Repository navigation
Feedback - Examples section - #609
Conversation
Docs preview
Both are uploaded Worker versions and serve no production traffic. |
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
|
|
||
| Underneath, the checkpoint attaches a {{< gloss "Tag" >}}Tag{{< /gloss >}} named `checkpoint-<checkpoint-id>` to the snapshot, and Agent Substrate does not collect a snapshot while a tag names it. You can see the tag by running `kubectl ate get tags --atespace kagent`. | ||
|
|
||
| ## Forking is temporarily unavailable |
There was a problem hiding this comment.
Blocking: kagent#3165, which moves suspension to DATA snapshots and makes forking possible, merged to main today. The docs pin 1.0.0-alpha13, which does not contain that commit, so ForkSession still returns FAILED_PRECONDITION on the documented version.
Removing this section also breaks the #forking-is-temporarily-unavailable links in about/substrate-runtime/suspend-and-resume.md:88 and observability/launch-ui.md:103. These places still say that forking is unavailable:
about/core-concepts.md:154about/substrate-runtime/suspend-and-resume.md:88observability/launch-ui.md:103- the
fork_sessionrow atexamples/agents-via-mcp.md:516 - the REVIEW comment at
operations/operational-considerations.md:253
Can we either keep these notes until the next kagent release, or update all of those places in this PR? If forking is in scope now, a fork step could replace this section. The same applies to the two removals in agents-via-mcp.md.
|
|
||
| 2. Keep the checkpoint ID if you need to inspect or delete the checkpoint later. | ||
|
|
||
| Forking a checkpoint is temporarily unavailable. The current release stores process memory in suspended Actor snapshots, so `fork_session` returns `FAILED_PRECONDITION` instead of creating a second Session from a checkpoint. |
There was a problem hiding this comment.
Blocking: same as the forking comment on agent-substrate.md. The fork_session row in the MCP tool reference table at line 516 of this page still says that the tool rejects checkpoints, so this page now contradicts itself.
|
|
||
| > [!WARNING] | ||
| > The open source build does not authenticate this port. Any caller that can reach it can invoke any Agent, so do not expose port `8083` outside the cluster. For what the open source build does guarantee, see [Identity]({{< link path="about/substrate-runtime/identity" >}}). | ||
| > A default installation sets `config.server.auth.mode` to `insecure`. In this mode any caller that can reach the port can invoke any Agent. Do not expose port `8083` outside the cluster while the controller runs this way. To take the caller's identity from a claim that a fronting proxy sets instead, set `config.server.auth.mode` to `trusted-proxy` and name the claim in `config.server.auth.userIdClaim`. For the wider identity model, see [Identity]({{< link path="about/substrate-runtime/identity" >}}). |
There was a problem hiding this comment.
Blocking: "while the controller runs this way" implies that trusted-proxy mode makes port 8083 safe to expose. In go/core/internal/httpserver/auth/proxy_authn.go, ProxyAuthenticator decodes the JWT without verifying its signature (its comment says "oauth2-proxy or k8s service account already validated"), and a request that sets X-Agent-Name takes its user ID from X-User-Id. A caller that reaches the port directly can still forge any identity.
The Helm README pairs trusted-proxy with oauth2-proxy.enabled: true. Can the warning say that the port must be reachable only through the authenticating proxy? The same wording is in agents-via-mcp.md:23.
|
|
||
| > [!WARNING] | ||
| > The open source build does not authenticate this endpoint. Every request is accepted, and the caller's identity is read from an `X-User-Id` header that the caller sets itself, defaulting to `admin@kagent.dev`. Because the endpoint can invoke agents, create checkpoints, and create Sessions, do not expose port `8083` outside the cluster. For the wider identity model and what the open source build does guarantee, see [Identity]({{< link path="about/substrate-runtime/identity" >}}). | ||
| > A default installation sets `config.server.auth.mode` to `insecure`. In this mode the endpoint accepts every request and reads the caller's identity from an `X-User-Id` header that the caller sets itself, defaulting to `admin@kagent.dev`. The endpoint can invoke agents, create checkpoints, and create Sessions. Do not expose port `8083` outside the cluster while the controller runs this way. To take the caller's identity from a claim that a fronting proxy sets instead, set `config.server.auth.mode` to `trusted-proxy` and name the claim in `config.server.auth.userIdClaim`. For the wider identity model, see [Identity]({{< link path="about/substrate-runtime/identity" >}}). |
There was a problem hiding this comment.
Should fix: see the trusted-proxy comment on a2a-agents.md:32, which applies here too. Separately, this warning is now six sentences. Consider keeping the alert to the risk and the instruction, and moving the trusted-proxy setup into body text or the Identity page.
| ### A2A methods | ||
|
|
||
| This example calls each method in the following table except the three `TaskPushNotificationConfig` calls, which manage a task's callbacks and which the kagent CLI wraps. The service defines more, including `ListTasks`. `GetTaskPushNotificationConfig` reads a single callback by ID. | ||
| The following table covers the methods that this example uses. The kagent CLI wraps the three `TaskPushNotificationConfig` calls, which manage a task's callbacks. For the further methods that `lf.a2a.v1.A2AService` defines, see the [A2A protocol](https://a2a-protocol.org) specification. |
There was a problem hiding this comment.
Should fix: the earlier text said that this example does not call the three TaskPushNotificationConfig methods. Without that, a reader cannot tell whether the table covers them. The link also goes to the a2a-protocol.org homepage. A link to the methods section of the specification would be more useful.
| An HTTP request that also sets the `tenant` field must set a value that matches its URL. There is no deployment-wide agent card, because the controller serves many Agents. | ||
|
|
||
| A caller addresses the Agent rather than one conversation. The message's `contextId` selects the conversation. Omitting both a `contextId` and a task ID starts a new {{< gloss "Session" >}}Session{{< /gloss >}}, and repeating a `contextId` continues that Session. | ||
| Both forms replace the `/api/a2a/<namespace>/<agent-name>/` URL paths that kagent 0.x served over HTTP. |
There was a problem hiding this comment.
Nit, optional: as a bare paragraph between the table and the contextId paragraph, this sentence reads as part of the addressing rules. It was easier to scan as the > [!NOTE] it replaced. Feel free to ignore.
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
2 participants
No description provided.