> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `<path>.md`.

# Agents

Role-specific agent constructors. Each returns an
[`AgentSpec`](/docs/reference/runtime#flowai_harness.runtime.AgentSpec) that
`define_runtime(...)` composes into a [`RuntimeSpec`](/docs/reference/runtime#flowai_harness.runtime.RuntimeSpec).

<span id="flowai_harness.agents.define_coordinator"></span>

## `define_coordinator`

`define_coordinator(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', routes: 'Iterable[str]' = (), tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>model</code></td>
<td><code>ModelInput</code></td>
<td>required</td>
</tr>
<tr>
<td><code>prompt</code></td>
<td><code>str | LayeredPrompt</code></td>
<td>required</td>
</tr>
<tr>
<td><code>routes</code></td>
<td><code>Iterable[str]</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td><code>tools</code></td>
<td><code>Iterable[ToolSpec]</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td><code>stateful</code></td>
<td><code>bool | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>max_turns</code></td>
<td><code>int | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>approval</code></td>
<td><code>ApprovalPolicyPatch | Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>tool_approvals</code></td>
<td><code>Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>toolkits</code></td>
<td><code>Iterable[str] | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>AgentSpec</code></p>

Define a coordinator agent spec.

The coordinator is the user-facing entrypoint agent. It owns the
conversation thread and hands work off to the agents named in ``routes``.

Args:
    name: Unique agent name within the runtime spec.
    model: Model selection: a model id string, a ``ModelSpec``, or a
        mapping with ``id`` and optional ``provider``.
    prompt: System prompt as a string or a ``LayeredPrompt``. A
        ``LayeredPrompt`` also contributes its deterministic prompt cache
        key.
    routes: Names of agents this coordinator can hand off to. At least
        one route is required; every route must name an agent registered
        in the same runtime spec.
    tools: ``ToolSpec`` values bound directly to this agent.
    stateful: Whether the agent keeps thread state across turns. Defaults
        to ``True`` for coordinators when ``None``.
    max_turns: Maximum orchestration turns for this agent, or ``None``
        for the runtime default.
    approval: Agent-level approval override for the ``plans`` and
        ``tools`` channels as an ``ApprovalPolicyPatch`` or mapping. The
        ``"default"`` sentinel for a channel means "do not override the
        runtime default for this channel".
    tool_approvals: Per-tool approval rules keyed by tool name. Each rule
        is ``"never"``, ``"always"``, or ``{"kind": "dynamic", "value": id}``.
    toolkits: Built-in toolkit ids to attach. Defaults to ``["agents"]``,
        which exposes the route hand-off tools.

Returns:
    A validated ``AgentSpec`` with ``role="coordinator"``.

Raises:
    ValueError: If ``routes`` is empty, or a ``tool_approvals`` key or
        approval rule is invalid.
    TypeError: If ``prompt`` is neither a string nor a ``LayeredPrompt``.

<span id="flowai_harness.agents.define_planner"></span>

## `define_planner`

`define_planner(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', plan: 'PlanSpec | Mapping[str, Any]', tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>model</code></td>
<td><code>ModelInput</code></td>
<td>required</td>
</tr>
<tr>
<td><code>prompt</code></td>
<td><code>str | LayeredPrompt</code></td>
<td>required</td>
</tr>
<tr>
<td><code>plan</code></td>
<td><code>PlanSpec | Mapping[str, Any]</code></td>
<td>required</td>
</tr>
<tr>
<td><code>tools</code></td>
<td><code>Iterable[ToolSpec]</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td><code>stateful</code></td>
<td><code>bool | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>max_turns</code></td>
<td><code>int | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>approval</code></td>
<td><code>ApprovalPolicyPatch | Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>tool_approvals</code></td>
<td><code>Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>toolkits</code></td>
<td><code>Iterable[str] | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>AgentSpec</code></p>

Define a planner agent spec.

A planner authors plan instances for the supplied plan schema. The plan
is auto-attached to the runtime spec when not declared explicitly.

Args:
    name: Unique agent name within the runtime spec.
    model: Model selection: a model id string, a ``ModelSpec``, or a
        mapping with ``id`` and optional ``provider``.
    prompt: System prompt as a string or a ``LayeredPrompt``.
    plan: ``PlanSpec`` (or mapping validated as one) describing the
        action schema this planner authors.
    tools: ``ToolSpec`` values bound directly to this agent.
    stateful: Whether the agent keeps thread state across turns. Defaults
        to ``True`` for planners when ``None``.
    max_turns: Maximum orchestration turns for this agent, or ``None``
        for the runtime default.
    approval: Agent-level approval override for the ``plans`` and
        ``tools`` channels as an ``ApprovalPolicyPatch`` or mapping.
    tool_approvals: Per-tool approval rules keyed by tool name.
    toolkits: Built-in toolkit ids to attach. Defaults to ``["plans"]``.

Returns:
    A validated ``AgentSpec`` with ``role="planner"``.

Raises:
    ValueError: If a ``tool_approvals`` key or approval rule is invalid.
    TypeError: If ``prompt`` is neither a string nor a ``LayeredPrompt``.

<span id="flowai_harness.agents.define_executor"></span>

## `define_executor`

`define_executor(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', plan: 'PlanSpec | Mapping[str, Any]', tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>model</code></td>
<td><code>ModelInput</code></td>
<td>required</td>
</tr>
<tr>
<td><code>prompt</code></td>
<td><code>str | LayeredPrompt</code></td>
<td>required</td>
</tr>
<tr>
<td><code>plan</code></td>
<td><code>PlanSpec | Mapping[str, Any]</code></td>
<td>required</td>
</tr>
<tr>
<td><code>tools</code></td>
<td><code>Iterable[ToolSpec]</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td><code>stateful</code></td>
<td><code>bool | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>max_turns</code></td>
<td><code>int | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>approval</code></td>
<td><code>ApprovalPolicyPatch | Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>tool_approvals</code></td>
<td><code>Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>toolkits</code></td>
<td><code>Iterable[str] | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>AgentSpec</code></p>

Define an executor agent spec.

An executor carries out approved plan instances of the supplied plan
schema, emitting business actions for host dispatch.

Args:
    name: Unique agent name within the runtime spec.
    model: Model selection: a model id string, a ``ModelSpec``, or a
        mapping with ``id`` and optional ``provider``.
    prompt: System prompt as a string or a ``LayeredPrompt``.
    plan: ``PlanSpec`` (or mapping validated as one) describing the
        action schema this executor executes.
    tools: ``ToolSpec`` values bound directly to this agent.
    stateful: Whether the agent keeps thread state across turns. Defaults
        to ``False`` for executors when ``None``.
    max_turns: Maximum orchestration turns for this agent, or ``None``
        for the runtime default.
    approval: Agent-level approval override for the ``plans`` and
        ``tools`` channels as an ``ApprovalPolicyPatch`` or mapping.
    tool_approvals: Per-tool approval rules keyed by tool name.
    toolkits: Built-in toolkit ids to attach. Defaults to
        ``["plans", "references"]``.

Returns:
    A validated ``AgentSpec`` with ``role="executor"``.

Raises:
    ValueError: If a ``tool_approvals`` key or approval rule is invalid.
    TypeError: If ``prompt`` is neither a string nor a ``LayeredPrompt``.

<span id="flowai_harness.agents.define_specialist"></span>

## `define_specialist`

`define_specialist(name: 'str', *, model: 'ModelInput', prompt: 'str | LayeredPrompt', tools: 'Iterable[ToolSpec]' = (), stateful: 'bool | None' = None, max_turns: 'int | None' = None, approval: 'ApprovalPolicyPatch | Mapping[str, Any] | None' = None, tool_approvals: 'Mapping[str, Any] | None' = None, toolkits: 'Iterable[str] | None' = None) -> 'AgentSpec'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>model</code></td>
<td><code>ModelInput</code></td>
<td>required</td>
</tr>
<tr>
<td><code>prompt</code></td>
<td><code>str | LayeredPrompt</code></td>
<td>required</td>
</tr>
<tr>
<td><code>tools</code></td>
<td><code>Iterable[ToolSpec]</code></td>
<td><code>()</code></td>
</tr>
<tr>
<td><code>stateful</code></td>
<td><code>bool | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>max_turns</code></td>
<td><code>int | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>approval</code></td>
<td><code>ApprovalPolicyPatch | Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>tool_approvals</code></td>
<td><code>Mapping[str, Any] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>toolkits</code></td>
<td><code>Iterable[str] | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>AgentSpec</code></p>

Define a specialist agent spec.

A specialist is a focused single-purpose agent without routes or a plan.
It can be routed to by a coordinator or dispatched directly via
``runtime.run_specialist(...)``.

Args:
    name: Unique agent name within the runtime spec.
    model: Model selection: a model id string, a ``ModelSpec``, or a
        mapping with ``id`` and optional ``provider``.
    prompt: System prompt as a string or a ``LayeredPrompt``.
    tools: ``ToolSpec`` values bound directly to this agent.
    stateful: Whether the agent keeps thread state across turns. Defaults
        to ``False`` for specialists when ``None``.
    max_turns: Maximum orchestration turns for this agent, or ``None``
        for the runtime default.
    approval: Agent-level approval override for the ``plans`` and
        ``tools`` channels as an ``ApprovalPolicyPatch`` or mapping.
    tool_approvals: Per-tool approval rules keyed by tool name.
    toolkits: Built-in toolkit ids to attach. Defaults to none.

Returns:
    A validated ``AgentSpec`` with ``role="specialist"``.

Raises:
    ValueError: If a ``tool_approvals`` key or approval rule is invalid.
    TypeError: If ``prompt`` is neither a string nor a ``LayeredPrompt``.