|
| 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