Repository navigation
Rework harness and agent concepts - #607
Merged
Merged
Conversation
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Docs preview
Both are uploaded Worker versions and serve no production traffic. |
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
marked this pull request as ready for review
October 14, 2026 23:04
Align 1.x documentation with the harness model and clarify BYO agent responsibilities, runtime requirements, Actor environment limits, and pgvector setup for agent memory. Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
changed the title
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Nadine2016
reviewed
Oct 15, 2026
| | One of `kagent`, `codex`, `claude`, `byo` | Yes | The runtime that executes the agent. Naming none, or more than one, is rejected. For the available runtimes, see [Choose a runtime](#choose-a-runtime). | | ||
| | `workload.image` | Yes | The runtime image, pinned by `sha256` digest. A tag alone is rejected, because a revision must be reproducible. | | ||
| | `workload.command` | For `byo` | Overrides the image entrypoint, up to 32 entries. Required for the `byo` runtime, optional otherwise. Every runtime honors an explicit value, the `kagent` runtime included, regardless of the language its image is written in. | | ||
| | One of `kagent`, `codex`, `claude`, `byo` | Yes | The harness that executes the agent. Naming none, or more than one, is rejected. For the four available, see [Choose a harness](#choose-a-harness). | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | One of `kagent`, `codex`, `claude`, `byo` | Yes | The harness that executes the agent. Naming none, or more than one, is rejected. For the four available, see [Choose a harness](#choose-a-harness). | | |
| | One of `kagent`, `codex`, `claude`, `byo` | Yes | The harness that executes the agent. Naming none, or more than one, is rejected. For the four harness types that are available, see [Choose a harness](#choose-a-harness). | |
Nadine2016
reviewed
Oct 15, 2026
| | `byo` | A container image of your own that implements kagent's A2A contract | You already have an agent that is built with an agent framework, and you want to run that agent in kagent. For more information, see [Bring your own agent]({{< link path="agents/bring-your-own-agent" >}}). | | ||
|
|
||
| `spec.kagent` is the only runtime block that takes settings of its own. The rest are empty. | ||
| The harnesses differ in two ways that decide what an agent running on them can do. They accept different model providers, which [Model provider support](#model-provider-support) lists, and they accept different AgentTemplate features, which [Tool and skill support](#tool-and-skill-support) lists. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The harnesses differ in two ways that decide what an agent running on them can do. They accept different model providers, which [Model provider support](#model-provider-support) lists, and they accept different AgentTemplate features, which [Tool and skill support](#tool-and-skill-support) lists. | |
| The harnesses accept different model providers, which [Model provider support](#model-provider-support) lists, and they accept different AgentTemplate features, which [Tool and skill support](#tool-and-skill-support) lists. |
Nadine2016
reviewed
Oct 15, 2026
| | `SAPAICore` | ❌ | ❌ | ❌ | ❌ | | ||
|
|
||
| kagent rejects `AnthropicVertexAI`, `GeminiVertexAI`, and `SAPAICore` on every runtime, because each authenticates with a credential that the egress gateway cannot place in an HTTP header. No agent can use these providers. For the alternatives, see [About model providers]({{< link path="setup/model-providers/about-model-providers#credentials-that-do-not-compile" >}}). | ||
| kagent reaches a model provider through the egress gateway, which holds the credential and adds it to each request as an HTTP header. The three rejected providers authenticate in a way that this design cannot serve: |
Collaborator
There was a problem hiding this comment.
Suggested change
| kagent reaches a model provider through the egress gateway, which holds the credential and adds it to each request as an HTTP header. The three rejected providers authenticate in a way that this design cannot serve: | |
| By default, kagent reaches a model provider through the egress gateway, which holds the credential and adds it to each request as an HTTP header. However, the following providers authenticate in a way that this design cannot serve: |
Nadine2016
reviewed
Oct 15, 2026
| | A subagent binding cannot itself carry tools, skills, plugins, or nested agents, and must use the same provider and credentials as the agent that binds it. | `codex`, `claude` | | ||
| | An {{< gloss "MCP" >}}MCP{{< /gloss >}} server is bound whole. Claude does not support partial tool selection, so the agent sees every tool the server offers rather than only the ones a binding names. The compiler warns rather than failing. | `claude` | | ||
| | A `RemoteMCPServer` must use the `STREAMABLE_HTTP` protocol. `SSE` is rejected. | `codex` | | ||
| | An {{< gloss "MCP" >}}MCP{{< /gloss >}} server is bound whole. Claude does not support partial tool selection, so the agent sees every tool that the server offers. The Agent still reconciles, and reports the decision in `status.warnings` as `Claude RemoteMCPServer "<name>" does not support partial tool selection`. | `claude` | |
Collaborator
There was a problem hiding this comment.
An {{< gloss "MCP" >}}MCP{{< /gloss >}} server is bound whole. >> not sure what this means
Nadine2016
reviewed
Oct 15, 2026
| | `Ready` | Whether Agent Substrate finished preparing the agent's capacity. | | ||
|
|
||
| `Ready` covers the Harness's own dependencies, not whether a given agent runs on it. Whether a template compiles against this Harness is reported on the Agent that pairs the two, because an AgentTemplate does not report status of its own. For that check and the conditions it reports, see [Your first agent]({{< link path="get-started/your-first-agent" >}}). | ||
| An Agent can also reconcile and still report a non-blocking decision in `status.warnings`, such as Claude binding an MCP server whole. For the conditions in full, see [Your first agent]({{< link path="get-started/your-first-agent" >}}). |
Collaborator
There was a problem hiding this comment.
same comment about binding whole
Nadine2016
reviewed
Oct 15, 2026
| This page applies to [declarative agents]({{< link path="agents/declarative-agents" >}}), which run on the `kagent` harness. Compaction is a `spec.kagent` setting, so a Harness that selects `codex`, `claude`, or `byo` does not take compaction settings. Omitting the `compaction` block leaves the history uncompacted. | ||
|
|
||
| Compaction is a `spec.kagent` setting, so it applies to the **kagent runtime only**. A Harness that selects `codex`, `claude`, or `byo` has no compaction settings. Omitting the `compaction` block leaves the history uncompacted. | ||
| Compaction is configured on the {{< gloss "Harness" >}}Harness{{< /gloss >}}, not on the {{< gloss "AgentTemplate" >}}AgentTemplate{{< /gloss >}}. The setting belongs to the runner that drives the root agent, which makes compaction harness policy rather than portable agent behavior. [Agent memory]({{< link path="agents/agent-memory" >}}) follows the same Harness-versus-AgentTemplate split. An AgentTemplate cannot enable, disable, or tune compaction on its own. |
Collaborator
There was a problem hiding this comment.
which makes compaction harness policy rather than portable agent behavior >> I feel like something is missing in this sentence
Nadine2016
approved these changes
Oct 15, 2026
Takes Nadine's suggestions on the Harness field table and the Choose a harness intro. The intro sentence they replace counted the ways the harnesses differ, which goes stale the moment a fifth difference appears. Drops "an MCP server is bound whole" in both places it appeared. The clause after it already said the same thing in plain words, so the phrase carried no information a reader could not get from the rest of the row. Replaces "which makes compaction harness policy rather than portable agent behavior" with the consequence it was gesturing at: the same AgentTemplate compacts differently on two Harnesses that set different values. Moves the agent memory pointer to the end so the paragraph finishes on compaction. Normalizes the label for the set of four. The pages had drifted into four names for one thing -- "harness types", "options", "ways", and "harnesses" -- so they all say harnesses now. Where that collided with the resource of the same name, the resource takes the longer form. On the provider rejection sentence, takes "However" and "the following providers" but not "By default". Every model call reaches the provider through the egress gateway, so only the credential-holding half varies, and whether apiKeyPassthrough survives the gateway's header injection is still an open REVIEW note on about-model-providers.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reworks the Agent harness page, and corrects claims on the pages that share its subject matter.
The harness page is now organized around choosing a runtime.
kagent,codex,claude, andbyoeach get a section carrying that runtime's settings, limits, and a complete example, replacing the old split between a comparison table, a settings section, and two examples.Several claims were wrong. kagent#3153 removed the controller-owned telemetry variable list in 1.0.0-alpha13, so a Harness that sets one of those variables now overrides the installation default. The page said it was rejected. The provider matrix called
Mistralunresolvable, though it has worked since alpha7, and gave a single rejection reason for three providers that fail in two different ways. The readiness section pointed readers at a HarnessREADYcolumn that nothing writes. References to a Python engine are gone.Worth a close look: the telemetry sections. The ownership model inverted, so those paragraphs are rewritten rather than edited.