Anthropic Managed Agents

The Managed Agents adapter models a conversation as an event-sourced session: you create a session, post user events into it, and stream back an ordered agent.* event log. It maps Karta’s typed events onto the Anthropic managed-agent shape. Auth: a session token or a kt_live_... key.

Create a session

POST /{org}/{agent}/v1/managed-agents/sessions The body is optional. Pass a metadata object to carry your own end-user id for per-visitor continuity.

metadata

object

Optional client metadata. metadata.end_user_id is used for per-visitor continuity when the caller is anonymous or soft-identified; a verified session token’s sub remains authoritative.

prewarm

boolean

Defaults to true. Set false when your client will open the visible warm stream before the first turn.

curl -X POST https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"end_user_id": "u_42"}}'
# -> 201 { "id": "sess_9f3a...", "object": "session", "status": "idle" }

Warm before first turn

Optional, before the first turn: ask Karta to start the agent ahead of time so the first response is not delayed by startup. Two shapes are available: fire-and-forget, or an observable stream. Warming is best-effort and never required; if you skip it, the first turn starts the agent as needed. POST /{org}/{agent}/v1/managed-agents/sessions/{session_id}/prewarm Returns immediately; the agent keeps warming in the background.

curl -X POST https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions/$SID/prewarm \
  -H "Authorization: Bearer $SESSION_TOKEN"
# -> 202 { "status": "warming" }

GET /{org}/{agent}/v1/managed-agents/sessions/{session_id}/warm Streams the readiness lifecycle as Server-Sent Events, so a UI can show a “getting ready” state and proceed once the agent is ready:

curl -N https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions/$SID/warm \
  -H "Authorization: Bearer $SESSION_TOKEN"

It emits warming (repeated as a heartbeat while the agent starts) and then a terminal ready - or error if warming failed, in which case you can still send the turn and it pays the cold start. The widget SDK wraps this as KartaAgentClient.warm(), which yields a WarmEvent stream (warming | ready | error).

List sessions

GET /{org}/{agent}/v1/managed-agents/sessions?end_user=<id> Returns prior conversations for the current end user, newest activity first:

{
  "object": "list",
  "data": [
    { "id": "sess_9f3a...", "object": "session", "status": "idle" }
  ]
}

If the caller uses a verified session token, Karta uses the verified sub. Anonymous callers must pass their stable end_user value and possess the session id to reopen a transcript.

Post an event

POST /{org}/{agent}/v1/managed-agents/sessions/{session_id}/events Posting a user event spawns the turn in the background and returns immediately; you observe the result on the event stream.

type

string

required

user.message, user.tool_confirmation, or user.interrupt.

text

string

The message text - required for user.message.

tool_use_id

string

Optional tool reference.

request_id

string

Required for user.tool_confirmation - the approval being answered.

result

string

approve_once, approve_session, or deny - required for user.tool_confirmation (allow still works as an alias for approve_once). A user.tool_confirmation without both result and request_id is a 400.

curl -X POST https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions/$SID/events \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "user.message", "text": "What roasts do you have?"}'
# -> 202 { "accepted": true }

Approve a pending tool use:

curl -X POST .../sessions/$SID/events \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "user.tool_confirmation", "request_id": "req_7c1...", "result": "approve_once"}'

Stream events

GET /{org}/{agent}/v1/managed-agents/sessions/{session_id}/events/stream Streams agent.* events as the turn runs. Pass ?after=<seq> to resume from a known sequence number - the log is ordered and replayable.

curl -N "https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions/$SID/events/stream?after=0" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Warm before first turn

Managed-agent sessions can start the agent runtime before the first user message. Use this for chat UIs that want a faster first turn or a visible “warming up” state.

Path	Use	Result
`POST /{org}/{agent}/v1/managed-agents/sessions/{session_id}/prewarm`	Fire-and-forget warmup from input focus or page idle time.	Returns `202 { "status": "warming" }` and continues in the background. If warmup misses, the first turn still runs and may take longer.
`GET /{org}/{agent}/v1/managed-agents/sessions/{session_id}/warm`	Visible warmup before enabling the composer.	Streams `warm` SSE events with `{"status":"warming"}` heartbeats, then `{"status":"ready"}` or `{"status":"error"}`.

When creating the session, leave prewarm at its default for hidden background warmup. Set prewarm: false only when your UI immediately opens the visible /warm stream and wants that stream to own the progress indicator.

curl -X POST https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions/$SID/prewarm \
  -H "Authorization: Bearer $SESSION_TOKEN"
# -> 202 { "status": "warming" }

curl -N https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions/$SID/warm \
  -H "Authorization: Bearer $SESSION_TOKEN"

Upload a file for the next turn

POST /{org}/{agent}/v1/managed-agents/sessions/{session_id}/files Stages a user upload for the next user.message turn. The agent sees the file under uploads/<name>.

name

string

required

Original filename. Karta stores it as a basename under uploads/.

content_base64

string

required

Base64-encoded file bytes.

{ "accepted": true, "path": "uploads/menu.pdf" }

Fetch session state

GET /{org}/{agent}/v1/managed-agents/sessions/{session_id}

{
  "id": "sess_9f3a...",
  "object": "session",
  "status": "idle",
  "events": [
    { "seq": 1, "type": "session.status_running" },
    { "seq": 2, "type": "agent.message", "text": "We've got Sunrise, ..." },
    { "seq": 3, "type": "session.status_idle", "stop_reason": "end_turn", "usage": { ... } }
  ]
}

status is idle or running; events is the ordered log so far.

Fetch transcript

GET /{org}/{agent}/v1/managed-agents/sessions/{session_id}/transcript Returns the compact transcript for reopening a past conversation:

{
  "session_id": "sess_9f3a...",
  "messages": [
    { "role": "user", "text": "What roasts do you have?" },
    { "role": "assistant", "text": "We've got Sunrise, Midnight, and Decaf Dusk." }
  ]
}

Verified callers are scoped by the token subject. Anonymous callers pass the same stable end_user value used for listing.

MCP app proxy

POST /{org}/{agent}/v1/managed-agents/mcp Use this only when building an MCP Apps host for a Managed Agents session. Put the active session id in X-Karta-Session, and post the MCP method and params:

{ "method": "tools/call", "params": { "name": "lookup", "arguments": {} } }

Karta returns the JSON result from the agent session. The browser never receives the MCP server credential. The agent emits agent.message (agent text), agent.thinking, agent.tool_use, and agent.tool_result. A turn opens with session.status_running and ends with a terminal session.status_idle (carrying stop_reason and usage) or session.error. When the agent pauses for a tool approval, the terminal session.status_idle carries stop_reason: "requires_action" plus the request_id to answer with a user.tool_confirmation event.

Why event-sourced

This shape suits clients that prefer post-and-observe over request/response: a UI posts a user message, then renders the agent’s agent.* events as they arrive - including tool-confirmation prompts it answers with a follow-up event. The ordered, replayable log makes reconnection and catch-up straightforward (after=<seq>).

Status codes

201 (create), 202 (event or prewarm accepted), 400 (bad body), 401, 402, 403, 404 (unknown agent / no active release), 409 (release not materialized). The visible warm stream reports readiness or timeout as warm events. See Errors.

Overview

Sessions

Consumer adapters

Anthropic Managed Agents

Create a session

Warm before first turn

List sessions

Post an event

Stream events

Warm before first turn

Upload a file for the next turn

Fetch session state

Fetch transcript

MCP app proxy

Why event-sourced

Status codes

​Create a session

​Warm before first turn

​List sessions

​Post an event

​Stream events

​Warm before first turn

​Upload a file for the next turn

​Fetch session state

​Fetch transcript

​MCP app proxy

​Why event-sourced

​Status codes

Create a session

Warm before first turn

List sessions

Post an event

Stream events

Warm before first turn

Upload a file for the next turn

Fetch session state

Fetch transcript

MCP app proxy

Why event-sourced

Status codes