OpenAPI 3.1.0raw.githubusercontent.com2026-08-202766453.1 MB

f7a624eccddb

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