Agent Runs

List framework agent runs

get

Paginated list of framework agent runs for the workspace, newest first, read from the durable world.agent_runs read model. Filter by framework / status. continuation_token is an opaque page cursor.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

frameworkstring · enum · nullableOptionalPossible values:

statusstring · enum · nullableOptionalPossible values:

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

422

Validation Error

application/json

get/v1/{workspace_id}/agent-runs

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agent-runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "run_id": "text",
      "framework": "claude-agent-sdk",
      "status": "text",
      "origin_source": "text",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "input_tokens": 0,
      "output_tokens": 0,
      "step_count": 0,
      "duration_ms": 1,
      "started_at": "text",
      "created_at": "text"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Dispatch a framework agent run

post

Proxies to agent-runner, which executes the chosen framework UNMODIFIED (natural setup) against the platform MCP world-tools edge under the caller's own bearer. Non-blocking — poll GET /agent-runs/{run_id} for the result.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

service_idstring · uuid · nullableOptional

Platform-authored run: the service whose pinned config the agent runs.

version_setstring · min: 1 · max: 256Optional

Named version set on the service whose pinned config the run uses (platform runs).

Default: release

frameworkstring · enum · nullableOptional

Framework a PLATFORM run executes on. For a native run the framework comes from the definition.

Possible values:

messagestring · min: 1 · max: 8000Required

User message the framework agent is invoked with.

timeout_sinteger · max: 300Optional

Server-side wall-clock budget for the run, in seconds (max 300).

Default: 120

Responses

202

Successful Response

application/json

run_idstring · uuidRequired

statusconst: runningRequired

422

Validation Error

application/json

post/v1/{workspace_id}/agent-runs

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/agent-runs HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "version_set": "release",
  "framework": "claude-agent-sdk",
  "native": {
    "definition_id": "123e4567-e89b-12d3-a456-426614174000",
    "version": 1,
    "inline": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "message": "text",
  "timeout_s": 120
}

{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "text"
}

Fetch the neutral session-bootstrap context for a service

get

The retrievable CONTEXT edge of the world-model harness: identity + reference instructions, world scope, tool descriptors, guardrails, and the REAL server-enforced write-floor — the byte-identical projection the hosted runner renders from, so a customer's own framework can bootstrap a session against the same world model. PHI-free (the API-run projection carries no scoped entities or rendered caller prose).

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

service_idstring · uuidRequired

version_setstring · max: 255OptionalDefault: release

Responses

200

Successful Response

application/json

The neutral, retrievable session-bootstrap context for ANY framework.

context_versionintegerOptionalDefault: 1

config_fingerprintstringOptionalDefault: ""

sourcestringOptionalDefault: ""

422

Validation Error

application/json

get/v1/{workspace_id}/agent-runs/harness-context

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agent-runs/harness-context?service_id=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "context_version": 1,
  "config_fingerprint": "",
  "source": "",
  "identity": {
    "entry_actor_name": "",
    "name": "",
    "role": "",
    "developed_by": "",
    "instructions": "",
    "initial_state": ""
  },
  "world_scope": {
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "scoped_entity_ids": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "allow_create": false
  },
  "tools": {
    "descriptors": [
      {
        "name": "text",
        "description": "",
        "input_schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    ],
    "read_tool_names": [
      "text"
    ],
    "write_tool_names": [
      "text"
    ]
  },
  "guardrails": {
    "guardrails": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "global_boundary_constraints": [
      "text"
    ],
    "global_action_guidelines": [
      "text"
    ]
  },
  "write_floor": {
    "enforced_at": "mcp-world-tools-edge",
    "requires_entity_anchor": true,
    "clinical_write_principal": "provider-only",
    "clinical_write_scope": "any-entity-in-workspace",
    "enrichment_write_scope": "caller-anchor-only",
    "unanchored_or_api_key_writes": "none",
    "allow_create": false
  },
  "runtime": {
    "engage_model": "",
    "channel_kind": "",
    "language": "",
    "caller_context": ""
  }
}

Get a framework agent run

get

Run status, final text, token usage, and the adapter-normalized trajectory of the framework's native output.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

run_idstring · uuidRequired

Responses

200

Successful Response

application/json

run_idstring · uuidRequired

statusstring · enumRequiredPossible values:

frameworkstring · enumRequiredPossible values:

textstringOptional

Final agent text. Empty while the run is still running or on failure.

Default: ""

errorstringOptional

Failure detail for failed/timed_out runs. Empty otherwise.

Default: ""

duration_msnumberOptionalDefault: 0

422

Validation Error

application/json

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

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/agent-runs/{run_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "run_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "framework": "claude-agent-sdk",
  "text": "",
  "error": "",
  "duration_ms": 0,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cached_tokens": 0,
    "cache_creation_tokens": 0
  },
  "trajectory": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ]
}