Skip to content

Commit 9699e88

Browse files
authored
docs(caller_principal): API server section and limitations
Documents the unauthenticated default on /run and /run_sse, the request.state.caller_principal convention for deployments that authenticate in middleware, and the strict-mode note for the adk web dev UI. Rewrites the limitations bullet: /run_live sessions still carry no principal.
1 parent d4ff60a commit 9699e88

1 file changed

Lines changed: 41 additions & 2 deletions

File tree

  • docs/guides/agents/caller_principal

‎docs/guides/agents/caller_principal/index.md‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,43 @@ principal for every request. With the default settings that yields a warning
109109
per approval and the approval is honored, which is the behavior those
110110
deployments had before the principal existed.
111111

112+
### ADK API server
113+
114+
The `/run` and `/run_sse` routes of the ADK API server (`adk api_server`,
115+
`adk web`, `get_fast_api_app`) record a principal on every invocation as
116+
well. The server does not authenticate callers itself, and the `user_id` in
117+
the request body is a claim the caller made rather than one the server
118+
checked, so without anything in front of these routes every request runs as
119+
`CallerPrincipal(authenticated=False, source="api_server")`. With the default
120+
settings that is a warning per approval, as for an unauthenticated A2A caller.
121+
122+
A deployment that authenticates callers in front of these routes, with an
123+
identity-aware proxy, a gateway or its own middleware, states the result on
124+
`request.state.caller_principal`, and the server uses that value as is:
125+
126+
```python
127+
from google.adk.agents import CallerPrincipal
128+
from google.adk.cli.fast_api import get_fast_api_app
129+
130+
app = get_fast_api_app(agents_dir="./agents", web=False)
131+
132+
133+
@app.middleware("http")
134+
async def record_caller(request, call_next):
135+
# Your authenticator decides who sent this request; report that outcome.
136+
user = verify_request(request) # None when the request is not authenticated.
137+
if user is not None:
138+
request.state.caller_principal = CallerPrincipal(
139+
authenticated=True, user_name=user.name, source="gateway"
140+
)
141+
return await call_next(request)
142+
```
143+
144+
Under strict mode, approvals arriving on `/run` or `/run_sse` are refused
145+
unless the deployment sets the principal this way. The dev UI served by `adk
146+
web` has no authentication of its own, so run it without strict mode, or add
147+
middleware that recognizes its operator.
148+
112149
### Strict mode
113150

114151
Strict mode refuses confirmations from unauthenticated callers instead of
@@ -194,5 +231,7 @@ decision stays uniform across all of them.
194231
- The synchronous `Runner.run` wrapper and live sessions do not accept a
195232
principal. Both behave as in-process callers.
196233
- Setting a principal does not authenticate anything by itself. The ADK API
197-
server's `/run` endpoint still requires its own authentication; the principal
198-
records the outcome of authentication, it does not perform it.
234+
server's `/run` and `/run_sse` routes record an unauthenticated principal
235+
unless the deployment's own authentication sets one; the principal records
236+
the outcome of authentication, it does not perform it. `/run_live` sessions
237+
do not carry a principal.

0 commit comments

Comments
 (0)