Docs: add Codex and Claude Harness examples, and a codex runtime-image conref

Start by reading agents/agent-harness.md and the linked PR #529. The work involves adding two complete Harness examples (Codex and Claude) to the documentation, each with a ModelConfig and AgentTemplate. You must also update .github/workflows/update-ref-docs.yaml to add a new conref for the Codex runtime image and create the file assets/kagent-docs/versions/runtime-image-codex.md. Test the examples on a cluster using the provided setup script. The main open question is where to place the Claude example, which you must decide and justify in the PR.

[!IMPORTANT]
Adjusted for 1.0.0-alpha5 on 2026-09-29. The codex and claude runtimes both survive, so the examples are still wanted. One structural change affects every manifest in this issue:

allowedAgentTemplates is removed from HarnessSpec. Any example that pairs an AgentTemplate to a Harness with a label selector is obsolete. alpha5 introduces an explicit Agent kind that pairs the two, taking either a reference or an inline spec on each side. Write the examples against that model.

The CRDs also moved to api.kagent.dev, so manifests need apiVersion: api.kagent.dev/v1alpha3. Part of #549.

The 1.x doc set documents the codex and claude runtimes in every table on Agent harness and shows a working example of neither. Every Harness example in the set selects the kagent runtime. A reader who decides on Codex from the runtime table has nothing to copy.

This gets worse when #529 merges. That PR rewrites setup/model-providers/google-vertexai.md, which today holds the only claude Harness example in the set, because Vertex AI no longer compiles on any runtime. After it merges, assets/kagent-docs/versions/runtime-image-claude.md is referenced by no page at all, while the nightly job keeps resolving it.

So this is one piece of work covering both coding-agent runtimes.

What to add

A Codex Harness example and a Claude Harness example, each complete enough to apply: the Harness, the ModelConfig it needs, and an AgentTemplate carrying the label the Harness admits. The spine is that a coding-agent Harness is the same shape as a kagent one and differs only in the runtime block, the image, and which ModelConfig it will accept — so these belong beside the existing example rather than in a new tutorial.

The configuration surface

Verified against kagent 1e5533b2 (v1.0.0-alpha2 plus five commits) on a cluster.

Codex.

Piece	Value
Runtime block	codex: {}, which takes no settings
Image	ghcr.io/kagent-dev/kagent/codex-harness, digest-pinned. A bare tag is rejected.
ModelConfig	OpenAI with openAI.apiFormat: responses, and no other openAI settings beyond baseUrl
Alternative	Bedrock with an OpenAI gpt-* model ID, no bedrock settings beyond region, and a bearer token in AWS_BEARER_TOKEN_BEDROCK

Claude.

Piece	Value
Runtime block	claude: {}, which takes no settings
Image	ghcr.io/kagent-dev/kagent/claude-harness, digest-pinned
ModelConfig	Anthropic, with no anthropic settings beyond baseUrl
Alternative	Bedrock with a bearer token, no bedrock settings beyond region

Both runtimes reject a ModelConfig that sets defaultHeaders, tls, or apiKeyPassthrough.

Behavior the API does not announce

• The Codex compiler rejects chat completions outright, so a Codex ModelConfig cannot be shared with a kagent agent that uses the same provider. openAI.apiFormat: responses is not a tuning knob, it is the only accepted value.
• A RemoteMCPServer bound to a Codex agent must use STREAMABLE_HTTP. SSE is rejected.
• Claude binds an MCP server whole. It does not support partial tool selection, so the agent sees every tool the server offers rather than only the ones a binding names, and the compiler warns rather than failing.
• Neither runtime accepts AnthropicVertexAI as of #529. Do not reintroduce a Vertex example.
• A version mismatch between the harness image and the controller does not look like a version mismatch. The harness validates the config version the controller compiles for it and refuses a mismatch; the chat reports AgentTemplate and Harness do not have a ready prepared revision, which reads as an Agent Substrate fault. Pin the image to the same kagent release the rest of the docs name.

The codex conref does not exist yet, and creating the file is not enough

Both existing runtime images come from conrefs that the nightly job resolves from the registry, so a Codex example needs a third one wired into the same job. In .github/workflows/update-ref-docs.yaml:

1. Add runtime-image-codex:kagent-dev/kagent/codex-harness to the RUNTIME_IMAGES table (currently two lines, around L482).
2. Add a RUNTIME_IMAGE_CODEX block beside the two write_conref calls (around L690).
3. Add a row to the PR-body summary table (around L713).
4. Create assets/kagent-docs/versions/runtime-image-codex.md with a resolved value so the page renders before the next nightly.

The env var name is derived from the basename, so runtime-image-codex becomes RUNTIME_IMAGE_CODEX automatically. The tag resolved against comes from versions/kagent.md, not from git describe.

At 1.0.0-alpha2 the digest is sha256:9ccd6750494a304490f21f5f10537a7677d3290070d1df90b4cb535dc6bcd0af. Re-resolve rather than copying that, and check it against whatever versions/kagent.md names when you start.

Where it goes

agents/agent-harness.md, in or beside the Choose a runtime section, is the natural home: the runtime tables are already there and the page is the reference for the resource.

The one open question is whether the Claude example lands there too, or on setup/model-providers/anthropic.md. The argument for the provider page is that a Claude Harness is inseparable from the ModelConfig that feeds it, which is how the Vertex page used to carry it. The argument for keeping both on the harness page is that a reader comparing runtimes sees both without navigating. Pick one and say why in the PR.

What to check before starting

1. Read agents/agent-harness.md end to end. Most of what an example needs is already stated in its tables; the example should not restate them.
2. Rebase on #529 if it has merged, since it changes the provider matrix and the restriction rows this example must agree with.
3. Run both on a cluster. scripts/setup-cluster/setup-cluster.sh in kagent-dev/kagent stands one up. Codex needs an OpenAI key entitled to a codex model — a key without access to the model still lists it and then fails the turn with model_not_found, surfacing only as Codex execution failed in the chat.

Done when

• A Codex Harness example exists, with its ModelConfig and an AgentTemplate, and was run on a cluster.
• A Claude Harness example exists on the same terms, restoring the one #529 removes.
• runtime-image-codex.md exists and the nightly job resolves it; both other conrefs still resolve.
• runtime-image-claude.md is referenced by a page again.
• Every image is digest-pinned, and no example carries a bare tag.
• The placement question is answered in the PR description.