For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Run a container image of your own as a kagent agent by implementing the A2A service that the byo runtime expects.

The byo runtime runs a container image that you build, and treats what is inside it as opaque. kagent still compiles the HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: its runtime, workload image, and WorkerPool and snapshot storage. An Agent pairs it with the AgentTemplate it runs.Learn more and AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once an Agent pairs it with a Harness.Learn more into a revisionRevisionThe compiled, immutable output of one Agent, identified by a content digest. A Session runs the revision it was created from for its whole life, so editing the Agent affects only sessions created afterward., schedules that revision onto Agent SubstrateAgent SubstrateThe runtime that kagent runs agents on. It multiplexes many sandboxed Actors onto a smaller pool of pre-started Workers, suspending idle ones to snapshots.Learn more, and routes conversations to it. What the image does with a message is yours to decide. Choose this runtime when you have an agent framework that kagent does not adapt, and you would rather bring the image than the integration.

What kagent runs and what your image runs

The byo runtime divides the work at the A2AA2AThe Agent-to-Agent protocol, which callers and other agents use to talk to an Agent. The conversation's context identifier is the Session ID, so a second message on the same ID continues the same conversation.Learn more (Agent-to-Agent) boundary. Everything on kagent’s side of that boundary behaves in the same way as for the built-in runtimes, so a BYO agent is sandboxed, snapshotted, and addressed identically to one that kagent executes itself.

kagent owns the lifecycle, the isolation, and the routing:

• Compiles an AgentAgentA Kubernetes custom resource that pairs one AgentTemplate with one Harness. Each side takes either an inline spec or a reference to an existing resource, and the controller compiles the pair into a revision.Learn more into an immutable revision, and creates a SessionSessionA running conversation with one Agent. Unlike the resources it is built from, a Session is not a Kubernetes resource: kagent's gRPC API creates it and its PostgreSQL database tracks it.Learn more from it.
• Wraps the ActorActorThe sandboxed unit of compute, provided by Agent Substrate, that runs a Session's conversation loop. Every Session is backed by one.Learn more that the image runs in with a gVisor sandbox.
• Suspends and resumes the Actor between turns, including its in-memory state.
• Routes every conversation through the A2A gateway, so callers address the Agent rather than the Actor behind it.
• Delivers the compiled agent configuration and agent card to the container, which the kagent helpers write to /config/config.json and /config/agent-card.json at startup.

Your image owns the agent’s behavior and the two endpoints that expose it:

• An A2A service that accepts a message and returns a reply.
• A readiness endpoint that reports when the service can take traffic.
• Whatever the agent actually does: model calls, tool calls, and conversation state.

Because Agent Substrate snapshots the whole Actor, an image that keeps conversation state in memory keeps it across a suspend. Your image does not need to persist anything to survive the gap between turns.

The A2A contract

A byo image must meet four requirements to run as an agent. kagent enforces only spec.workload.command at apply time, and the rest surface as a failed invoke rather than as a validation error. The steps in the Configure a byo Harness and Build the image sections later in this page show how to satisfy each requirement.

Opaque and configured agents

kagent compiles an AgentTemplate for a byo Harness in the same way as for the kagent runtime, then hands the result to the container. The two ways of using this runtime differ only in whether the image reads it.

• An opaque agent ignores the compiled configuration. The AgentTemplate exists to give the agent an identity and a description, and the image decides everything else, including which model to call and which tools to offer. Every field on an opaque AgentTemplate is optional, modelConfig included.
• A configured agent reads the compiled configuration. The image honors the AgentTemplate’s system prompt, ModelConfig, tool bindings, skills, and plugins, so an operator changes the agent’s behavior by editing the AgentTemplate rather than by rebuilding the image.

The kagent and byo runtimes compile through the same path, so a configured BYO agent accepts the same model providers and the same AgentTemplate features as the built-in runtime. For the provider matrix, see Model provider support. For what an AgentTemplate can bind, see Tool and skill support.

Both kinds of agent receive the same inputs. Agent Substrate delivers the two JSON payloads as private environment variables, and the kagent helpers write them to files before the agent starts. An image in another language either reads the files that MaterializeFromEnv writes or parses the variables itself.

The runtime object is the root of the configuration document, and subagents inherit it. It includes the settings that a process needs before it serves a request.

{
  "runtime": {
    "control_plane_url": "http://kagent-controller.kagent.svc:8083",
    "gateway_url": "http://kagent-controller.kagent.svc:8083",
    "name": "my-byo-agent",
    "namespace": "kagent",
    "log_level": "info",
    "port": "80",
    "max_content_length": 0
  }
}

Configure a BYO Harness

A byo Harness takes the same fields as any other, minus the runtime settings block. spec.byo is an empty object, because the runtime has nothing to configure. The image holds the behavior.

kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: Harness
metadata:
  name: my-byo-harness
  namespace: kagent
spec:
  byo: {}
  workload:
    image: <your-registry>/my-agent@sha256:<digest>
    command: ["/my-agent"]
  substrate:
    workerPoolRef:
      name: kagent-default
    snapshotPolicy:
      location: s3://ate-snapshots/kagent/
EOF

Review the following table to understand this configuration. For the fields that every Harness shares, see Configure a Harness.

An opaque agent’s AgentTemplate carries only a description for the agent card. An Agent then pairs it with the Harness.

kubectl apply -f - <<EOF
apiVersion: api.kagent.dev/v1alpha3
kind: AgentTemplate
metadata:
  name: my-byo-template
  namespace: kagent
spec:
  description: An agent that my own image implements.
---
apiVersion: api.kagent.dev/v1alpha3
kind: Agent
metadata:
  name: my-byo-agent
  namespace: kagent
spec:
  template:
    ref:
      name: my-byo-template
  harnessRef:
    name: my-byo-harness
EOF

To configure the agent from Kubernetes instead, add the fields that any AgentTemplate takes, and read /config/config.json in the image. For what those fields mean, see Your first agent.

Build the image

The A2A contract is a gRPC service and a readiness endpoint, so any language with a gRPC server can satisfy it. kagent ships helpers for two of them. To build and run a minimal image end to end before writing your own, see Run your own agent image.

if err := config.MaterializeFromEnv("/config"); err != nil {
    return err
}
compiled, err := config.LoadAgentConfig("/config/config.json")
if err != nil {
    return err
}
runtime := compiled.ProcessConfig()

application, err := app.New(app.AppConfig{
    AgentCard: a2atype.AgentCard{
        Name:         "my-agent",
        Version:      "v1",
        Capabilities: a2atype.AgentCapabilities{Streaming: true},
    },
    ControlPlaneURL:  runtime.ControlPlaneURL,
    MaxContentLength: runtime.MaxContentLength,
    Port:             cmp.Or(runtime.Port, "80"),
    AppName:          cmp.Or(runtime.Name, "my-agent"),
    Logger:           logger,
}, myExecutor{})
if err != nil {
    return err
}
return application.Run()

from kagent.adk import KAgentApp
from kagent.core import KAgentConfig

config = KAgentConfig.from_file()

app = KAgentApp(
    root_agent_factory=build_agent,
    agent_card=card,
    kagent_api_url=config.api_url,
    app_name=config.app_name,
).build()

Known limitations

• The A2A interface is fixed. kagent advertises http://127.0.0.1:80 over gRPC, and spec.byo takes no field to change the address, the port, or the protocol. An image that serves A2A over HTTP JSON-RPC alone cannot run on this runtime.
• The kagent-langgraph and kagent-crewai adapters do not qualify yet. Both build a FastAPI application with A2A JSON-RPC routes and no gRPC server, so neither satisfies the contract as shipped. Running LangGraph or CrewAI under byo currently means serving A2A over gRPC yourself.
• Long-term memory is unavailable. Memory is configured under spec.kagent.memory and wired only by the kagent runtime’s compiler. A byo Harness has no equivalent setting. For what a BYO image would need to replace, see Agent memory.
• A broken port mapping presents as a healthy agent. For the failure and what avoids it, see The A2A contract.

Next steps