docs: add AI Agent Runtime capability page (Agent Sessions API) - #2345
Open
wasaga wants to merge 5 commits into
Open
docs: add AI Agent Runtime capability page (Agent Sessions API)#2345wasaga wants to merge 5 commits into
wasaga wants to merge 5 commits into
Conversation
✅ Deploy Preview for pomerium-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Greptile SummaryAdds an early-access AI agent runtime capability page and registers it in site navigation and LLM-facing documentation outputs.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| content/docs/capabilities/agentic-runtime.mdx | Adds the complete capability narrative, configuration examples, API flow, and threat-model discussion; no eligible follow-up defect was established. |
| plugins/llms-txt-plugin.js | Adds the new route to curated and Tier 1 outputs; its current route resolves and available bundle headroom avoids the hypothesized size-limit condition. |
| sidebars.js | Registers the new page under Capabilities using the matching document ID. |
| src/css/custom.css | Adds light/dark diagram visibility rules keyed to Docusaurus's data-theme attribute; no eligible follow-up defect was established. |
Sequence Diagram
sequenceDiagram
participant Client
participant Sessions as Agent Sessions API
participant Sandbox
participant Pomerium
participant Upstream
Client->>Sessions: Create session and prompt
Sessions->>Sandbox: Claim pod and launch agent
Sandbox->>Pomerium: Request with approved run token
Pomerium->>Pomerium: Evaluate policy and inject secret
Pomerium->>Upstream: Forward authorized request
Reviews (2): Last reviewed commit: "docs: theme-aware diagrams — dark varian..." | Re-trigger Greptile
desimone
reviewed
Aug 13, 2026
| policy: | ||
| allow: | ||
| and: | ||
| - claim/email: alice@example.com # who approved |
desimone
reviewed
Aug 13, 2026
| ```yaml | ||
| policy: | ||
| allow: | ||
| and: |
nickytonline
left a comment
nickytonline
left a comment
Member
There was a problem hiding this comment.
Also, should we mention that this is a k8s only solution? I know we mention k8s throughout the docs, but probably good to mention it up front?
|
|
||
| You want an agent to do real work: read tickets, query a database, call an internal API, open a pull request. Real work needs credentials. But an agent is a program that takes instructions from untrusted text. Give it an API key, and you have given the key to anyone who can influence its input — a hostile issue comment, a poisoned dependency README, a malicious tool description. | ||
|
|
||
| The usual mitigations try to make the agent careful. Careful is not a security boundary. The alternative is an architecture in which the agent has nothing to leak: it runs in a sandbox with no secrets, and everything it is allowed to reach sits behind a gateway that decides, per request and deterministically, whether this agent, acting for this person, may reach this resource. |
Member
There was a problem hiding this comment.
maybe mention an example of this like hooks in a harness?
|
|
||
| The layers, from enforcement up to product: | ||
|
|
||
| - **Pomerium** is the gateway. It authenticates every request against your identity provider, evaluates a deterministic policy, injects the credentials the upstream needs, and logs the result. In the reference configuration, every credentialed request a sandbox makes leaves through it. |
Member
There was a problem hiding this comment.
This sounds a bit weird the last phrase in this bullet point.
Suggested change
| - **Pomerium** is the gateway. It authenticates every request against your identity provider, evaluates a deterministic policy, injects the credentials the upstream needs, and logs the result. In the reference configuration, every credentialed request a sandbox makes leaves through it. | |
| - **Pomerium** is the gateway. It authenticates every request against your identity provider, evaluates a deterministic policy, injects the credentials the upstream needs, and logs the result. In the reference configuration, all outbound requests from a sandbox that require credentials are routed through Pomerium. |
|
|
||
| - **Pomerium** is the gateway. It authenticates every request against your identity provider, evaluates a deterministic policy, injects the credentials the upstream needs, and logs the result. In the reference configuration, every credentialed request a sandbox makes leaves through it. | ||
| - **The sandbox pod** runs your agent next to a sidecar. The agent container holds no credentials of any kind. The sidecar holds the pod's credentials and proxies the agent's traffic to Pomerium. | ||
| - **The Agent Sessions API** manages sessions: it claims sandbox pods, launches agents in them, streams their output as durable events, and suspends and revives them. |
Member
There was a problem hiding this comment.
Probably need to mention destroying the pods too?
Suggested change
| - **The Agent Sessions API** manages sessions: it claims sandbox pods, launches agents in them, streams their output as durable events, and suspends and revives them. | |
| - **The Agent Sessions API** manages sessions: it claims sandbox pods, launches agents in them, streams their output as durable events, and suspends, revives them or terminates them. |
| P-->>S: policy evaluated, credentials injected | ||
| ``` | ||
|
|
||
| Each hop carries a different credential: the manager's workload token, the person's SSO session, the pod's projected token, the run token. None of them can stand in for another. |
Member
There was a problem hiding this comment.
Should manager be orchestrator to keep wording uniform? Or is manager something else in this context?
Suggested change
| Each hop carries a different credential: the manager's workload token, the person's SSO session, the pod's projected token, the run token. None of them can stand in for another. | |
| Each hop carries a different credential: the orchestrator's workload token, the person's SSO session, the pod's projected token, the run token. None of them can stand in for another. |
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
3 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.
Summary
Adds a new capabilities page, Run AI Agents in Isolated Sandboxes (
/docs/capabilities/agentic-runtime), documenting the agentic runtime: run identity, the Agent Sessions API, and the sandbox model.The page is written for a reader who has never heard of Pomerium. It opens with the problem (agents take instructions from untrusted text, so a key given to an agent is a key given to its input), then walks the stack bottom-up: Pomerium as the policy-enforcing gateway with gateway-side secret injection (
${secret.…}references), run identity binding a human approval to an attested pod (act.*claims,bearer_token_format: agentic_run_token), the two-container sandbox pod built on Kubernetes agent-sandbox, the Agent Sessions API (sessions/turns/events), client tiers (SDKs, companion, polling), a compromised-component analysis, and positioning.Includes two D2-sourced SVG diagrams (committed with their
.d2sources, house style), two mermaid sequence diagrams, sidebar registration, and llms-txt route entries.Docs link: https://deploy-preview-2345--pomerium-docs.netlify.app/docs/capabilities/agentic-runtime
AI disclosure
Claude Code drafted the page and diagrams.
Checklist