Agent Runs

Dispatch and poll framework agent runs that execute unmodified against the platform world-tools surface.

Agent runs let you execute a partner agent framework against your workspace's world-tools surface in a single API call. The chosen framework runs unmodified in its own design - the platform meets it at open edges only: authored agent configuration for initialization, the world-tools data surface for tools, and a normalized trajectory of the framework's native output.

Two frameworks are supported:

Framework	Value	Notes
Claude Agent SDK	claude-agent-sdk	Runs the Claude Agent SDK autonomously against world tools
OpenAI Agents SDK	openai-agents	Runs the OpenAI Agents SDK autonomously against world tools

Dispatch a Run

POST /v1/{workspace_id}/agent-runs

Dispatches a framework agent run. Returns immediately with a run ID and running status (HTTP 202). The framework executes asynchronously on the server under the specified timeout budget.

A run is either a platform run (provide service_id + framework) or a native run (provide native, referencing a registered agent definition or an inline definition body). Provide exactly one of the two; a request with both or neither is rejected.

Request Body

Field	Type	Required	Description
service_id	string (UUID)	Platform runs	Service whose agent configuration the run uses.
version_set	string	No	Named version set on the service (platform runs). Defaults to release.
framework	string	Platform runs	Agent framework to execute: claude-agent-sdk or openai-agents. For a native run the framework comes from the definition.
native	object	Native runs	Runs a native agent definition instead of a platform service. Provide exactly one of native.definition_id (with optional native.version; omit for the latest version) or native.inline (an inline definition body, validated against the same clamp schema as registration).
message	string	Yes	User message the framework agent is invoked with. 1-8000 characters.
timeout_s	integer	No	Server-side wall-clock budget in seconds. 1-300, defaults to 120.

Response (202 Accepted)

Field	Type	Description
run_id	string (UUID)	Unique identifier for the dispatched run.
status	string	Always running on creation.

Example

curl -X POST https://api.platform.amigo.ai/v1/{workspace_id}/agent-runs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "a1b2c3d4-...",
    "framework": "openai-agents",
    "message": "What appointments does the patient have this week?",
    "timeout_s": 120
  }'

{
  "run_id": "e5f6a7b8-...",
  "status": "running"
}

Get a Run

GET /v1/{workspace_id}/agent-runs/{run_id}

Returns the current status of a run, including the final text, token usage, and the normalized trajectory of the framework's native output once the run completes.

Path Parameters

Parameter	Type	Description
workspace_id	string (UUID)	Workspace ID.
run_id	string (UUID)	Run ID returned by the dispatch call.

Response

Field	Type	Description
run_id	string (UUID)	Run identifier.
status	string	One of running, succeeded, failed, timed_out.
framework	string	Framework that executed the run.
text	string	Final agent text. Empty while running or on failure.
error	string	Failure detail for failed or timed_out runs. Empty otherwise.
duration_ms	number	Wall-clock duration of the run in milliseconds.
usage	object	Token usage: input_tokens, output_tokens, cached_tokens (cache-read input tokens, billed at the provider's cache-hit rate), and cache_creation_tokens (cache-write input tokens; 0 on providers without cache-write accounting).
trajectory	array	Normalized trajectory steps from the framework's native output. Each step includes a kind (such as transcript, tool_call, decision, completion, usage), a seq number, and kind-specific fields.

Run Statuses

Status	Description
running	The framework is still executing. Poll again.
succeeded	The run completed. text, usage, and trajectory are populated.
failed	The run encountered an error. See error for details.
timed_out	The run exceeded its timeout_s budget.

Example

curl https://api.platform.amigo.ai/v1/{workspace_id}/agent-runs/{run_id} \
  -H "Authorization: Bearer $API_KEY"

{
  "run_id": "e5f6a7b8-...",
  "status": "succeeded",
  "framework": "openai-agents",
  "text": "The patient has two appointments this week...",
  "error": "",
  "duration_ms": 4523.1,
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 340,
    "cached_tokens": 800,
    "cache_creation_tokens": 200
  },
  "trajectory": [
    {
      "kind": "tool_call",
      "seq": 0,
      "tool_name": "world_read"
    },
    {
      "kind": "transcript",
      "seq": 1,
      "content": "The patient has two appointments this week..."
    },
    {
      "kind": "completion",
      "seq": 2
    },
    {
      "kind": "usage",
      "seq": 3
    }
  ]
}

Authentication

Both endpoints require a workspace API key (Authorization: Bearer ...). The key must belong to the workspace in the URL path. The caller's credential is forwarded to the world-tools surface, so all data access executes under the caller's own workspace permissions.

Rate Limits

The dispatch endpoint is subject to write rate limits. The get endpoint is subject to read rate limits. Standard workspace rate limit headers apply.

Notes

• Runs are non-blocking. Dispatch returns immediately; poll the get endpoint for results.
• The timeout_s budget covers the entire run (configuration loading and framework execution). If the framework does not complete within the budget, the run transitions to timed_out.
• The trajectory is a normalized representation of the framework's native output. The shape is consistent across frameworks but may evolve. Treat individual step fields as informational.
• Each framework runs on the version set's pinned engage model when that model belongs to the framework's own provider (an OpenAI model for openai-agents, an Anthropic model for claude-agent-sdk). Otherwise the run falls back to a platform default model for that framework.