Rewrite conceptual and operational info

[Rachael-Graham]

No description provided.

[github-actions]

Docs preview

Link	Points at
Branch preview	The newest push to this branch. Updates in place.
Commit preview	b37924d only. Frozen.

Both are uploaded Worker versions and serve no production traffic.

[Nadine2016]

and kagent declares nothing for a Session >> not sure how this relates to the sentence before where everything it needs is declared in the ActorTemplate. Also this paragraph is about placing the actor on a worker and it is hard to understand why we suddenly talk about the session

[Nadine2016]

maybe make this a note

[Nadine2016]

same comment as earlier

[Nadine2016]

Suggested change

Agent Substrate reports pool capacity through its metrics rather than through an error that reaches the caller. Each Worker publishes a state of `idle`, `partial`, `at_capacity`, or `unschedulable`, which together show how much of a pool is in use, and a placement that finds no suitable Worker records a `no_capacity` outcome. Agent Substrate treats this outcome as a normal result rather than a failure, so it carries no error type and raises no alert on its own. Watch the share of Workers at `at_capacity` and the rate of `no_capacity` placements to tell a pool that is merely busy from one that is too small.

Agent Substrate reports pool capacity through its metrics rather than through an error that reaches the caller. Each Worker publishes a state of `idle`, `partial`, `at_capacity`, or `unschedulable`, which together show how much of a pool is in use. A placement that finds no suitable Worker records a `no_capacity` outcome. Agent Substrate treats this outcome as a normal result rather than a failure, so it carries no error type and raises no alert on its own. Watch the share of Workers at `at_capacity` and the rate of `no_capacity` placements to tell a pool that is merely busy from one that is too small.

[Nadine2016]

Suggested change

	None of those signals reach the caller. A turn that cannot get a Worker waits for one, and a turn that waits too long fails with a generic timeout that names neither capacity nor the pool.
	None of those signals reach the caller. A turn that cannot get a Worker waits for one, and a turn that waits too long fails with a generic timeout.

[Rachael-Graham]

Kept the trailing clause, "that names neither capacity nor the pool." It is the diagnostic point of the sentence: the timeout gives an operator nothing to connect back to pool capacity, which is why the section sends them to the metrics instead.

[Nadine2016]

Suggested change

Because short turns release their capacity quickly, a pool under mild pressure absorbs the load and only sheds the requests that wait past the deadline. The result is intermittent timeouts under concurrency rather than a clean failure. Neither the kagent controller log nor the Agent Substrate API log records a capacity message when this happens, so confirm the diagnosis from the `at_capacity` and `no_capacity` signals and from the pool's `READY` count, then raise the replica count.

Because short turns release their capacity quickly, a pool under mild pressure absorbs the load and only sheds the requests that wait past the deadline. The result is intermittent timeouts under concurrency rather than a clean failure. Neither the kagent controller log nor the Agent Substrate API log records a capacity message when this happens, so confirm the diagnosis from the `at_capacity` and `no_capacity` signals and from the pool's `READY` count. If you notice Worker pressure, raise the replica count.

[Nadine2016]

does that mean, I can set this to test and it will point to google cloud storage?

[Nadine2016]

just confirming that there would not be any helm settings? if so, maybe we should explicitly say that. and maybe link to google docs for workload identity

[Nadine2016]

we should explain what these envs are

[Nadine2016]

Suggested change

	4. Run a turn on an agent, suspend its Actor, and compare the `latestSnapshot` path [in the response](#inspect-the-runtime) against the `location` that you set. Because the backend and the location are configured separately, a mismatch between them breaks resume rather than install. Confirm the result rather than the intent.
	4. Run a turn on an agent, suspend its Actor, and compare the `latestSnapshot` path [in the response](#inspect-the-runtime) against the `location` that you set. Because the backend and the location are configured separately, a mismatch between them breaks resuming an Actor from its snapshot later.

[Nadine2016]

what is both referring to here?

[Nadine2016]

sounds like you need to install an instance in any case?

[Nadine2016]

the last sentence should say somethign like When you enable client certificates with the ... setting, ....

right now, it is hard to understand where sslcert and sslkey are coming from. I am assuming those are sub fields under that setting, but not sure.

[Nadine2016]

Suggested change

	> The development database is a single pod backed by one PersistentVolumeClaim, and `kagent install` sizes that claim at 500Mi. Losing the pod's volume loses every Session and every compiled revision, so move a production installation to a PostgreSQL instance of your own.
	> The development database is a single pod backed by one PersistentVolumeClaim, and `kagent install` sizes that claim at 500Mi. Losing the pod's volume loses every Session and every compiled revision, so move a production installation to a PostgreSQL instance that you manage.

[Nadine2016]

we say the connection string must reference the files, but this is not true in the connection string above

[Nadine2016]

maybe a different word than survive. it is hard to understand what this means

[Nadine2016]

thinking you can remove the helm3/4 sentences as those refer to when you edit the secret directly, which is not what we want them to do

[Rachael-Graham]

Keeping these. The review feedback this PR addresses asks specifically to move the providers.<provider>.apiKey, Helm ownership, and upgrade-conflict explanation into a second "Helm manages the Secret" tab, which is where they now sit. They tell a reader who already set the key in Helm values why a direct Secret edit will not hold.

[Nadine2016]

Expiry bounds Sessions, not history > needs another title as we are not talking about expiration, but deletion.

[Rachael-Graham]

Retitled to "Expiry deletes the Session, not its history." Keeping expiry in the label, because expiry is what triggers the deletion and the section is about the idle TTL, but the callout now names deletion as you asked.

[Nadine2016]

I think we need a different first sentence

[Rachael-Graham]

Removed the paragraph rather than rewriting it. The review feedback asks to move the creation-request-ID behavior to a more suitable topic, so I folded the fact into the existing REVIEW comment until a Sessions reference page exists to hold it.

[Nadine2016]

Suggested change

An agent spends most of its life waiting. It waits on a person to reply, and it waits on a large language model (LLM) to answer. [Agent Substrate]({{< link path="about/architecture/agent-substrate" >}}) runs each agent inside an **Actor**, the unit that it suspends and resumes. Rather than hold compute open through that waiting, Agent Substrate writes the idle Actor to a {{< gloss "Snapshot" >}}snapshot{{< /gloss >}} and releases the capacity that the Actor held on its {{< gloss "Worker" >}}Worker{{< /gloss >}}. The next message restores it. The {{< gloss "Session" >}}Session{{< /gloss >}} stays ready the whole time, so reclaiming this capacity costs the user nothing. This page explains what a snapshot captures, when kagent suspends an Actor, and what happens when a suspended Actor is addressed again.

An agent spends most of its life waiting. It waits on a person to reply, and it waits on a large language model (LLM) to answer. [Agent Substrate]({{< link path="about/architecture/agent-substrate" >}}) runs each agent inside an **Actor**, the unit that suspends and resumes the agent. To free up compute resources while waiting for an agent to resume, Agent Substrate writes the idle Actor to a {{< gloss "Snapshot" >}}snapshot{{< /gloss >}} and releases the capacity that the Actor held on its {{< gloss "Worker" >}}Worker{{< /gloss >}}. The next message to the agent restores the Actor. The {{< gloss "Session" >}}Session{{< /gloss >}} stays ready the whole time, so reclaiming this capacity costs the user nothing. This page explains what a snapshot captures, when kagent suspends an Actor, and what happens when a suspended Actor is addressed again.

[Rachael-Graham]

Took this with one change: "the unit that Agent Substrate suspends and resumes" rather than "the unit that suspends and resumes the agent." Agent Substrate performs the suspend, not the Actor.

[Nadine2016]

I don't understand the first sentence

[Nadine2016]

Suggested change

	Outbound traffic leaves a Worker through the egress gateway rather than directly out. This chokepoint gives Agent Substrate one place to decide what each agent can reach. The gateway takes three steps on every connection, and each step depends on the one before it, because the Actor's identity selects the policy, and the policy supplies the rules.
	All outbound traffic leaves a Worker through the egress gateway, which gives Agent Substrate one place to decide what each agent can reach. The gateway takes three steps on every connection, and each step depends on the one before it, because the Actor's identity selects the policy, and the policy supplies the rules.

[Nadine2016]

Suggested change

	2. The gateway fetches the `EgressPolicy` for this Actor. Each Actor has at most one `EgressPolicy` named `default`, and Agent Substrate addresses the policy by the Actor rather than by this name. An Actor with no policy reaches nothing, because a policy is the only thing that allows a destination.
	2. The gateway fetches the `EgressPolicy` for this Actor. Each Actor has at most one `EgressPolicy` named `default`, and Agent Substrate addresses the policy by the Actor rather than by this name. An Actor with no policy reaches nothing, because a policy is the only thing that allows access to a destination.

[Rachael-Graham]

Took your "access to a destination" fix but changed the subject. The review feedback asks to name the gateway as the thing that denies, because a default-deny policy does not stop an Actor from attempting a request, so the sentence now reads: "The gateway denies every request from an Actor that has no policy, because only a policy allows access to a destination."

[Nadine2016]

Suggested change

The verified identity holds the other two steps together. The Actor's identity is established only by the certificate, so the gateway authorizes every request against the Actor that actually sent it regardless of the headers or hostnames that the request carries. The gateway refuses a connection that does not present a certificate rather than falling back to a default identity. Each Actor also gets its own connection pool, even when two of them dial the same address, so that every connection carries requests from the one Actor that opened it.

The Actor's identity is established only by the certificate, so the gateway authorizes every request against the Actor that actually sent it regardless of the headers or hostnames that the request carries. The gateway refuses a connection that does not present a certificate rather than falling back to a default identity. Each Actor also gets its own connection pool, even when two of them dial the same address, so that every connection carries requests from the one Actor that opened it.

[Rachael-Graham]

Took the body of this but kept a lead sentence. The review feedback asks the page to explain why the verified Actor identity matters for policy enforcement, so the paragraph now opens with "Policy enforcement depends on this verified identity."

[Nadine2016]

Suggested change

	A rule's type fixes the kind of connection it covers and the place that the gateway reads the destination hostname from. Three types cover the three cases.
	Each rule defines the type of connection that is allowed to a destination and how the gateway determines the destination's hostname. The following connection types are allowed:

[Nadine2016]

Suggested change

	- **`http`**: Cleartext HTTP, meaning HTTP/1.1 and the h2c that gRPC uses. The gateway reads the `Host` header and matches it against the rule's hostnames. TLS to those same names is not allowed by this rule.
	- **`http`**: Cleartext HTTP, meaning HTTP/1.1 and the h2c that gRPC uses. The gateway reads the hostname from the `Host` header and matches it against the rule's hostnames. TLS to those same names is not allowed by this rule.

[Nadine2016]

Suggested change

	All three rule types cover TCP connections. Agent Substrate blocks UDP, and it does not support a protocol in which the server sends the first bytes once the connection opens, such as SMTP or SSH. The gateway reads the destination hostname from the bytes that the client sends first, so those protocols leave the gateway nothing to match against.
	All three rule types cover TCP connections. Agent Substrate blocks UDP, and it does not support a protocol in which the server sends the first bytes once the connection opens, such as SMTP or SSH. The gateway reads the destination hostname from the bytes that the client sends first, so those protocols leave the gateway with nothing to match against.