Agent Assignment

Route specific contract bundles to specific agents. Three-level resolution system with pattern-based rules.

How Bundle Resolution Works

When an agent connects, the console determines which bundle to serve using three sources in priority order:

The first match wins. If nothing matches, the agent connects without a bundle.

Explicit Assignment

Set a bundle directly on an agent:

Dashboard > Agents > select an agent > Assign Bundle.

Or via API:

PATCH /api/v1/agent-registrations/{agent_id}
{"bundle_name": "production-safety"}

This overrides all rules and agent-provided values.

Bulk Assignment

Assign one bundle to many agents at once:

POST /api/v1/agent-registrations/bulk-assign
{
  "agent_ids": ["prod-agent-1", "prod-agent-2", "prod-agent-3"],
  "bundle_name": "production-safety"
}

Each affected agent receives an assignment_changed SSE event and fetches the new bundle immediately.

Assignment Rules

Rules match agents by ID pattern and optional tags. Evaluated in priority order (lower number = higher priority).

Creating a Rule

Dashboard > Agents > Assignment Rules tab > New Rule.

Pattern Syntax

Standard glob matching:

Validation: Patterns must be 1-200 printable ASCII characters. No path separators (/, \) or null bytes.

Tag Matching

Rules can optionally match on agent tags. All specified keys must match (AND logic):

{
  "team": "platform",
  "tier": "1"
}

This rule only matches agents that have both team=platform AND tier=1 in their tags.

Example Rules

Rules are evaluated in priority order. The first matching rule wins.

Environment scoping: Rules are matched against the agent's environment. At runtime, agents connecting via SSE only match rules for their authenticated environment — rules targeting production never apply to a staging agent.

Dry-Run Resolution

Preview which bundle an agent would receive without actually connecting:

GET /api/v1/assignment-rules/resolve/{agent_id}?env={env}

The optional env query parameter filters resolution to rules for that environment only. When omitted, all tenant rules are evaluated — this is the dashboard preview mode and does not reflect runtime behavior for a connected agent.

Response:

{
  "agent_id": "prod-platform-agent",
  "bundle_name": "platform-production",
  "source": "rule",
  "matched_rule_id": "550e8400-...",
  "matched_pattern": "prod-*"
}

The source field tells you where the bundle came from:

• explicit -- set directly on the registration
• rule -- matched an assignment rule (includes rule ID and pattern)
• agent -- provided by the agent on connect
• none -- no bundle resolved

SSE Events

When an agent's assignment changes (explicit assignment, rule change, or bulk assign), the console pushes an assignment_changed SSE event to the affected agent. The agent fetches the new bundle and reloads contracts immediately.

Agents connecting via SSE automatically resolve bundle assignment against their authenticated environment. Rules targeting other environments are excluded from the match, so agents in production and staging receive environment-scoped bundles independently.

API Endpoints

Next Steps

• Connecting Agents -- connect agents with tags for rule matching
• Fleet Monitoring -- verify agents received the correct bundle