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.

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.