Route by capability

Send a capability to the right agent, and change which agent serves it without touching the applications that call it.

Before you begin#

You need at least one healthy agent that declares the capability you want to route. Check what is available:

kubectl get agents -A

An agent must be Ready to be routable. Degraded agents are deliberately skipped.

Declare the capability on the agent#

spec:
  capabilities:
    - name: refund-processing
      description: Evaluates and drafts customer refunds.

Create the route#

apiVersion: agentfleet.io/v1alpha1
kind: AgentRoute
metadata:
  name: refund-processing-route
  namespace: agentfleet-demo
spec:
  routeType: capability
  capabilities:
    - refund-processing
  priority: 100
  enabled: true

kubectl apply -f refund-route.yaml

Verify#

Ask for the capability and read which agent answered and why:

curl -s http://127.0.0.1:8080/v1/run \
  -H 'Content-Type: application/json' \
  -d '{"tenant":"retail","capability":"refund-processing","input":{"message":"test"}}' \
  | grep -o '"route":{[^}]*}'

"route":{"mode":"capability",
         "reason":"Matched healthy agent by capability."}

Read the reason, not just the agent

route.reason is the scheduler explaining itself. When routing surprises you, this field tells you whether the decision came from priority, health, or a fallback.

Shifting traffic between agents#

Give the replacement a higher priority and both stay eligible, with the new one preferred:

spec:
  priority: 120

To drain the old one entirely without deleting anything, disable its route:

spec:
  enabled: false

Priority does not override health

A higher-priority agent that is Degraded still loses to a healthy lower-priority one. Priority orders candidates; it does not create eligibility.

When no agent matches#

A 409 with no_matching_agent means no healthy agent declared the capability. Check whether the agent exists but is degraded before assuming the route is wrong:

kubectl get agents -A
kubectl describe agent refund-agent -n agentfleet-demo