Agents

Agents are AI assistants that can chat with users and execute tools.

Defining Agents

agent "assistant" {
  model       = models.anthropic.claude_sonnet_4
  personality = "Friendly, helpful, and concise"
  tools       = [
    builtins.http.get,
    tools.weather
  ]
}

Attributes

Tools

Agents can use three types of tools:

Built-in Tools

tools = [
  builtins.http.get,       # HTTP GET
  builtins.http.post,      # HTTP POST
  builtins.http.put,       # HTTP PUT
  builtins.http.patch,     # HTTP PATCH
  builtins.http.delete,    # HTTP DELETE
]

Custom Tools

Reference tools defined in tool blocks:

tools = [
  tools.weather,
  tools.create_todo
]

External Plugin Tools

Reference tools from loaded plugins:

tools = [
  plugins.slack.send_message,
  plugins.github.create_issue
]

MCP Server Tools

Reference tools from a declared mcp "name" server through the mcp.<name>.* namespace. Use .all to expose every tool the server provides:

tools = [
  mcp.filesystem.read_text_file,   # single tool
  mcp.remote_api.all,              # every tool from that server
]

See MCP Tools for how to declare consumer-side MCP servers.

Mission-Scoped Agents

Agents can be defined inside a mission block, making them available only to that mission. This is useful for specialized agents that don’t make sense as global definitions.

mission "research" {
  commander { model = models.anthropic.claude_sonnet_4 }
 
  agent "specialist" {
    model       = models.anthropic.claude_opus_4
    personality = "Deep domain expert"
    tools       = [plugins.shell.exec]
  }
 
  agents = [agents.global_helper, agents.specialist]
 
  task "gather" {
    objective = "Research the topic"
    # No agents attribute — task inherits the mission's list,
    # so both `global_helper` and `specialist` are available.
  }
 
  task "deep_dive" {
    objective = "Run the specialized analysis"
    agents    = [agents.specialist]  # Restrict this task to one agent.
  }
}

Mission-scoped agents use the same syntax and attributes as global agents. They must be listed in the mission’s agents = [...] to be available — once listed there, every task in the mission can use them automatically. A task only needs its own agents = [...] attribute when you want to restrict that task to a different subset.

Rules:

• A scoped agent name must not conflict with any global agent name
• Two different missions can each define an agent with the same name (they are independently scoped)
• Multiple scoped agents per mission are supported

Example: Specialized Agents

agent "coder" {
  model       = models.anthropic.claude_sonnet_4
  personality = "Precise and methodical"
  tools       = [builtins.http.get]
}
 
agent "researcher" {
  model       = models.openai.gpt_4o
  personality = "Curious and thorough"
  tools       = [builtins.http.get]
}
 
agent "writer" {
  model       = models.anthropic.claude_sonnet_4
  personality = "Creative and articulate"
  tools       = []  # No tools, just conversation
}

Built-in Tools

All agents automatically have access to result tools for handling large data:

When a tool returns a result larger than the configured threshold (default: ~16,000 tokens), it’s automatically stored and a sample is shown. The agent can use these tools to access the full data without overwhelming context.

In mission context, result_to_dataset is also available to promote arrays to datasets.

Tool Response Limits

You can configure the maximum token count for tool call responses before they’re truncated and stored for paged access:

agent "data_processor" {
  model = models.anthropic.claude_sonnet_4
  tools = [builtins.http.get]
 
  tool_response {
    max_tokens = 32000  # override the default 16,000 token limit
  }
}

When a response exceeds max_tokens, it’s stored in memory and the LLM receives a preview with metadata. The agent can then use result_* tools to access the full data.

The same setting is available on the mission commander:

mission "example" {
  commander {
    model = models.anthropic.claude_sonnet_4
    tool_response {
      max_tokens = 32000
    }
  }
}

Reasoning

Use the optional reasoning attribute to enable native provider reasoning (“extended thinking” on Anthropic, reasoning_effort on OpenAI, thinking_config on Gemini). Valid values: "low", "medium", "high".

agent "researcher" {
  model       = models.anthropic.claude_opus_4_7
  personality = "Methodical analyst"
  reasoning   = "high"
  tools       = [builtins.http.get]
}

The same attribute is available on the mission commander:

mission "complex_orchestration" {
  commander {
    model     = models.anthropic.claude_sonnet_4_6
    reasoning = "medium"
  }
  agents = [agents.researcher]
  task "investigate" { objective = "Find the root cause" }
}

Per-provider behaviour:

Models that don’t support native reasoning silently ignore the reasoning attribute and log a warning at agent startup. They produce direct answers with no reasoning step; there is no chain-of-thought fallback.

OpenAI / Ollama use the Responses API. Squadron talks to OpenAI and OpenAI-compatible servers (Ollama, vLLM, LiteLLM) over /v1/responses, not the legacy /v1/chat/completions. The Responses API is what surfaces reasoning summaries on o-series and gpt-5 models. Ollama supports /v1/responses since v0.13.3 — older versions will need to be upgraded.

Token budgets (for providers that accept a budget): low ≈ 2 048 tokens, medium ≈ 8 192, high ≈ 24 576. For Anthropic, the provider clamps max_tokens upward when needed so the budget fits.