Routing & Sessions

When a user sends a message, the orchestrator needs to decide which agent handles it. The routing field in agent.yaml controls this behaviour. Sessions track the ongoing conversation state between a user and an agent.

Routing modes

The routing field is a simple string enum:

routing: auto    # or: inline, delegate

auto (default)

The orchestrator decides whether to inline or delegate based on heuristics. An agent is inlined when all of these are true:

• It has 3 or fewer tools
• It does not set a custom model override
• Its combined capability prompts are under 2000 characters

Otherwise, the agent is delegated.

routing: auto

Tip

auto is a good default for most agents. You only need to set inline or delegate explicitly when you want to override the heuristics.

inline

The agent’s capability tools are merged directly into the default agent’s tool list. The agent does not run as a separate entity — its tools simply become available on the default agent.

routing: inline

Best for simple, lightweight agents with a small number of tools that don’t need their own system prompt or conversation context.

delegate

The agent runs as a separate entity with its own session and context. Other agents hand off work to it using delegate_to_agent.

routing: delegate

Best for complex agents that need their own system prompt, model configuration, or isolated conversation context.

Note

There is no trigger system (no intent classifier, keyword matching, or regex matching). Routing is mention-based: if a message starts with @agent_id, it goes to that agent. Otherwise, it goes to the default agent, which has access to inlined tools and can delegate to other agents.

Sessions

A session is a stateful conversation between a user and an agent. Sessions track:

• Message history — A rolling window of the last 30 messages sent to the LLM.
• Long-term memory — Always available via the built-in memory_* tools.
• Active capability state — If a capability uses multi-step flows, the session holds intermediate state.

Session configuration

Configure sessions with the session field in agent.yaml:

session:
  trigger: mention              # when to activate (default: "mention")
  idle_timeout_minutes: 30      # cleanup timeout in minutes (default: 30)
  isolation: shared             # or: per_thread (default: shared)

Session isolation modes

shared (default) — Reuses active sessions for the same user and agent across threads. If a user is already talking to an agent in one thread, starting a conversation in another thread picks up the same session.

per_thread — Creates a dedicated session per thread with separate capability containers. Each thread gets its own message history and state.

session:
  isolation: per_thread

Tip

Use per_thread when your agent manages stateful workflows that should not bleed across threads — for example, a code review agent that tracks file context per pull request.

Next steps

Now that you understand routing, head to Build Your First Agent to put it all together.