Agents

Run an agent with configuration

Run an agent with inline configuration or existing agent reference. Supports A2A messages, memory context, tool execution, and model fallback.

post/v2/agents/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.

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

Agent execution initiated successfully. Returns task details including the task ID, execution status, and agent response. The task ID can be used to track execution progress and retrieve results.

idstring required

The unique ID of the created agent execution task

contextIdstring required

The correlation ID for this execution (used for tracking)

kind'task' required

A2A entity type identifier

metadataobject

Task metadata containing workspace_id and trace_id for feedback and tracking

Changes

Changed in 185 of the 261 revisions of this API.4567318

Sep 2, 2026c4473310c0131See the full diff
- ○
  the request property default value changed from 01M1GDMJX1FSP0DZFG1P3T197A to 01M1GG3ZM6N814CYYJMXEXSZAJ
  request-property-default-value-changed
Sep 2, 2026cb6c448ef6371See the full diff
- ○
  the request property default value changed from 01M1ECMMTM3ZJ12MBDZMP0EFZM to 01M1GDMJX1FSP0DZFG1P3T197A
  request-property-default-value-changed
Sep 1, 2026359a7831a2f02See the full diff
- ○
  the request property default value changed from 01M1DZ6W5MR62NHR6FPCS17VKD to 01M1ECMMTM3ZJ12MBDZMP0EFZM
  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
Sep 1, 202666b8a490291111See the full diff
- ▲
  removed from the // request property oneOf list
  request-property-one-of-removed
- ○
  the request property default value changed from 01M1DS3XKZ334F6K69Q18F7MBR to 01M1DZ6W5MR62NHR6FPCS17VKD
  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
Sep 1, 2026081200e02fe02See the full diff
- ○
  the request property default value changed from 01M1D09EGJCFG5T2VVRTESSXB3 to 01M1DS3XKZ334F6K69Q18F7MBR
  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
Aug 31, 2026b22330eb2d5a11See the full diff
- ▲
  removed from the // request property oneOf list
  request-property-one-of-removed
- ○
  the request property default value changed from 01M1BS0MBP78QVTN74A32X1W7X to 01M1D09EGJCFG5T2VVRTESSXB3
  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
Aug 31, 202694a16765e3fe1See the full diff
- ○
  the request property default value changed from 01M1BBCBE71SSSP29HBX33QJ1E to 01M1BS0MBP78QVTN74A32X1W7X
  request-property-default-value-changed
Aug 31, 20263a2f6c296c092See the full diff
- ○
  the request property default value changed from 01M151RV9B0GPP12VSFXS0J6D0 to 01M1BBCBE71SSSP29HBX33QJ1E
  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
Aug 28, 20269642bb8e4f8311See the full diff
- ▲
  removed from the // request property oneOf list
  request-property-one-of-removed
- ○
  the request property default value changed from 01M11P4TR7TWJBMSC2TD9QCXVS to 01M151RV9B0GPP12VSFXS0J6D0
  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
Aug 27, 2026c9228554b8331See the full diff
- ○
  the request property default value changed from 01M114XDSYDQRM345CW2C35FXE to 01M11P4TR7TWJBMSC2TD9QCXVS
  request-property-default-value-changed

Of the 261 revisions, 73 have no diff computed.

Full history (185 revisions)