> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/api-reference/readme/platform/agent-runs.md).

# Agent Runs

## Dispatch a framework agent run

> Proxies to agent-runner, where the chosen SDK owns its autonomous loop inside a platform-controlled prompt/model/tool/auth/timeout envelope. Capabilities come from Platform MCP under the caller's bearer. Non-blocking — poll GET /agent-runs/{run\_id} for the result.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateAgentRunRequest":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Platform-authored run: the service whose pinned config the agent runs."},"version_set":{"$ref":"#/components/schemas/NameString","description":"Named version set on the service whose pinned config the run uses (platform runs).","default":"release"},"framework":{"anyOf":[{"type":"string","enum":["claude-agent-sdk","openai-agents"]},{"type":"null"}],"title":"Framework","description":"Framework a PLATFORM run executes on. For a native run the framework comes from the definition."},"native":{"anyOf":[{"$ref":"#/components/schemas/NativeRunRef"},{"type":"null"}],"description":"Run a native (bring-your-own) agent definition instead of a platform service."},"message":{"type":"string","maxLength":8000,"minLength":1,"title":"Message","description":"User message the framework agent is invoked with."},"timeout_s":{"type":"integer","maximum":300,"exclusiveMinimum":0,"title":"Timeout S","description":"Server-side wall-clock budget for the run, in seconds (max 300).","default":120}},"type":"object","required":["message"],"title":"CreateAgentRunRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"NativeRunRef":{"properties":{"definition_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Definition Id","description":"Registered definition to run. Omit `version` for the latest."},"version":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Version","description":"Pinned definition version; omit for latest."},"inline":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Inline","description":"Inline definition document (dev/playground). Validated by the platform clamp schema."}},"type":"object","title":"NativeRunRef","description":"Run a customer-authored NATIVE agent definition (inc-10): a REGISTERED\ndefinition by id (``version`` omitted = latest), or an INLINE body for\ndev/playground iteration. The definition's own ``framework`` selects the\nruntime — no top-level ``framework`` needed."},"CreateAgentRunResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"status":{"type":"string","const":"running","title":"Status"}},"type":"object","required":["run_id","status"],"title":"CreateAgentRunResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-runs":{"post":{"tags":["Agent Runs"],"summary":"Dispatch a framework agent run","description":"Proxies to agent-runner, where the chosen SDK owns its autonomous loop inside a platform-controlled prompt/model/tool/auth/timeout envelope. Capabilities come from Platform MCP under the caller's bearer. Non-blocking — poll GET /agent-runs/{run_id} for the result.","operationId":"create_agent_run_v1__workspace_id__agent_runs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentRunRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Fetch the neutral session-bootstrap context for a service

> The retrievable CONTEXT edge of the world-model harness: identity + reference instructions, world scope, tool descriptors, guardrails, and an MCP write-policy summary. It shares the HarnessContext schema with the hosted harness but is not byte-identical to a hosted render: this REST path does not resolve the runner's engage-model preference. PHI-free (the API-run projection carries no scoped entities or rendered caller prose).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HarnessContext":{"properties":{"context_version":{"type":"integer","title":"Context Version","default":1},"config_fingerprint":{"type":"string","title":"Config Fingerprint","default":""},"source":{"type":"string","title":"Source","default":""},"identity":{"anyOf":[{"$ref":"#/components/schemas/AgentIdentity"},{"type":"null"}]},"world_scope":{"$ref":"#/components/schemas/WorldScope"},"tools":{"$ref":"#/components/schemas/Tools"},"guardrails":{"$ref":"#/components/schemas/Guardrails"},"write_floor":{"$ref":"#/components/schemas/WriteFloor"},"runtime":{"$ref":"#/components/schemas/Runtime"}},"type":"object","required":["world_scope","tools","guardrails","write_floor","runtime"],"title":"HarnessContext","description":"A framework-neutral, retrievable service bootstrap projection."},"AgentIdentity":{"properties":{"entry_actor_name":{"type":"string","title":"Entry Actor Name","default":""},"name":{"type":"string","title":"Name","default":""},"role":{"type":"string","title":"Role","default":""},"developed_by":{"type":"string","title":"Developed By","default":""},"instructions":{"type":"string","title":"Instructions","default":""},"initial_state":{"type":"string","title":"Initial State","default":""}},"type":"object","title":"AgentIdentity","description":"Who the agent IS — platform-authored only; ``None`` for native runs\n(a customer's own definition carries its own identity). Named\n``AgentIdentity`` (not ``Identity``) to avoid colliding with the existing\n``config.models.Identity`` OpenAPI schema (a same-name collision would\nforce-rename that shipped schema — a breaking spec change)."},"WorldScope":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"scoped_entity_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Scoped Entity Ids","default":[]},"allow_create":{"type":"boolean","title":"Allow Create","default":false}},"type":"object","required":["workspace_id"],"title":"WorldScope","description":"The world slice — ids only (the leaf stays I/O-free). This is the\nread/subject scope, NOT the write bound (see ``write_floor``).\n``allow_create`` records context intent and is not an authorization grant."},"Tools":{"properties":{"descriptors":{"items":{"$ref":"#/components/schemas/ToolDescriptor"},"type":"array","title":"Descriptors","default":[]},"read_tool_names":{"items":{"type":"string"},"type":"array","title":"Read Tool Names","default":[]},"write_tool_names":{"items":{"type":"string"},"type":"array","title":"Write Tool Names","default":[]}},"type":"object","title":"Tools","description":"Discovery hint — the neutral descriptors. NOT the enforcement (the MCP\nedge is; a remote agent discovers live schemas from the server too)."},"ToolDescriptor":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}}},"type":"object","required":["name"],"title":"ToolDescriptor"},"Guardrails":{"properties":{"guardrails":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Guardrails","default":[]},"global_boundary_constraints":{"items":{"type":"string"},"type":"array","title":"Global Boundary Constraints","default":[]},"global_action_guidelines":{"items":{"type":"string"},"type":"array","title":"Global Action Guidelines","default":[]}},"type":"object","title":"Guardrails"},"WriteFloor":{"properties":{"enforced_at":{"type":"string","title":"Enforced At","default":"mcp-world-tools-edge"},"requires_entity_anchor":{"type":"boolean","title":"Requires Entity Anchor","default":true},"clinical_write_principal":{"type":"string","title":"Clinical Write Principal","default":"provider-only"},"clinical_write_scope":{"type":"string","title":"Clinical Write Scope","default":"any-entity-in-workspace"},"enrichment_write_scope":{"type":"string","title":"Enrichment Write Scope","default":"caller-anchor-only"},"unanchored_or_api_key_writes":{"type":"string","title":"Unanchored Or Api Key Writes","default":"none"},"allow_create":{"type":"boolean","title":"Allow Create","default":false}},"type":"object","title":"WriteFloor","description":"A static summary of MCP write policy, advisory to the renderer.\n\nThe MCP edge resolves the caller's actual principal and enforces the\nresult. These fields do not grant write access; hosted runner credentials\nare currently unanchored and cannot perform provider-only clinical writes."},"Runtime":{"properties":{"engage_model":{"type":"string","title":"Engage Model","default":""},"channel_kind":{"type":"string","title":"Channel Kind","default":""},"language":{"type":"string","title":"Language","default":""},"caller_context":{"type":"string","title":"Caller Context","default":""}},"type":"object","title":"Runtime"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-runs/harness-context":{"get":{"tags":["Agent Runs"],"summary":"Fetch the neutral session-bootstrap context for a service","description":"The retrievable CONTEXT edge of the world-model harness: identity + reference instructions, world scope, tool descriptors, guardrails, and an MCP write-policy summary. It shares the HarnessContext schema with the hosted harness but is not byte-identical to a hosted render: this REST path does not resolve the runner's engage-model preference. PHI-free (the API-run projection carries no scoped entities or rendered caller prose).","operationId":"get_harness_context_v1__workspace_id__agent_runs_harness_context_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Service Id"}},{"name":"version_set","in":"query","required":false,"schema":{"type":"string","maxLength":255,"default":"release","title":"Version Set"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HarnessContext"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get a framework agent run

> Run status, final text, token usage, and the runner-normalized trajectory of framework-native output.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AgentRunDetail":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"status":{"type":"string","enum":["running","succeeded","failed","timed_out"],"title":"Status"},"framework":{"type":"string","enum":["claude-agent-sdk","openai-agents"],"title":"Framework"},"text":{"type":"string","title":"Text","description":"Final agent text. Empty while the run is still running or on failure.","default":""},"error":{"type":"string","title":"Error","description":"Failure detail for failed/timed_out runs. Empty otherwise.","default":""},"duration_ms":{"type":"number","minimum":0,"title":"Duration Ms","default":0},"usage":{"$ref":"#/components/schemas/Usage"},"trajectory":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Trajectory","description":"AgentEffect-shaped step dicts (kind, seq, content, tool_name, ...) — the runner normalizer's projection of framework-native output. Untyped passthrough in v1: the AgentEffect projection is a server-private shape still converging across frameworks; typing it here now would freeze a premature wire contract. A typed discriminated union lands in a follow-up.","default":[]}},"type":"object","required":["run_id","status","framework"],"title":"AgentRunDetail"},"Usage":{"properties":{"input_tokens":{"type":"integer","title":"Input Tokens","default":0},"output_tokens":{"type":"integer","title":"Output Tokens","default":0},"cached_tokens":{"type":"integer","title":"Cached Tokens","description":"Cache-READ input tokens (billed at the provider's cache-hit rate).","default":0},"cache_creation_tokens":{"type":"integer","title":"Cache Creation Tokens","description":"Cache-WRITE input tokens (Anthropic cache_creation_input_tokens; 0 on providers without it).","default":0}},"type":"object","title":"Usage"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/agent-runs/{run_id}":{"get":{"tags":["Agent Runs"],"summary":"Get a framework agent run","description":"Run status, final text, token usage, and the runner-normalized trajectory of framework-native output.","operationId":"get_agent_run_v1__workspace_id__agent_runs__run_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/agent-runs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.