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, WorkerPool and snapshot storage, and which AgentTemplates it accepts.Learn more and AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once a Harness accepts it.Learn more into a revisionRevisionThe compiled, immutable output of one Harness and AgentTemplate pairing, identified by a content digest. An AgentInstance runs the revision it was created from for its whole life, so editing either resource affects only instances 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 AgentInstance. The conversation's context identifier is the AgentInstance 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 a Harness and an AgentTemplate into an immutable revision, and creates an AgentInstanceAgentInstanceA running, conversational pairing of a Harness and an AgentTemplate. Unlike the two, it is not a Kubernetes resource: kagent's gRPC API creates it and its database tracks it.Learn more from it.
• Wraps the ActorActorThe sandboxed unit of compute, provided by Agent Substrate, that runs an AgentInstance's conversation loop. Every AgentInstance 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 AgentInstance rather than the Actor behind it.
• Delivers the compiled agent configuration and agent card to the container as environment variables.

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 as environment variables. The two ways of using this runtime differ only in whether the image reads them.

• 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 variables.

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: 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"]
  env:
    - name: PORT
      value: "80"
  substrate:
    workerPoolRef:
      name: kagent-default
    snapshotPolicy:
      location: gs://<your-bucket>/kagent/
  allowedAgentTemplates:
    selector:
      matchLabels:
        kagent.dev/harness: my-byo-harness
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 the label that the Harness selects on, plus a description for the agent card.

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

To configure the agent from Kubernetes instead, add the fields that any AgentTemplate takes, and read KAGENT_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.

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

from kagent.adk import KAgentApp

app = KAgentApp(
    root_agent_factory=build_agent,
    agent_card=card,
    kagent_api_url=os.environ["KAGENT_URL"],
    app_name="my-agent",
).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. Readiness passes on 8081 regardless of the A2A service, so the AgentInstance reports READY and every invoke fails. This is kagent#2758.

Next steps