Sign in
Agents

Run agent with streaming response

Run an agent with streaming via SSE, combining inline configuration with real-time updates including messages, tool executions, and status.

post/v2/agents/stream-run

Request body

keystring required

A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed.

task_idstring

Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.

rolestring required

Specifies the agent's function and area of expertise.

instructionsstring required

Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.

variablesobject

Optional variables for template replacement in system prompt, instructions, and messages

pathstring required

Entity storage path.

With workspace-level API keys, use the format project/folder/subfolder/.... The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: Default Project/agents.

With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: agents. For backward compatibility, a leading project name is ignored when it matches the scoped project.

descriptionstring

A brief summary of the agent's purpose.

system_promptstring nullable

A custom system prompt template for the agent. If omitted, the default template is used.

memory_storesstring[]

Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.

metadataobject

Optional metadata for the agent run as key-value pairs that will be included in traces

engine'text' | 'jinja' | 'mustache'

Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax.

stream_timeout_secondsnumber

Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)

Example request

{
  "model": {
    "parameters": {
      "fallbacks": [
        {
          "model": "openai/gpt-4o-mini"
        }
      ],
      "cache": {
        "ttl": 3600
      },
      "load_balancer": {
        "type": "weight_based",
        "models": [
          {
            "model": "openai/gpt-4o",
            "weight": 0.7
          },
          {
            "model": "anthropic/claude-3-5-sonnet",
            "weight": 0.3
          }
        ]
      },
      "timeout": {
        "call_timeout": 30000
      }
    },
    "retry": {
      "count": 3,
      "on_codes": [
        429,
        500,
        502,
        503,
        504
      ]
    }
  },
  "fallback_models": [
    {
      "parameters": {
        "fallbacks": [
          {
            "model": "openai/gpt-4o-mini"
          }
        ],
        "cache": {
          "ttl": 3600
        },
        "load_balancer": {
          "type": "weight_based",
          "models": [
            {
              "model": "openai/gpt-4o",
              "weight": 0.7
            },
            {
              "model": "anthropic/claude-3-5-sonnet",
              "weight": 0.3
            }
          ]
        },
        "timeout": {
          "call_timeout": 30000
        }
      },
      "retry": {
        "count": 3,
        "on_codes": [
          429,
          500,
          502,
          503,
          504
        ]
      }
    }
  ],
  "identity": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "thread": {
    "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "tags": [
      "customer-support",
      "priority-high"
    ]
  },
  "path": "Default Project",
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ]
}

Response

Server-Sent Event stream successfully established. Delivers real-time agent execution events including message fragments, tool invocations, intermediate results, and completion status. Stream terminates with [DONE] sentinel upon completion.

Changes

Changed in 186 of the 267 revisions of this API.4581338

  • 51df0153af4f1See the full diff
    • ○

      the request property default value changed from 01M1KBNSANXJWM1WAC5XFT24TV to 01M1KFH7X35CQ548G4SJY2P6YH

      request-property-default-value-changed

  • c4473310c0131See the full diff
    • ○

      the request property default value changed from 01M1GDMJXPN10CCG62EN570CB3 to 01M1GG3ZN1HXSWEETC398SDXXW

      request-property-default-value-changed

  • cb6c448ef6371See the full diff
    • ○

      the request property default value changed from 01M1ECMMVCTM4E2TRHQA5DVFGG to 01M1GDMJXPN10CCG62EN570CB3

      request-property-default-value-changed

  • 359a7831a2f02See the full diff
    • ○

      the request property default value changed from 01M1DZ6W7287MTSS0BNZHR8MM3 to 01M1ECMMVCTM4E2TRHQA5DVFGG

      request-property-default-value-changed

    • ○

      added to the // request property oneOf list

      request-property-one-of-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 66b8a490291111See the full diff
    • ▲

      removed from the // request property oneOf list

      request-property-one-of-removed

    • ○

      the request property default value changed from 01M1DS3XMQY7CRW47TCJ7F45DC to 01M1DZ6W7287MTSS0BNZHR8MM3

      request-property-default-value-changed

    This revision also has 65 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 081200e02fe02See the full diff
    • ○

      the request property default value changed from 01M1D09EHMER0837FZDB41GHSM to 01M1DS3XMQY7CRW47TCJ7F45DC

      request-property-default-value-changed

    • ○

      added to the // request property oneOf list

      request-property-one-of-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • b22330eb2d5a11See the full diff
    • ▲

      removed from the // request property oneOf list

      request-property-one-of-removed

    • ○

      the request property default value changed from 01M1BS0MCFXWB35MRYTA0TEEX7 to 01M1D09EHMER0837FZDB41GHSM

      request-property-default-value-changed

    This revision also has 61 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 94a16765e3fe1See the full diff
    • ○

      the request property default value changed from 01M1BBCBESP0377N45TCTK2748 to 01M1BS0MCFXWB35MRYTA0TEEX7

      request-property-default-value-changed

  • 3a2f6c296c092See the full diff
    • ○

      the request property default value changed from 01M151RVA37AG5VQAAK2Y2B3TE to 01M1BBCBESP0377N45TCTK2748

      request-property-default-value-changed

    • ○

      added to the // request property oneOf list

      request-property-one-of-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9642bb8e4f8311See the full diff
    • ▲

      removed from the // request property oneOf list

      request-property-one-of-removed

    • ○

      the request property default value changed from 01M11P4TSB6BW5664QJHP89FVJ to 01M151RVA37AG5VQAAK2Y2B3TE

      request-property-default-value-changed

    This revision also has 39 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 267 revisions, 78 have no diff computed.