What is a Router?
A router is a directed graph that evaluates an AI request and chooses how it should be handled. Routers are especially useful when a project has multiple endpoints, policies, or optimization strategies but application developers need one stable API target.
Router DAG Definition
The Bud admin UI models router graphs with a RouterDAGDefinition shape:
| Field | Description |
|---|
name | Router graph name |
version | Optional version label |
description | Optional summary of the routing purpose |
parameters | Runtime inputs accepted by the router |
steps | Ordered action nodes and dependency metadata |
outputs | Optional named outputs produced by the graph |
Action Categories
Router actions are fetched dynamically from the router API. The editor uses action metadata for display, parameter forms, outputs, and connection validation.
| Category | Role in the Graph | Examples of Parameters |
|---|
| Signal | Evaluate request or environment inputs | Request fields, string lists, content rules |
| Projection | Transform context into normalized routing features | Templates, JSON objects, derived fields |
| Decision | Choose downstream route based on rules | Branches, rule trees, conditions |
| Algorithm | Execute endpoint selection strategy | Endpoint lists, weighted endpoints, ordered fallback endpoints |
| Plugin | Apply extension behavior | Credentials, provider settings, cache or guardrail configuration |
The exact action list is backend-driven. If an expected action does not appear, refresh the router actions catalog or verify that /routers/actions returns the category and action metadata.
Connection Rules
The router editor intentionally supports a constrained topology so routing graphs remain predictable.
Allowed Connections
| Source | Allowed Targets |
|---|
| Trigger | Signal, Decision, Projection |
| Decision | Algorithm, Plugin |
Rejected Connections
- Signal → any node
- Projection → any node
- Decision → Signal, Projection, Decision, or Trigger
- Algorithm → any node
- Plugin → any node
- Trigger → Algorithm or Plugin directly
The editor shows warnings for invalid connections, such as trying to connect a Trigger directly to an Algorithm. In that case, insert a Decision first and connect the Algorithm from the Decision.
Parameters and Data Sources
Router action forms can draw options from Bud resources loaded on the detail page:
- Clusters use
cluster_id values for deployment-compatible workflows.
- Models load global model records.
- Projects identify project-scoped routing ownership.
- Providers and credentials support proprietary or cloud-backed actions.
- Endpoints provide deployment targets for algorithm and routing actions.
Save Lifecycle
When you click Save, Bud admin performs these steps:
- Flush unsaved action configuration changes.
- Validate action parameters in the editor panel.
- Convert editor steps into API
dag_config.steps.
- Add
entry_step, parameters, outputs, dependencies, conditions, and next_steps.
- Update the router and set status to
active.
Routers can appear as draft, active, or inactive. Router cards display step count, execution count, creation time, and last execution time when available.