Onboard an agent

Take an agent from "it exists" to "it serves governed traffic": register it, route to it, and allow it in policy.

The three things every agent needs#

An agent is not reachable until all three exist. Missing any one produces a different, specific error, so work through them in order:

1. An Agent resource, so the fleet knows it exists and is healthy.
2. An AgentRoute, so a capability resolves to it.
3. A policy allow rule, so requests to it are permitted.

Register the agent#

apiVersion: agentfleet.io/v1alpha1
kind: Agent
metadata:
  name: refund-agent
  namespace: agentfleet-demo
spec:
  runtime: langgraph
  hostingMode: kubernetes
  tenant: retail
  owner: commerce-ops
  capabilities:
    - name: refund-processing
  image:
    repository: ghcr.io/acme/refund-agent
    tag: v0.1.0

apiVersion: agentfleet.io/v1alpha1
kind: Agent
metadata:
  name: refund-agent
  namespace: agentfleet-demo
spec:
  runtime: external-http
  hostingMode: external
  tenant: retail
  owner: commerce-ops
  capabilities:
    - name: refund-processing
  endpoint:
    url: https://agents.example.com/refund-agent

Use hostingMode: external for an agent that already runs somewhere else. The control plane governs it without deploying it.

Unless the profile sets registry.operatorWritesAreApprovals=true, the Registry record the Operator publishes for the agent is pending, and nothing routes to a pending record: only registered and managed records route, and only a recorded decision by an administrator should make one (the approval routes that record it, issue #727, are only a first slice in the Registry: off by default, not enabled by the chart, and not called by the Console or the command line). That setting takes the Operator's write as the approval, so the record is registered and routes. It records no person's decision, and with Registry write authentication off, the default, any caller that can reach the write API can make a record routable. The local and demo profiles set it when their file is passed (not for an older release upgraded with --reuse-values: see Install with Helm); the chart default and the enterprise profiles do not, so on those the agent does not route yet. On PostgreSQL storage, turning it on later does not move an agent that is already pending; on memory storage the restart that turning it on causes loses the Registry’s records, and the Operator’s next republish creates each agent again as registered (read from the chart and the Registry code; not run on a cluster).

kubectl get agents -n agentfleet-demo
# NAME           RUNTIME     MODE         PHASE
# refund-agent   langgraph   kubernetes   Ready

Route to it#

See Route by capability. Without a route, requests fail with no_matching_agent even though the agent is healthy.

Allow it in policy#

See Write a policy that allows traffic. Without an allow rule, requests fail with policy_denied even though the agent is healthy and routable.

Verify end to end#

curl -s http://127.0.0.1:8080/v1/run \
  -H 'Content-Type: application/json' \
  -d '{"tenant":"retail","capability":"refund-processing",
       "input":{"message":"refund order 123"}}'

A 200 with your agent named in agent.name means all three pieces are in place.

Preview it first#

The Console's onboarding view generates these manifests from a form and runs readiness checks before you apply anything — useful for catching a capability with no matching policy while it is still a draft.