Agents

Agents and all of their behaviors are defined in the orchestrator block in the workflow configuration. This page covers the top-level orchestrator agent and optional nested service_agents, which follow exactly the same schema.

Orchestrator and service agents

A workflow is structured by specifying an orchestrator agent and (optionally) some service agents. The orchestrator is the primary entry point for the workflow and has all of the standard components of a regular agent, but it can also delegate tasks to service agents, which are optional specialists configured under orchestrator.service_agents.

If you omit service_agents or leave it empty, all reasoning and tool use stay in the orchestrator—effectively creating a single-agent setup.

note

A workflow configuration defines, at most, one orchestrator and does not support nesting service agents under other service agents.

Service agents do not call each other; only the orchestrator coordinates them.

Example

The orchestrator block is required. The orchestrator and each service_agents item share name, model_settings, system_prompt, and optional mcp_tools, chariot_tools, and tool_retries. Only the orchestrator also has service_agents.

This configuration defines an orchestrator travel booking assistant with two service_agents that help with flights and hotels.

{
  "name": "Booking Assistant",
  "orchestrator": {
    "name": "Booking Assistant",
    "model_settings": {
      "ai_provider": "openai",
      "name": "gpt-5-mini",
      "api_key": {
        "owner_type": "project",
        "owner_id": "<your-project-id>",
        "path": "secret/Custom/<openai-api-key-secret-id>/value"
      }
    },
    "system_prompt": "You are a helpful assistant that coordinates bookings. Route flight questions to the Travel Agent and hotel questions to the Hotel Agent.",
    "tool_retries": 3,
    "mcp_tools": {},
    "chariot_tools": {},
    "service_agents": [
      {
        "name": "Travel Agent",
        "model_settings": {
          "ai_provider": "openai",
          "name": "gpt-5-nano",
          "api_key": {
            "owner_type": "project",
            "owner_id": "<your-project-id>",
            "path": "secret/Custom/<openai-api-key-secret-id>/value"
          }
        },
        "system_prompt": "You are a helpful assistant that checks flight costs. Return flight options only; do not complete purchases.",
        "tool_retries": 2,
        "mcp_tools": {}
      },
      {
        "name": "Hotel Agent",
        "model_settings": {
          "ai_provider": "openai",
          "name": "gpt-5-nano",
          "api_key": {
            "owner_type": "project",
            "owner_id": "<your-project-id>",
            "path": "secret/Custom/<openai-api-key-secret-id>/value"
          }
        },
        "system_prompt": "You are a helpful assistant that checks hotel availability. Return hotel options only; do not complete purchases.",
        "mcp_tools": {}
      }
    ]
  }
}

Orchestrator fields

name

The name that identifies this agent in the workflow.

note

The workflow name must match the orchestrator.name in the configuration for it to be valid.

model_settings (optional)

The AI model this agent uses and its settings. See Models.

system_prompt

The instructions this agent will follow when it receives a request.

tool_retries (optional)

How many times Chariot retries a tool call after a recoverable failure for this agent. Defaults to 3 if omitted.

mcp_tools and chariot_tools (optional)

• MCP tools: External MCP servers listed under mcp_tools.
• Chariot tools: Tools from Chariot packages under chariot_tools, reached through Chariot’s MCP server.

See Tools for full schema details.

service_agents (optional)

Extra agents the orchestrator can call.