Agent

The record of what an agent is, who owns it, what it can do, and where it runs. Everything else in the control plane resolves back to it.

Why it exists#

An agent that only exists as a Deployment is invisible to governance: nothing records which tenant it belongs to, which capabilities it claims, which models it may call, or who to ask when it misbehaves. The Agent resource is that record, and it is a Kubernetes object so it lives in the same GitOps review flow as the rest of your platform.

An Agent may be deployed by the operator or merely described. An agent already running somewhere else is registered with hostingMode: external and an endpoint — it is governed without being owned.

A minimal 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
      description: Evaluates and drafts customer refunds.
  image:
    repository: ghcr.io/acme/refund-agent
    tag: v0.1.0

Apply it like any other resource. The operator reconciles the Deployment and Service, then publishes the agent to the registry so the gateway can route to it.

kubectl apply -f refund-agent.yaml
kubectl get agents -n agentfleet-demo

Capabilities are the routing contract#

Callers ask for a capability, never for an agent by name. That indirection is what lets you replace, split, or version an agent without touching the applications calling it. An agent declaring refund-processing is announcing it can serve that capability; an AgentRoute decides which declaring agent actually gets the request.

Health gates routing#

The operator tracks agent status and reports a phase. A Degraded agent is not routed to, which is why a request can fail with no_matching_agent even though the agent exists. That is the intended behaviour — routing to a known-unhealthy agent would trade a clear error for a confusing one.

Full field list#

Every field, with types and defaults, is in the generated CRD reference.