Run and stream an agent

Use POST /api/v1/agents-v2/agents/{agent_id}/run-stream/ for a user-facing stream. Send a stable thread_id; Central Hub persists the chat and messages.

curl -N -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/run-stream/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Space-Slug: acme" \
  -H "Content-Type: application/json" \
  -d '{"thread_id":"contract-demo-1","message":"Summarize the renewal terms."}'

Consume events until the run completes. Use run status, events, history, and cancel endpoints for background integrations. Chats expose persisted history, summaries, plans, share links, and fork operations. Generated sandbox files are persisted to durable storage when delivered; do not assume an E2B path remains available after a run.

All of the run variants below are callable with an API key (X-API-Key + X-Space-Slug); add Accept: text/event-stream to consume the stream.

Run the default agent

To run the workspace's default agent without knowing its ID, omit the ID and pass ?default=true:

POST /api/v1/agents-v2/agents/run-stream/?default=true&save_history=true

save_history=false runs without persisting the chat (useful for one-off or background calls that should not appear in the chat list).

Per-run overrides (runtimeConfig)

For full control — including attaching connections or MCP servers for a single run — send the AG-UI RunAgentInput body and put overrides under forwardedProps.runtimeConfig. Every top-level key must be present (omitting state/tools/context returns 422):

curl -N -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/run-stream/?save_history=true" \
  -H "X-API-Key: $ALO_API_KEY" \
  -H "X-Space-Slug: $WORKSPACE_SLUG" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "contract-demo-1",
    "runId": "run-8f2c",
    "state": null,
    "messages": [{"id": "m1", "role": "user", "content": "Summarize the renewal terms."}],
    "tools": [],
    "context": [],
    "forwardedProps": {
      "mode": "act",
      "chatSource": "app",
      "runtimeConfig": {
        "connection_ids": [42],
        "mcp_connection_ids": [7],
        "tool_names": ["files-search"],
        "skill_slugs": ["contract-review"],
        "model_config_id": 12,
        "system_prompt": "You are a careful contract analyst."
      }
    }
  }'

runtimeConfig fields are all optional per-run overrides: system_prompt, tool_names, skill_slugs, skill_set_slugs, model_config_id, connection_ids (SQL connectors), mcp_connection_ids, and file_scope. Runtime connection IDs extend the agent's configured set rather than replacing it. mode is "act" (default) or "plan"; chatSource defaults to "app".

Test a draft configuration

To try an unsaved configuration without creating an agent row, use the default path with ?default=false&save_history=false and pass the full inline config in the body's forwardedProps.runtimeConfig. Nothing is persisted and the chat is never saved.

Attach files (vision and documents)

Upload a file, then reference it from the last user message. Upload returns {id, name, mime_type, size, presigned_url}:

curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/files/upload/" \
  -H "X-API-Key: $ALO_API_KEY" -H "X-Space-Slug: $WORKSPACE_SLUG" \
  -F "file=@contract.pdf;type=application/pdf"

Attach it by adding a content part to the last user message — {"type": "document", "source": {"type": "url", "id": "<id>", "name": "contract.pdf", "mimeType": "application/pdf", "value": "<presigned_url>"}} (use "type": "image" for images) — and by listing it under forwardedProps.files.

Download a generated file

Files an agent produces in its sandbox are addressed by their in-sandbox path for the same run. Fetch a pre-signed URL by passing the same agent_id and thread_id the run used:

GET /api/v1/agents-v2/agents/{agent_id}/sandbox/files/presigned-url/?path=<sandbox_path>&thread_id=<thread_id>&expires_in_seconds=600

The response is {"url": "<pre-signed URL>"}. Persisted generated files are also delivered as FILE_GENERATED stream events during the run.