Agent Specialization

Agent specialization routing uses a domain registry to prevent duplicate effort in multi-agent teams. Agents claim non-overlapping knowledge domains and are routed tasks based on their registered expertise. When a task arrives, the router matches its topic against the domain registry and dispatches it to the owning agent rather than broadcasting to all agents.

How it works

Specialization is built on three mechanisms:

• Domain registry — a workspace-scoped store that maps domain names to agent IDs. At startup, each agent with a domains config registers its claimed domains. The registry rejects duplicate claims to enforce non-overlap.
• Claim and release — an agent claims a domain at startup and holds it until it is shut down or explicitly releases it via POST /agents/:id/domains/:domain/release. Released domains are immediately available for other agents to claim.
• Routing — when a task is dispatched, the specialization router extracts topic signals from the task description using a lightweight classifier and looks up the best-matching domain in the registry. The task is forwarded to the owning agent. If no domain matches, the task falls back to the default routing policy (round-robin or priority-based).

Built-in domains

Open Astra ships with a set of predefined domains that map to common software engineering concerns. Any agent can claim these domains in its config:

Custom domains can be registered with any string identifier. Domain names are case-insensitive and must match the regex [a-z0-9-]+.

Registering a domain

Declare the domains an agent owns in its YAML config. An agent can hold multiple domains:

agents:
  - id: security-agent
    displayName: Security Specialist
    domains:
      - auth
      - infra
    systemPromptTemplate: |
      You are a security specialist. Your areas of ownership are
      authentication systems and infrastructure hardening.

  - id: test-agent
    displayName: Test Engineer
    domains:
      - testing
    systemPromptTemplate: |
      You are a test engineer. Write thorough, maintainable tests.

Routing behavior

When a task is dispatched to the swarm, the specialization router scores each registered domain against the task description using keyword overlap and embedding similarity. The domain with the highest score above the routing confidence threshold (specialization.routingThreshold, default 0.65) wins and the task goes to its owner.

Tasks that score below the threshold on all domains are treated as unspecialized and handled by the fallback policy. You can inspect routing decisions in the agent run trace — each dispatched task includes a routingDecision field showing the matched domain, owning agent, and confidence score.

specialization:
  enabled: true
  routingThreshold: 0.65       # Minimum confidence to use domain routing
  fallbackPolicy: round-robin  # round-robin | priority | broadcast
  embeddingModel: text-embedding-3-small

Conflict handling

The domain registry enforces single-owner exclusivity. If a second agent attempts to claim a domain that is already held, the registration is rejected with a 409 Domain already claimed error at startup. The conflicting agent will start without that domain and log a warning.

To reassign a domain, the current owner must release it first:

# Release a domain from the current owner
POST /agents/security-agent/domains/auth/release

# The domain is now available; restart or reconfigure the new owner to claim it

If the owning agent crashes and cannot release its domains gracefully, the registry applies a lease timeout (configurable via specialization.domainLeaseTtlSeconds). After the TTL expires, the domain is automatically released and available for reclaim.