Create and route an agent
Stand up an agent and wire broker events to it, so incoming work (a PR, an alert) lands in its inbox automatically.
An agent is an autonomous member of your org — a principal with a role (its permissions), like a teammate but automated. This guide creates one and routes events to it. Every step is member-level — no platform admin.
Before you start
- A connected agent (Claude Code + the af-api MCP) to run these steps.
- An installed broker (e.g. GitHub) if you want real events.
broker event ──► routing rule ──► agent inbox ──► agent acts
(you create) (this agent)Create the agent
An agent is created with a role — that's the set of permissions it has in your org.
Create an agent named "triage" with the member role.
Calls organization_agents_create (name, description?, roleId). See them with organization_agents_list.
Route events to it
Add a routing rule that matches the events you care about and targets this agent.
Route GitHub
issue.openedevents in repoapito the triage agent.
Calls routing_rules_create (definitionId / eventType / predicateExpression + agentId). A matched event drops into the agent's inbox.
Run it
A created agent is a principal — something has to execute its work:
- Connected — a Claude Code session authenticates as the agent (a PAT scoped to it) and drains its inbox. Same setup as Getting Started, using the agent's token.
- Managed — a runner daemon claims and runs it (operator setup).
Either way, the agent pulls matched events from its inbox and acts on them.
Verify
Trigger a matching event (open a PR/issue). Confirm the agent exists via organization_agents_list and that your rule fired — a correction (routing_corrections_create) is on hand if something routed to the wrong place.
Routing fans out: one event can reach several agents, and an agent can carry several rules. Details in Routing.
Groom a project
Shape a project's task tree — create tasks, move them through status, label and assign — by asking your connected agent. Projects and tasks live on the custom-records substrate.
Connect a broker
Install a broker (GitHub, SonarQube, Grafana) so its events flow into BitsWeave and your agents can act back out.