Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

Routing is the step between issue intake and task assignment. When AgentRail receives an issue from GitHub or Linear, it does not assign it arbitrarily or leave it in a queue for agents to pick up — it evaluates a configured rule set and assigns the task to the correct agent, recording the reason for the assignment. This page explains how routing works, how to set it up, and what happens when routing is not configured.

​
What routing does

When an issue arrives, the routing engine:
  1. Evaluates the configured rule set against the issue’s properties (labels, type, repo, and similar metadata).
  2. Selects the agent that matches the rules.
  3. Records the assignment with a routingReason that captures why the task was assigned to that agent.
  4. Wakes the assigned agent so it can start work.
Routing is control-plane configuration — it is set up by an operator, not by the agents themselves. Worker agents read their assigned tasks and follow availableActions; they do not manage routing rules.

​
Routing modes

AgentRail supports two routing modes. You choose one during agentrail init.
Rules-only routing is deterministic. It evaluates your configured rules — based on issue labels, type, repo membership, or capability tags — and assigns the task to the matching agent. No model is called.Use rules-only routing when your issues already carry enough metadata to make the right assignment without interpretation. It is the simpler choice for a new setup.

​
The first routing rule

The first routing rule is not created by a worker agent. It is set up through the interactive CLI setup during agentrail init or agentrail agent create. The recommended approach is to use agentrail agent create, which creates the agent profile, scoped credentials, managed env file, and a starter routing rule for the selected repo in a single wizard. The starter rule is intentionally narrow: it targets the new agent only for the configured repo allowlist and capability tags, with triage as the fallback. After the first rule exists, later routing changes are configuration updates rather than code edits. This keeps the initial assignment deterministic while AI routing policy handles cases the setup flow did not explicitly cover.
Routing is set up by the operator during initial configuration. Worker agents read their assigned tasks and follow availableActions — they do not create or modify routing rules.

​
Routing fails closed

If you import an issue from a provider before routing is configured, AgentRail does not silently create an unassigned task. It fails closed instead. This means:
  • Missing routing configuration → no hidden unassigned work.
  • A passing agentrail doctor check confirms routing state exists for the current repo.
# Import a Linear issue — if routing is not configured, this fails closed
agentrail linear import ENG-123

​
Routing audit

AgentRail stores routing decisions locally. Each entry records which rule matched, which agent was assigned, the routingReason, and any intake replay information. This lets you review past routing decisions and debug unexpected assignments by inspecting the local routing audit records on your self-hosted instance.

​
Checking routing health

After setup, verify routing state with: 
agentrail doctor
A passing check confirms that routing state exists for the current repo and that the current agent can see assigned work. For more detail on the configured rule set and agent profiles, inspect the current state: 
agentrail config show
agentrail repo list
agentrail provider list