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 exposing the A2A service that the byo harness expects.

The byo harness runs a container image that you build, and treats what is inside it as opaque. kagent still builds 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. from the HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: which harness executes the agent, its workload image, and its WorkerPool and snapshot storage. An Agent pairs it with the AgentTemplate that it runs.Learn more and the 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, 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 harness when you already have an agent that is built with an agent framework, and you want to run that agent in kagent.

Responsibilities on each side of the A2A boundary

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) is the contract between kagent and a BYO agent.

Your image owns one side of the A2A contract by:

• Exposing an A2A service that accepts a message and returns a reply.
• Exposing a readiness endpoint that reports when the service can take traffic.
• Deciding what the agent actually does, including model calls, tool calls, and conversation state.

kagent runs a BYO agent exactly as it runs one on a managed harness, and owns the other side of the A2A contract by:

• Building an immutable revision from the HarnessHarnessA Kubernetes custom resource defining how an agent is allowed to run: which harness executes the agent, its workload image, and its WorkerPool and snapshot storage. An Agent pairs it with the AgentTemplate that it runs.Learn more and the AgentTemplate, and creating 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.
• Running 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 hosts your image inside a sandbox. The WorkerPoolWorkerPoolA Kubernetes custom resource declaring how many Workers to keep running and which sandbox class they use. An operator must provision one before any Agent can compile.Learn more that the Harness references sets the class: gvisor, which every installation provides, or microvm, which needs its own Agent Substrate provisioning. For more information, see Sandbox classes.
• Suspending and resuming the Actor between turns, including its in-memory state.
• Routing every conversation through the A2A gateway, so callers address the 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 rather than the Actor behind it.
• Delivering the agent configuration and agent card to the container, which the kagent helpers write to /config/config.json and /config/agent-card.json at startup.

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

Both the Harness and the image must meet the following requirements, and kagent enforces them at different moments. Nothing checks the A2A service until a caller invokes the agent, so a misconfigured image reaches a healthy-looking state first. For examples of how to satisfy each requirement, see the steps in Configure a BYO Harness and Build the image.

Compare BYO and declarative agents

kagent resolves the AgentTemplate in the same way for a BYO agent as for a declarative agent, then delivers the result to the container as a JSON document in an environment variable. Both harnesses resolve a ModelConfig through the same code, so the same model providers work and the same ones are rejected. For the provider matrix, see Model provider support.

The kagent harness reads that document and assembles the agent from it. A BYO image decides whether to read it:

• An opaque agent ignores the document. 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 document. The image applies the AgentTemplate’s system prompt, ModelConfig, tool bindings, skills, and plugins itself. Editing the AgentTemplate changes what the agent does without a rebuild.

Two AgentTemplate features continue to apply regardless of this choice. First, a byo Harness rejects structured output, with Harness runtime "byo" does not support structured output. Second, the agent card that kagent advertises for a byo Agent leaves out the AgentTemplate’s skills and declares no extension, so a client cannot discover human-in-the-loop support the way it can for a declarative agent.

Both kinds of BYO agent receive the same environment variables. Agent Substrate delivers the two JSON payloads as private 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. The object 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 Harness. Its own block, spec.byo, is an empty object, because the image defines the behavior that the other harnesses take settings for.

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 sets 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 Go and Python. To build and run a minimal image end to end before writing your own, see Run your own agent image.

import (
    "cmp"
    "context"
    "fmt"
    "iter"
    "os"

    a2atype "github.com/a2aproject/a2a-go/v2/a2a"
    "github.com/a2aproject/a2a-go/v2/a2asrv"
    "github.com/kagent-dev/kagent/go/adk/pkg/app"
    "github.com/kagent-dev/kagent/go/adk/pkg/config"
    "github.com/kagent-dev/kagent/go/pkg/logging"
)

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 does not take a field that changes the address, the port, or the protocol. An image that serves A2A over only HTTP JSON-RPC cannot run on this harness.
• The LangGraph, CrewAI, and OpenAI adapters do not satisfy the contract. The kagent-langgraph, kagent-crewai, and kagent-openai packages each build a FastAPI application with A2A JSON-RPC routes, without a gRPC server. Running LangGraph, CrewAI, or the OpenAI Agents SDK under byo means serving A2A over gRPC yourself, as the Any other language tab in Build the image describes.
• Long-term memory is unavailable. Memory is configured under spec.kagent.memory, and only the kagent harness wires it up. A byo Harness does not take an equivalent setting. For what a BYO image would need to replace, see Agent memory.
• A broken port mapping looks like a healthy agent. For the failure and what avoids it, see The A2A contract.

Next steps