[github-actions]

kagent-dev/kagent#3362 — feat(api): resolve Agent metadata from scoped Actor tokens

Docs versions: 1.x (first shipped in v1.0.0-rc1)

No code-path rule covers 11 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/agent-identity-lookup.md
• go/api/gen/kagent/api/v1/agent_identity.pb.go
• go/api/gen/kagent/api/v1/agent_identity_grpc.pb.go
• go/core/internal/grpcserver/agent_identity.go
• go/core/internal/grpcserver/interceptors.go
• go/core/internal/grpcserver/policy.go
• ...and 5 more

What changes for users: Downstream services that receive a scoped Actor JWT can call AgentIdentityService.ResolveAgentIdentity to learn which Agent the runtime represents. The token must include kagent-agent-info, must not include kagent-runtime, and the response includes Agent metadata plus sessionId and runtimeRevision.

What the docs now say: The Identity concept page now explains the Agent identity lookup RPC, its token audience boundary, the Agent metadata that it returns, and that returning sessionId does not grant Session API access.

Not verified: No cluster; the configuration is unrun, and internal links are unchecked.

How kagent-3362 was drafted, and what was not verified

• Code PR: feat(api): resolve Agent metadata from scoped Actor tokens kagent#3362
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x; first shipped in v1.0.0-rc1
• Category: scoped-edit / pr
• Possibly incomplete: feat(auth): add gateway Actor JWT credentials kagent#3359 — feat(auth): add gateway Actor JWT credentials, because feat(api): resolve Agent metadata from scoped Actor tokens kagent#3362 depends on it.

Plan, and what changed it

• Planned: Add the Agent identity lookup behavior to the Agent Substrate identity page.
• Learned: neighbors/kagent-3359.md carries the Actor JWT configuration surface, so this item should document only the lookup behavior that the code diff adds.
• Did: Added a short conceptual section to docs-site/content/kagent/1.x/about/substrate-runtime/identity.md.

Why a documentation change is necessary

The pull request adds AgentIdentityService.ResolveAgentIdentity, a new RPC for downstream services that need to map an Actor token back to the Agent and Session revision that it represents. The target Identity page already explains runtime Actor tokens and the kagent-runtime audience, but it did not mention the new kagent-agent-info lookup audience or the sessionId and runtimeRevision response fields. Without this section, readers would not know that lookup tokens use a separate audience and cannot be reused for Session API access.

What changed on disk

• docs-site/content/kagent/1.x/about/substrate-runtime/identity.md — added the Agent identity lookup section under Agent runtime calls.

How to verify this change

1. In a kagent 1.x cluster, configure a downstream model or service to receive an Actor JWT with both its own audience and kagent-agent-info, then run a Session that calls that service.
2. Capture the downstream request's bearer token, port-forward the controller, and call the lookup RPC:

   grpcurl -plaintext \
     -H "Authorization: Bearer $ACTOR_JWT" \
     -d '{}' \
     localhost:8083 kagent.api.v1.AgentIdentityService/ResolveAgentIdentity

3. The response shows the Agent namespace, name, UID, labels, annotations, sessionId, and runtimeRevision; the same token fails against kagent.api.v1.SessionService/GetSession with Unauthenticated.

Proposed release note

No proposed-release-note.md file: markers.notes_placeable is false. Suggested note text: Downstream services can now call AgentIdentityService.ResolveAgentIdentity with a scoped Actor JWT to resolve the Agent namespace, name, UID, labels, annotations, the bound Session ID, and the pinned runtime revision.

What was not verified

• The configuration was not applied to a cluster, so the change is unrun.
• Hugo was not run, so internal links are unchecked.

How the pages were chosen (triage report)

Feature clusters

These clusters look incomplete. Each names a pull request this run never saw, so documenting the cluster as it stands may describe half a feature — the classic failure is a guide telling a reader to set a field that a later change gave a default. Read the absent pull request before drafting:

Cluster	Missing	What it is	Why it matters
c8	kagent-dev/kagent#3359	feat(auth): add gateway Actor JWT credentials (merged)	kagent-dev/kagent#3362 depends on it

Draft a documentation change

kagent-dev/kagent#3362 — feat(api): resolve Agent metadata from scoped Actor tokens

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): An Actor JWT identifies the runtime, but downstream services also need to know which Kagent Agent it represents. This PR adds AgentIdentityService.ResolveAgentIdentity, returning the Agent's namespace, name, UID, labels, and annotations, plus the bound Session ID and its pinned runtime revision.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 11 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/agent-identity-lookup.md
  • go/api/gen/kagent/api/v1/agent_identity.pb.go
  • go/api/gen/kagent/api/v1/agent_identity_grpc.pb.go
  • go/core/internal/grpcserver/agent_identity.go
  • go/core/internal/grpcserver/interceptors.go
  • go/core/internal/grpcserver/policy.go
  • ...and 5 more

Draft branch: pr-tracker-draft-kagent-3362

[Rachael-Graham]

Covered by #652 (v1.0.0-rc1 docs update).