Skip to content

Commit 1aa91f1

Browse files
authored
docs(agents): add the CallerPrincipal unit guide
Required for a new source unit by check-new-py-prefix. Follows the adk-unit-guide template: get started, how it works, the three principal states, strict mode, configuration options, limitations. For google#6461.
1 parent e0983bd commit 1aa91f1

1 file changed

Lines changed: 188 additions & 0 deletions

File tree

  • docs/guides/agents/caller_principal
Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# CallerPrincipal
2+
3+
`CallerPrincipal` records whether a serving layer authenticated the caller of
4+
an invocation, and as whom. The human-in-the-loop tool confirmation flow reads
5+
it to decide whether an approval that arrived over the wire is one the agent
6+
may act on.
7+
8+
## Introduction
9+
10+
A tool that requires confirmation pauses the agent until a user approves the
11+
call. When the agent is served remotely, the approval arrives as a message on
12+
the same channel as everything else the remote caller sends, so without a
13+
principal the framework cannot tell an operator's approval from a remote peer
14+
approving the dangerous tool call it just caused. `CallerPrincipal` carries the
15+
one fact that decides this: whether the layer that received the request
16+
verified who sent it.
17+
18+
The principal lives on `InvocationContext.caller_principal`. `Runner.run_async`
19+
accepts it as a keyword argument, and the A2A executor sets it for every
20+
request it serves, so an application that serves agents over A2A gets it
21+
without writing any code. An application with its own serving layer sets it
22+
from its own authenticator.
23+
24+
The design keeps the principal separate from the transport on purpose. A
25+
transport is a proxy for identity, and a proxy for identity fails in both
26+
directions: it refuses authenticated callers because of how they connected,
27+
and it admits anyone who reaches a path the proxy does not cover. Asking the
28+
authentication question directly avoids both failures.
29+
30+
## Get started
31+
32+
This example serves an agent behind an application's own request handler. The
33+
handler runs its authenticator first, then tells the runner what it found. A
34+
confirmation-gated tool is included so that the principal has something to
35+
decide.
36+
37+
```python
38+
from google.adk.agents import CallerPrincipal
39+
from google.adk.agents import LlmAgent
40+
from google.adk.runners import InMemoryRunner
41+
from google.adk.tools.bash_tool import ExecuteBashTool
42+
43+
agent = LlmAgent(name="ops_agent", tools=[ExecuteBashTool()])
44+
runner = InMemoryRunner(agent=agent, app_name="ops")
45+
46+
47+
async def handle_request(request, new_message):
48+
# Your authenticator runs before this point. Report what it established;
49+
# do not infer anything from the message the caller sent.
50+
user = request.authenticated_user
51+
principal = CallerPrincipal(
52+
authenticated=user is not None,
53+
user_name=user.name if user else None,
54+
source="gateway",
55+
)
56+
async for event in runner.run_async(
57+
user_id=request.user_id,
58+
session_id=request.session_id,
59+
new_message=new_message,
60+
caller_principal=principal,
61+
):
62+
yield event
63+
```
64+
65+
An in-process caller, such as a test or a command-line tool that calls
66+
`runner.run_async` directly, does not pass a principal. Leaving it unset says
67+
that no remote trust boundary was crossed, which is true for that caller.
68+
69+
## How it works
70+
71+
`InvocationContext.caller_principal` has three meaningful states, and the tool
72+
confirmation flow treats each differently.
73+
74+
| State | Meaning | Tool confirmation |
75+
| :--- | :--- | :--- |
76+
| `None` | The invocation started in process. Nothing had to vouch for the caller, because the caller is the operator. | Honored. |
77+
| `authenticated=False` | A serving layer handled the request and could not say who sent it. | Warned about by default; refused when strict mode is on. |
78+
| `authenticated=True` | The serving layer verified the caller. | Honored. |
79+
80+
A refusal is explicit rather than silent. The confirmation is delivered to the
81+
tool with `confirmed=False`, which is the same state a user's decline produces,
82+
so a tool that follows the confirmation contract returns its rejection response
83+
and the turn ends with a reason the caller can see. The pending call never
84+
hangs waiting for an approval that will not come.
85+
86+
The principal is derived only from what the serving layer established. It is
87+
never read from message content, from event authorship, or from transport
88+
metadata, because a remote caller controls all three and could set any of them
89+
to whatever the framework wanted to see.
90+
91+
### A2A
92+
93+
`A2aAgentExecutor` builds the principal from the A2A server's call context on
94+
every request. The caller is authenticated exactly when the A2A server
95+
authenticated it, which is also the case in which the invocation's user id is
96+
the authenticated user name rather than a generated `A2A_USER_` value. The two
97+
cannot disagree about the same request.
98+
99+
An A2A server that runs without an authenticator produces an unauthenticated
100+
principal for every request. With the default settings that yields a warning
101+
per approval and the approval is honored, which is the behavior those
102+
deployments had before the principal existed.
103+
104+
### Strict mode
105+
106+
Strict mode refuses confirmations from unauthenticated callers instead of
107+
warning about them. It is the `STRICT_CALLER_PRINCIPAL` feature and is off by
108+
default, because turning it on changes what an existing deployment does with an
109+
approval, and an upgrade should not do that on its own. The intent is to make
110+
strict mode the default at the next major version.
111+
112+
Turn it on with the environment variable ADK uses for every feature:
113+
114+
```bash
115+
export ADK_ENABLE_STRICT_CALLER_PRINCIPAL=1
116+
```
117+
118+
Or programmatically, when environment variables are not practical in your
119+
deployment:
120+
121+
```python
122+
from google.adk.features import FeatureName
123+
from google.adk.features import override_feature_enabled
124+
125+
override_feature_enabled(FeatureName.STRICT_CALLER_PRINCIPAL, True)
126+
```
127+
128+
Strict mode never affects an invocation with no principal. An in-process
129+
caller crossed no boundary, so there is nothing to refuse.
130+
131+
## Configuration options
132+
133+
`CallerPrincipal` is a frozen model with three fields. It rejects unknown
134+
fields, so a typo cannot silently produce a principal that says nothing.
135+
136+
| Option | Type | Default | Description |
137+
| :--- | :--- | :--- | :--- |
138+
| `authenticated` | `bool` | required | Whether a serving-layer authenticator verified the caller. |
139+
| `user_name` | `str \| None` | `None` | The verified identity when `authenticated` is `True`. |
140+
| `source` | `str \| None` | `None` | A short label for the serving edge that set the principal. |
141+
142+
`authenticated` is the only field a trust decision reads. Set it to `True` only
143+
when your authenticator actually verified the caller. A request that carries a
144+
name it asserted about itself, without verification, is not authenticated, and
145+
saying otherwise reopens the problem the principal exists to close.
146+
147+
`user_name` is informational. It is the identity the authenticator established,
148+
kept alongside the decision so that a log line or an audit record can say who
149+
approved a tool call. Leave it `None` when `authenticated` is `False`; a name
150+
without verification behind it is a claim, not an identity.
151+
152+
`source` is a label such as `"a2a"` or `"gateway"` that names the edge that
153+
set the principal. It appears in the confirmation flow's log messages so that
154+
an operator reading a warning can tell which entry point produced it. Nothing
155+
makes a trust decision on it, so a transport cannot become a proxy for identity
156+
through this field either.
157+
158+
## Advanced applications
159+
160+
### Custom A2A request converters
161+
162+
`A2aAgentExecutorConfig.request_converter` lets an application replace the
163+
function that turns an A2A request into a run request. The executor sets the
164+
principal from the server's call context after the converter returns,
165+
regardless of what the converter produced. A converter can therefore neither
166+
drop the principal nor assert one the server never established, which keeps
167+
the trust decision structural rather than dependent on every converter
168+
remembering to make it.
169+
170+
### Serving layers with more than one entry point
171+
172+
An application that exposes an agent through several edges can give each a
173+
distinct `source` and let them share the same rule for `authenticated`. The
174+
confirmation flow's log messages then identify the edge, and the trust
175+
decision stays uniform across all of them.
176+
177+
## Limitations
178+
179+
- The principal describes the caller of the invocation as a whole. ADK does
180+
not verify the identity behind each individual event within a session.
181+
- Only the tool confirmation flow reads the principal today. Other consumers
182+
can read `InvocationContext.caller_principal`, but the framework does not
183+
yet gate anything else on it.
184+
- The synchronous `Runner.run` wrapper and live sessions do not accept a
185+
principal. Both behave as in-process callers.
186+
- Setting a principal does not authenticate anything by itself. The ADK API
187+
server's `/run` endpoint still requires its own authentication; the principal
188+
records the outcome of authentication, it does not perform it.

0 commit comments

Comments
 (0)