<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Google Developer Experts</title>
    <description>The latest articles on DEV Community by Google Developer Experts (gde).</description>
    <link>https://dev.to/gde</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Forganization%2Fprofile_image%2F11939%2Fe3080d5b-ecde-42a8-b089-bafecc31fa97.png</url>
      <title>DEV Community: Google Developer Experts</title>
      <link>https://dev.to/gde</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/gde"/>
    <language>en</language>
    <item>
      <title>One model gateway across clouds: LiteLLM on Cloud Run and Azure with zero API keys</title>
      <dc:creator>Miguel Moreno</dc:creator>
      <pubDate>Sun, 15 Nov 2026 22:23:05 +0000</pubDate>
      <link>https://dev.to/gde/one-model-gateway-across-clouds-litellm-on-cloud-run-and-azure-with-zero-api-keys-3ma7</link>
      <guid>https://dev.to/gde/one-model-gateway-across-clouds-litellm-on-cloud-run-and-azure-with-zero-api-keys-3ma7</guid>
      <description>&lt;p&gt;&lt;em&gt;As of November 2026. All identifiers in this post are examples.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;We built a proof of concept with two AI agents: one on Google Cloud, in Agent Runtime, and one on Azure, in Microsoft Foundry. Each agent has its own identity in Microsoft Entra Agent ID and stores no secret.&lt;/p&gt;

&lt;p&gt;Agents call models. This post covers how ours reach them: a model gateway that runs in both clouds, serves Gemini and Azure OpenAI from either side, and holds no API key for any of it.&lt;/p&gt;

&lt;p&gt;During a demo we switched off the gateway in one cloud. The agent's next answer came through the other one, and we barely noticed the switch.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F89w4gwr9kg6pjhpvr22p.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F89w4gwr9kg6pjhpvr22p.png" alt="Figure 1: the architecture map" width="800" height="540"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Why put a gateway between agents and models
&lt;/h2&gt;

&lt;p&gt;An agent can call a model directly. With two agents that is fine. With fifty it gets uncomfortable:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Every agent needs credentials for every model provider it uses.&lt;/li&gt;
&lt;li&gt;There is no single place that says which agent may use which model.&lt;/li&gt;
&lt;li&gt;Usage is spread across two clouds and two billing consoles.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A model gateway fixes the three at once. Agents talk to one endpoint, and the rules and the usage records live there. We used &lt;a href="https://docs.litellm.ai/" rel="noopener noreferrer"&gt;LiteLLM&lt;/a&gt; because it speaks to both Vertex AI and Azure OpenAI behind one OpenAI-compatible API.&lt;/p&gt;

&lt;p&gt;The catch is that a gateway usually introduces two new kinds of secret: the keys it holds for the model providers, and the keys it hands out to its callers. We wanted neither.&lt;/p&gt;

&lt;h2&gt;
  
  
  The design
&lt;/h2&gt;

&lt;p&gt;There is one LiteLLM in each cloud, with the same configuration:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;On Google Cloud it runs on &lt;strong&gt;Cloud Run&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;On Azure it runs on &lt;strong&gt;Container Apps&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Each one has a Redis sidecar in the same service, for its own short-lived state.&lt;/li&gt;
&lt;li&gt;Both use one shared Postgres database, on &lt;strong&gt;Cloud SQL&lt;/strong&gt;, for agents, allowed models and usage.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each gateway is connected to both model families. The one on Azure can call Gemini, and the one on Google Cloud can call Azure OpenAI. An agent uses the gateway of its own cloud and gets the same catalogue either way.&lt;/p&gt;

&lt;p&gt;The model list is the same file on both sides:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;model_list&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;model_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;gpt-4.1-mini&lt;/span&gt;
    &lt;span class="na"&gt;litellm_params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;azure/gpt-4.1-mini&lt;/span&gt;
      &lt;span class="na"&gt;api_base&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;https://&amp;lt;your-resource&amp;gt;.openai.azure.com/&lt;/span&gt;
  &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;model_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;gemini-3.1-flash-lite&lt;/span&gt;
    &lt;span class="na"&gt;litellm_params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;vertex_ai/gemini-3.1-flash-lite&lt;/span&gt;
      &lt;span class="na"&gt;vertex_project&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;&amp;lt;your-project&amp;gt;&lt;/span&gt;
      &lt;span class="na"&gt;vertex_location&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;global&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;There is no &lt;code&gt;api_key&lt;/code&gt; line anywhere in it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Agents sign in as themselves
&lt;/h2&gt;

&lt;p&gt;LiteLLM normally gives each caller a virtual key. That is one more secret per agent, which is exactly what we wanted to avoid.&lt;/p&gt;

&lt;p&gt;Each agent already has an identity in Microsoft Entra Agent ID and can get a token for any audience it has a role on. So the gateway is one more audience, &lt;code&gt;a2a-llm-gateway&lt;/code&gt;, with one role, &lt;code&gt;LLM.Invoke&lt;/code&gt;. The agent sends its own Entra token as the bearer.&lt;/p&gt;

&lt;p&gt;On the LiteLLM side, a custom auth hook replaces the key lookup. Its core is short:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;_verify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="kt"&gt;dict&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;key&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;_JWKS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get_signing_key_from_jwt&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;key&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;jwt&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;decode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;algorithms&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"RS256"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                      &lt;span class="n"&gt;audience&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="no"&gt;AUDIENCES&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;issuer&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="no"&gt;ISSUER&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                      &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"require"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"exp"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"iss"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"aud"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;user_api_key_auth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;api_key&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;claims&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;asyncio&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;to_thread&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_verify&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;api_key&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="s2"&gt;"LLM.Invoke"&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;claims&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"roles"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="ow"&gt;or&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;Exception&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"forbidden: missing app role LLM.Invoke"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;team&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;get_team_object&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;team_id&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;claims&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"azp"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;   &lt;span class="c1"&gt;# the agent's ID&lt;/span&gt;
    &lt;span class="n"&gt;model&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;_requested_model&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt; &lt;span class="ow"&gt;and&lt;/span&gt; &lt;span class="n"&gt;team&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;models&lt;/span&gt; &lt;span class="ow"&gt;and&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;team&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;Exception&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"forbidden: model '{model}' not allowed for this agent"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;UserAPIKeyAuth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;team_id&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;claims&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"azp"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;team_models&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;team&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;models&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It is wired in with one line of configuration:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;general_settings&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;custom_auth&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;custom_auth.user_api_key_auth&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftmkpup2iyvrb5s1bibf9.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftmkpup2iyvrb5s1bibf9.png" alt="Figure 2: the checks" width="800" height="386"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The caller ID in the token is the agent's identity, and LiteLLM's "team" is keyed by that same ID. So usage is recorded per agent without anyone inventing a second naming scheme.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which agent may use which model
&lt;/h2&gt;

&lt;p&gt;The allow-list comes from the inventory file we use to onboard agents:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;gcp-agent&lt;/span&gt;
  &lt;span class="na"&gt;llm&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;gateway&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;gcp&lt;/span&gt;
    &lt;span class="na"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s"&gt;gemini-3.1-flash-lite&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The onboarding pipeline assigns the &lt;code&gt;LLM.Invoke&lt;/code&gt; role in Entra and creates the team in LiteLLM with those models. An agent that asks for a model outside its list is refused before any provider is called.&lt;/p&gt;

&lt;h2&gt;
  
  
  The gateway holds no model keys either
&lt;/h2&gt;

&lt;p&gt;This is the part that makes the design hold together. Every link from the gateway outwards uses the identity of the workload.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ffx4fgci2xlxiof5urrtl.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ffx4fgci2xlxiof5urrtl.png" alt="Figure 3: the links" width="800" height="431"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;From Google Cloud to Gemini.&lt;/strong&gt; The Cloud Run service account has the Vertex AI role. Nothing to configure.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;From Google Cloud to Azure OpenAI.&lt;/strong&gt; LiteLLM asks Google for an OIDC token and presents it to Entra, where a federated credential on an app registration accepts it. In the model entry it is one line:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;      &lt;span class="na"&gt;azure_ad_token&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;oidc/google/api://AzureADTokenExchange&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;From Azure to Azure OpenAI.&lt;/strong&gt; The Container App's managed identity.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;From Azure to Gemini.&lt;/strong&gt; This is the reverse federation. The managed identity's token is exchanged at a Google workload identity pool, which lets it act as the same service account the Cloud Run side uses. Google's client libraries do the exchange when they find this credential file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"external_account"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"audience"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"//iam.googleapis.com/projects/&amp;lt;NUMBER&amp;gt;/locations/global/workloadIdentityPools/azure-workloads/providers/&amp;lt;PROVIDER&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"subject_token_type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"urn:ietf:params:oauth:token-type:jwt"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"token_url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"https://sts.googleapis.com/v1/token"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"credential_source"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"file"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/var/run/fed/azure-token"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"service_account_impersonation_url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/litellm-runtime@&amp;lt;PROJECT&amp;gt;.iam.gserviceaccount.com:generateAccessToken"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A small sidecar keeps the Azure token in that file fresh. The pool accepts only that one managed identity as a subject.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;To the database.&lt;/strong&gt; Both gateways reach Cloud SQL through the Cloud SQL Auth Proxy, as a sidecar, with IAM database authentication:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;cloud-sql-proxy --auto-iam-authn --port=5432 &amp;lt;project&amp;gt;:&amp;lt;region&amp;gt;:&amp;lt;instance&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The database user is the service account. There is no password in the connection string.&lt;/p&gt;

&lt;h2&gt;
  
  
  When a gateway goes down
&lt;/h2&gt;

&lt;p&gt;Once every agent in a cloud depends on that cloud's gateway, the gateway is a single point of failure for all of them. So one thing has to be guaranteed: &lt;strong&gt;an agent keeps getting answers when the gateway of its own cloud is unavailable.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Two properties of this design make that possible:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The same token works on both gateways.&lt;/strong&gt; They share the audience, the role and the database. An agent needs nothing new to be served by the other cloud.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Either gateway reaches both model families.&lt;/strong&gt; A model provider being down and a gateway being down are separate failures, and neither one strands an agent.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There is also a rule worth stating: &lt;strong&gt;a refusal is not an outage.&lt;/strong&gt; A 401, a 403 or a 429 means the gateway is working and said no. Moving to the other cloud must never be a way around that answer.&lt;/p&gt;

&lt;p&gt;In our test, with the Azure gateway switched off, the Azure agent's next answer came through the Google Cloud gateway. Nobody touched anything, and the switch was barely noticeable.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we learned the hard way
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Let one side own the schema.&lt;/strong&gt; Two LiteLLM instances migrating the same database at startup is a race. One runs the migration. The other starts with &lt;code&gt;DISABLE_SCHEMA_UPDATE=true&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Custom auth failures come back as 401.&lt;/strong&gt; LiteLLM maps exceptions from the hook that way, even for what is logically a 403. Clients should read the message, not only the code.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pin the image version.&lt;/strong&gt; The custom auth hook imports LiteLLM internals. An unpinned upgrade can break sign-in for every agent at once.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Turn off message logging.&lt;/strong&gt; With &lt;code&gt;turn_off_message_logging: true&lt;/code&gt; the database keeps who called what and how much, and never the prompts.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What this design asks of you
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Per-minute limits are per cloud.&lt;/strong&gt; Rate counters live in Redis, and each cloud has its own. A limit of 60 requests a minute is 60 on each side.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The shared database lives in one cloud.&lt;/strong&gt; Both gateways depend on it. It is the first thing to look at when taking this to production.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The gateway still has an admin key.&lt;/strong&gt; LiteLLM needs a master key for its own administration. It stays in each cloud's secret manager, read by the gateway's identity. No agent ever sees it, and it is not part of any request between an agent and a model.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Wrapping up
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;One gateway per cloud, same configuration, same catalogue.&lt;/li&gt;
&lt;li&gt;Agents authenticate with the identity they already have.&lt;/li&gt;
&lt;li&gt;The gateway reaches both model providers and its database with workload identity.&lt;/li&gt;
&lt;li&gt;An agent can be served from either cloud with the same token.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Between an agent and a model there is no API key to rotate.&lt;/p&gt;

</description>
      <category>googlecloud</category>
      <category>azure</category>
      <category>ai</category>
      <category>security</category>
    </item>
    <item>
      <title>Google Agent Platform across clouds with SPIFFE: zero secrets between Google Cloud and Microsoft Entra</title>
      <dc:creator>Miguel Moreno</dc:creator>
      <pubDate>Sun, 15 Nov 2026 21:53:40 +0000</pubDate>
      <link>https://dev.to/gde/google-agent-platform-across-clouds-with-spiffe-zero-secrets-between-google-cloud-and-microsoft-1hjg</link>
      <guid>https://dev.to/gde/google-agent-platform-across-clouds-with-spiffe-zero-secrets-between-google-cloud-and-microsoft-1hjg</guid>
      <description>&lt;p&gt;&lt;em&gt;As of November 2026. All identifiers in this post are examples.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;We built a proof of concept with two AI agents. Agent A runs on Azure, in Microsoft Foundry. Agent B runs on Google Cloud, in Agent Runtime. They talk to each other over the A2A protocol, in both directions.&lt;/p&gt;

&lt;p&gt;Neither agent stores a password, a service account JSON key or a client secret. This post shows how that works, with the actual requests.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F3soj8u68zfgvlb1jej3g.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F3soj8u68zfgvlb1jej3g.png" alt="Figure 1: the architecture map" width="800" height="558"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The problem with the usual approach
&lt;/h2&gt;

&lt;p&gt;The quick way to connect agents across clouds looks like this:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The Google Cloud agent gets an Azure client secret, so it can ask Entra for a token.&lt;/li&gt;
&lt;li&gt;The Azure agent gets a Google service account key, so it can call Google APIs.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Now each cloud holds a long-lived credential for the other one. Someone has to rotate them. Each one can leak through a log, a repository or a container image. And with a hundred agents you have a few hundred secrets.&lt;/p&gt;

&lt;p&gt;We wanted a design where there is nothing to rotate, because nothing is stored.&lt;/p&gt;

&lt;h2&gt;
  
  
  The idea
&lt;/h2&gt;

&lt;p&gt;Two rules carry the whole design.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Each cloud proves who the workload is.&lt;/strong&gt; The agent never holds a credential. The platform it runs on vouches for it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One authority decides what the workload may do.&lt;/strong&gt; We chose Microsoft Entra. People sign in with Entra ID. Agents get identities in Entra Agent ID.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The piece that joins the two rules is &lt;strong&gt;workload identity federation&lt;/strong&gt;. Entra is told: "trust tokens signed by this Google issuer, for exactly this subject". If you have connected GitHub Actions to a cloud without a secret, this is the same pattern.&lt;/p&gt;

&lt;p&gt;What makes it work for agents is that Google gives every agent in Agent Runtime its own identity, expressed as a SPIFFE ID:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/
  projects/987654321098/locations/europe-west1/reasoningEngines/7300112233445566778
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That ID names one agent, in one project, in one region. Google signs tokens that carry it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Entra side: a blueprint and one federated credential
&lt;/h2&gt;

&lt;p&gt;In Entra Agent ID, an agent identity is created from a &lt;strong&gt;blueprint&lt;/strong&gt;. The blueprint is where credentials live. The agent identity itself cannot hold one, which is a useful property: nobody can attach a password to it later.&lt;/p&gt;

&lt;p&gt;On the blueprint we add a single federated identity credential:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"gcp-agent-spiffe"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"issuer"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"subject"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/europe-west1/reasoningEngines/7300112233445566778"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"audiences"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"api://AzureADTokenExchange"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Entra will accept a token as proof of identity only if the issuer, the subject and the audience match this record exactly, and the signature checks out against Google's public keys. There are no wildcards.&lt;/p&gt;

&lt;h2&gt;
  
  
  The exchange, hop by hop
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F63fjl7ire0murvqkxr60.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F63fjl7ire0murvqkxr60.png" alt="Figure 2: the token exchange" width="799" height="476"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  Hop 1: Google proves who the agent is
&lt;/h3&gt;

&lt;p&gt;Inside the agent, one call to the Google auth library:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;requests&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;oauth2&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;id_token&lt;/span&gt;

&lt;span class="n"&gt;google_jwt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;id_token&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;fetch_id_token&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"api://AzureADTokenExchange"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The agent asked for nothing secret. The runtime returns a JWT signed by Google, with the SPIFFE ID as its subject and the audience we requested.&lt;/p&gt;

&lt;h3&gt;
  
  
  Hop 2: the blueprint vouches for the agent
&lt;/h3&gt;

&lt;p&gt;The agent sends that JWT to Entra in place of a client secret:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="no"&gt;POST&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//login.microsoftonline.com/&amp;lt;TENANT_ID&amp;gt;/oauth2/v2.0/token&lt;/span&gt;

&lt;span class="na"&gt;grant_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;client_credentials&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;client_id&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="no"&gt;BLUEPRINT_APP_ID&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;client_assertion_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;urn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;ietf&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;oauth&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;assertion&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="k"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;jwt&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;bearer&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;client_assertion&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;google_jwt&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;scope&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//AzureADTokenExchange/.default&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;fmi_path&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="no"&gt;AGENT_IDENTITY_ID&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Entra finds the federated credential, validates the Google signature, and checks that the agent identity in &lt;code&gt;fmi_path&lt;/code&gt; belongs to this blueprint. It returns an intermediate token that is only good for the next hop.&lt;/p&gt;

&lt;h3&gt;
  
  
  Hop 3: the agent gets a token for one gateway
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="no"&gt;POST&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//login.microsoftonline.com/&amp;lt;TENANT_ID&amp;gt;/oauth2/v2.0/token&lt;/span&gt;

&lt;span class="na"&gt;grant_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;client_credentials&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;client_id&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="no"&gt;AGENT_IDENTITY_ID&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;client_assertion_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;urn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;ietf&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;oauth&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;assertion&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="k"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;jwt&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;bearer&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;client_assertion&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;intermediate&lt;/span&gt; &lt;span class="n"&gt;token&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="na"&gt;&amp;amp;scope&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//a2a-azure-gateway/.default&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is where authorization starts. The gateway application in Entra requires a role assignment. If the agent has no role there, Entra answers &lt;code&gt;AADSTS501051&lt;/code&gt; and issues nothing.&lt;/p&gt;

&lt;p&gt;If it has one, the access token looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"iss"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"https://login.microsoftonline.com/&amp;lt;TENANT_ID&amp;gt;/v2.0"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"aud"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;a2a-azure-gateway app id&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"azp"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;AGENT_IDENTITY_ID&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"roles"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"A2A.Invoke.agent-a"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;One audience, one role, valid for about an hour. The agent caches it and calls the gateway with it.&lt;/p&gt;

&lt;p&gt;Each token in the chain is narrower than the one before it:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Frkxdi3hb9l2pv8nwtf9b.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Frkxdi3hb9l2pv8nwtf9b.png" alt="Figure 3: what each token says" width="800" height="458"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;In Python this is about twenty lines of plain HTTP. We did not use MSAL, because it does not expose &lt;code&gt;fmi_path&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Authorization: three locks
&lt;/h2&gt;

&lt;p&gt;Authenticating is not enough to get in. A request has to pass three independent checks.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flxfzuafwhuqlvo6nebt2.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flxfzuafwhuqlvo6nebt2.png" alt="Figure 4: three locks" width="800" height="486"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Lock 1, Entra.&lt;/strong&gt; Each target agent has its own role on the gateway application, such as &lt;code&gt;A2A.Invoke.agent-a&lt;/code&gt;. The role is assigned only to the agents allowed to call that target. No role, no token.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Lock 2, the gateway.&lt;/strong&gt; API Management on Azure and Apigee on Google Cloud both validate the signature, the tenant, the audience and the expiry. Then they check that the token carries the role for the route being called, that the caller is on the allow-list for that route, and that it is not on the deny-list. The Apigee version of that check is small:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="kd"&gt;var&lt;/span&gt; &lt;span class="n"&gt;ok&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;roles&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cfg&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;role&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;                 &lt;span class="c1"&gt;// the role for THIS target&lt;/span&gt;
      &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cfg&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;allowed_callers&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;azp&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;        &lt;span class="c1"&gt;// the caller is expected here&lt;/span&gt;
      &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;isolated&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;                           &lt;span class="c1"&gt;// and nobody pulled the plug&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A role for agent X gives no access to agent Y behind the same gateway.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Lock 3, the backend.&lt;/strong&gt; The gateway drops the caller's token and calls the agent with its own identity. On Azure, only the gateway's managed identity may invoke the Foundry agent. On Google Cloud, only the Apigee service account may query the Agent Runtime engine. A call that goes around the gateway bounces, even with a valid Entra token.&lt;/p&gt;

&lt;h2&gt;
  
  
  The other direction
&lt;/h2&gt;

&lt;p&gt;Agent A calling Agent B is the same design with less visible plumbing. Foundry already holds a federated credential for its agents, so the code is one line:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="n"&gt;token&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;DefaultAzureCredential&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get_token&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"api://a2a-gcp-gateway/.default"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Apigee validates that Entra token with the same three checks, then calls Agent B with its own service account.&lt;/p&gt;

&lt;p&gt;Both directions end up symmetrical: an Entra token for the gateway of the other cloud, and a gateway that is the only door to its agent.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pulling the plug
&lt;/h2&gt;

&lt;p&gt;Entra access tokens live for about an hour, so removing a role does not stop an agent right away. For that there is a deny-list in both gateways. It holds the agent's ID as a caller and its name as a target, so an isolated agent can neither call nor be called.&lt;/p&gt;

&lt;p&gt;In our rehearsals the first refusal arrived in under a second. The worst case is bounded by a ten-second cache in the gateway.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we learned the hard way
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Never delete and recreate the Google agent.&lt;/strong&gt; Its engine ID is part of the SPIFFE ID. A new agent has a new subject, and the federated credential stops matching. Update it in place.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;AADSTS70021&lt;/code&gt; means the federated credential does not match.&lt;/strong&gt; Check the issuer, subject and audience character by character, including a trailing slash. Also wait a little: new credentials take time to propagate.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Authorize on &lt;code&gt;azp&lt;/code&gt; and &lt;code&gt;roles&lt;/code&gt;.&lt;/strong&gt; Tokens also carry a claim for the parent blueprint. Do not use it for access decisions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Quotas shape the design.&lt;/strong&gt; An application accepts at most 20 federated credentials, and a blueprint at most 250 agent identities. Subject patterns are not available for the Google issuer, so each agent needs its own exact credential.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Automate onboarding.&lt;/strong&gt; In our setup an agent is one entry in an inventory file. A pipeline creates the blueprint, the federated credential, the agent identity, the roles and the gateway allow-lists. With the runtime already deployed, that run took 22.8 seconds.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What this design asks of you
&lt;/h2&gt;

&lt;p&gt;No stored secret does not mean no responsibility. Two things take the place of the secrets.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The control planes become the credential.&lt;/strong&gt; Whoever can update the agent's code on Google Cloud can act as the agent. Whoever can edit the blueprint in Entra can add a federated credential of their own. Keep both permissions with very few identities, and alert on changes to federated credentials.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Use one blueprint per agent.&lt;/strong&gt; The federated credential lives on the blueprint, and a workload that authenticates as the blueprint can ask for a token for any agent identity under it. With one blueprint per agent, a compromised agent can only ever be itself.&lt;/p&gt;

&lt;h2&gt;
  
  
  Wrapping up
&lt;/h2&gt;

&lt;p&gt;The result is a small set of moving parts:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The platform proves the workload.&lt;/li&gt;
&lt;li&gt;One federated credential connects that proof to Entra.&lt;/li&gt;
&lt;li&gt;One role per target says who may call whom.&lt;/li&gt;
&lt;li&gt;The gateway enforces it, and the backend trusts only the gateway.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Nothing in that list has to be rotated.&lt;/p&gt;

</description>
      <category>googlecloud</category>
      <category>azure</category>
      <category>security</category>
      <category>ai</category>
    </item>
    <item>
      <title>MCP, A2A, UCP, AP2... Confused? A Simple Map of AI Agent Protocols (November 2026)</title>
      <dc:creator>Karthigayan Devan</dc:creator>
      <pubDate>Sun, 15 Nov 2026 20:09:35 +0000</pubDate>
      <link>https://dev.to/gde/mcp-a2a-ucp-ap2-confused-a-simple-map-of-ai-agent-protocols-november-2026-3ph</link>
      <guid>https://dev.to/gde/mcp-a2a-ucp-ap2-confused-a-simple-map-of-ai-agent-protocols-november-2026-3ph</guid>
      <description>&lt;p&gt;MCP. A2A. AG-UI. A2UI. UCP. AP2. ACP. x402. And as of this week, Poppy.&lt;/p&gt;

&lt;p&gt;If your head spins every time a new agent protocol drops, you're not alone. Even the acronyms collide: "ACP" now means at least two different things depending on who you ask.&lt;/p&gt;

&lt;p&gt;Here's the good news. These protocols are &lt;strong&gt;not competing with each other&lt;/strong&gt;. They are layers, like the network stack. Once you see the layers, the whole thing clicks.&lt;/p&gt;

&lt;p&gt;This guide gives you the map, what's new as of November 2026, a real end-to-end example, and an honest answer to "which ones do I actually need?"&lt;/p&gt;

&lt;h2&gt;
  
  
  TL;DR: one question picks the protocol
&lt;/h2&gt;

&lt;p&gt;Ask yourself: &lt;strong&gt;what is my agent talking to?&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;My agent is talking to...&lt;/th&gt;
&lt;th&gt;Use this&lt;/th&gt;
&lt;th&gt;In one line&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Tools and data&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;MCP&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Plug the agent into APIs, databases and files&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Another agent&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;A2A&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Hand off work to an agent someone else built&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A user's screen&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;AG-UI&lt;/strong&gt; / &lt;strong&gt;A2UI&lt;/strong&gt;
&lt;/td&gt;
&lt;td&gt;Show the user what the agent is doing, live&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A store or business&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;UCP&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Search, cart, checkout and orders in one standard&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A payment&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;AP2&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Prove the user really approved the purchase&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Keep this table handy. Everything below just adds detail.&lt;/p&gt;

&lt;h2&gt;
  
  
  The stack at a glance
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;+---------------------------------------------------+
|  USER          AG-UI (live events) / A2UI (UI)     |
+---------------------------------------------------+
|  PAYMENTS      AP2 (signed mandates), x402         |
+---------------------------------------------------+
|  COMMERCE      UCP (catalog, cart, checkout)       |
+---------------------------------------------------+
|  AGENTS        A2A (agent to agent)                |
+---------------------------------------------------+
|  TOOLS         MCP (agent to tools and data)       |
+---------------------------------------------------+
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;One agent can use all five layers in a single task. We'll walk through exactly that later.&lt;/p&gt;

&lt;h2&gt;
  
  
  Layer 1: MCP, the agent's hands
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Model Context Protocol (MCP)&lt;/strong&gt; connects an agent to tools and data: your database, GitHub, Slack, a weather API, anything. Build an MCP server once, and any MCP-compatible agent can use it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's new:&lt;/strong&gt; the current spec is &lt;strong&gt;2026-07-28&lt;/strong&gt;, and it's the biggest change yet. MCP moved from a stateful, session-based protocol to a &lt;strong&gt;stateless request and response&lt;/strong&gt; protocol.&lt;/p&gt;

&lt;p&gt;What that means in practice:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;No more sessions.&lt;/strong&gt; The session handshake is gone, so any request can go to any server instance. Great news for anyone running MCP servers behind a load balancer.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A new discovery call.&lt;/strong&gt; Clients can ask a server what it supports before sending other requests.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Some features are deprecated.&lt;/strong&gt; Roots, Sampling and Logging are now deprecated, and Tasks moved out of the core into an official extension.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Old transport is on the way out.&lt;/strong&gt; If your server still uses HTTP+SSE, the spec tells you to migrate to Streamable HTTP.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you built an MCP server last year, read the changelog before your next upgrade.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Use it when:&lt;/strong&gt; your agent needs to read or do something in another system.&lt;/p&gt;

&lt;h2&gt;
  
  
  Layer 2: A2A, agents talking to agents
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Agent2Agent (A2A)&lt;/strong&gt; lets agents built by different teams, vendors or companies work together. Each agent publishes an "Agent Card" describing what it can do, and other agents discover it and delegate tasks.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;MCP vs A2A in one line:&lt;/strong&gt; MCP is for tools you control. A2A is for agents you don't own, which have their own brains and make their own decisions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's new:&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;v1.0 shipped on March 12, 2026&lt;/strong&gt;, the first stable version, with JSON-RPC, gRPC and HTTP+JSON bindings. The v1.0.1 patch followed in May.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;v1.1 is in the works.&lt;/strong&gt; A release candidate tagged in late October adds two-way streaming while a task runs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It moved in with MCP.&lt;/strong&gt; A2A joined MCP in the Agentic AI Foundation (under the Linux Foundation) in August 2026.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Big vendors are on board.&lt;/strong&gt; Microsoft Copilot Studio now lets you expose an agent as a remote MCP server or an A2A agent.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Use it when:&lt;/strong&gt; you need a specialist agent from another team or company, like a travel policy agent, a fraud check agent or a partner's booking agent.&lt;/p&gt;

&lt;h2&gt;
  
  
  Layer 3: AG-UI and A2UI, the agent's face
&lt;/h2&gt;

&lt;p&gt;Agents that work silently in the background feel broken to users. These two protocols fix that, and they solve different halves of the problem:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;AG-UI (Agent-User Interaction Protocol)&lt;/strong&gt; is the live wire. It streams events from the agent to your app in real time: "searching hotels...", "found 12 options...", "waiting for your approval." It's event-based and runs over HTTP and Server-Sent Events.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A2UI&lt;/strong&gt; is about &lt;strong&gt;what&lt;/strong&gt; to show. The agent describes UI (cards, forms, approval buttons) in a declarative format, and your app renders it with its own components. No arbitrary code from the agent runs in your app.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Simple way to remember it: &lt;strong&gt;A2UI describes the screen, AG-UI delivers it live.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;There are a few more in this layer worth knowing about:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;MCP Apps&lt;/strong&gt; is MCP's own extension for showing UI from tools.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Agent Client Protocol&lt;/strong&gt; connects coding agents to code editors. (Yes, this is one of the two "ACPs.")&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Use it when:&lt;/strong&gt; a human watches the agent work or needs to approve something.&lt;/p&gt;

&lt;h2&gt;
  
  
  Layer 4 and 5: agentic commerce (the most exciting part)
&lt;/h2&gt;

&lt;p&gt;This is where agents stop just answering questions and start &lt;strong&gt;spending money&lt;/strong&gt;. It's also where trust matters most, so two protocols split the job.&lt;/p&gt;

&lt;h3&gt;
  
  
  UCP: the shopping standard
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Universal Commerce Protocol (UCP)&lt;/strong&gt; gives agents one standard way to work with any business, from discovery to checkout and after.&lt;/p&gt;

&lt;p&gt;Its core capabilities:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Catalog:&lt;/strong&gt; search and browse products&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cart:&lt;/strong&gt; build multi-item carts&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Identity linking:&lt;/strong&gt; connect the user's account using OAuth 2.0, without sharing passwords&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Checkout:&lt;/strong&gt; taxes, shipping, discounts, the whole messy reality&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Order:&lt;/strong&gt; confirmation, tracking and returns through webhooks&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;What's new:&lt;/strong&gt; UCP has grown beyond shopping. The spec site now shows three tracks: &lt;strong&gt;shopping, lodging and food&lt;/strong&gt;. Hotel booking and food ordering specs are still drafts, so expect changes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Who's behind it:&lt;/strong&gt; the co-developer list reads like a who's who of commerce: Google, Shopify, Etsy, Wayfair, Target, Walmart, Amazon, Microsoft, Meta, Salesforce and Stripe, plus travel players like Booking.com, Expedia Group, Hilton and Marriott, and food players like DoorDash and Uber Eats.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The detail businesses care about:&lt;/strong&gt; the business stays the Merchant of Record and keeps the customer relationship. The agent doesn't take over the store.&lt;/p&gt;

&lt;h3&gt;
  
  
  AP2: proof that you said yes
&lt;/h3&gt;

&lt;p&gt;Here's the problem AP2 solves. Every payment system today assumes a human clicked "buy." When an AI agent clicks it, three hard questions appear:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Authorization:&lt;/strong&gt; did the user really give the agent permission for this purchase?&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Authenticity:&lt;/strong&gt; does the request match what the user actually wanted, or did the agent hallucinate?&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Accountability:&lt;/strong&gt; if something goes wrong, who's responsible?&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;Agent Payments Protocol (AP2)&lt;/strong&gt; answers these with &lt;strong&gt;mandates&lt;/strong&gt;: tamper-evident, cryptographically signed records of what the user approved. There are two kinds:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Checkout Mandate:&lt;/strong&gt; the items and purchase details agreed with the merchant. Shared with the merchant.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Payment Mandate:&lt;/strong&gt; the approval to charge a specific payment method. Shared with the payment network and processors, not with everyone.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each comes in two stages:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Open:&lt;/strong&gt; your rules up front, like "any hotel under $250 a night, using my Visa." This lets the agent act on its own.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Closed:&lt;/strong&gt; your approval for one specific, final purchase.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;AP2 supports both &lt;strong&gt;human present&lt;/strong&gt; (you approve in the moment) and &lt;strong&gt;human not present&lt;/strong&gt; (the agent buys within your limits while you sleep).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What's new:&lt;/strong&gt; AP2 v0.2 was released and &lt;strong&gt;donated to the FIDO Alliance&lt;/strong&gt;, the group behind passkeys. Standardization continues in FIDO's working groups.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Roadmap worth watching:&lt;/strong&gt; AP2 starts with cards. The roadmap adds e-wallets, &lt;strong&gt;push payments like UPI (India) and PIX (Brazil)&lt;/strong&gt;, and digital currencies. That matters for huge markets where cards aren't the main way people pay.&lt;/p&gt;

&lt;h3&gt;
  
  
  How UCP and AP2 fit together
&lt;/h3&gt;

&lt;p&gt;UCP runs the shopping flow. AP2 secures the payment inside it. UCP has AP2 support built in, along with MCP and A2A support, so these aren't rival standards. They're designed as a set.&lt;/p&gt;

&lt;h3&gt;
  
  
  Other names you'll hear
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;ACP (Agentic Commerce Protocol):&lt;/strong&gt; OpenAI and Stripe's commerce standard. Interestingly, Stripe also co-develops UCP. Watch this space.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;x402:&lt;/strong&gt; agent payments built on the old HTTP "402 Payment Required" status code, popular for crypto and pay-per-use APIs. The official AP2 samples include x402 flows.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Putting it all together: "Book me a hotel in Chicago"
&lt;/h2&gt;

&lt;p&gt;Let's see every layer in one real task. You tell your assistant:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;"Book me a hotel near the conference in Chicago, under $250 a night, for the three nights I'm there."&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Here's what happens under the hood:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;MCP:&lt;/strong&gt; the agent reads your calendar through an MCP server and finds your conference dates.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A2A:&lt;/strong&gt; it asks your company's travel policy agent (built by another team) whether you need approval for this trip.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;AP2 (open mandate):&lt;/strong&gt; you've already signed an open mandate: hotels only, under $250 a night, company card.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;UCP:&lt;/strong&gt; the agent searches hotel catalogs, builds the booking, and runs checkout with the hotel, which stays the Merchant of Record.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A2UI + AG-UI:&lt;/strong&gt; your screen shows three hotel cards live as the search runs, with a "Book this one" button.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;AP2 (closed mandate):&lt;/strong&gt; you tap the button, and a signed, closed mandate locks in that exact booking and price.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;UCP (order):&lt;/strong&gt; the confirmation and any later changes flow back through order webhooks.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Seven steps, five protocols, zero custom integrations. That's the whole promise of this stack.&lt;/p&gt;

&lt;h2&gt;
  
  
  Brand new this week: Poppy
&lt;/h2&gt;

&lt;p&gt;On &lt;strong&gt;November 13, 2026&lt;/strong&gt;, Sierra released &lt;strong&gt;Personal Agent Protocol 1.0&lt;/strong&gt;, nicknamed &lt;strong&gt;Poppy&lt;/strong&gt;. It defines how &lt;strong&gt;your personal AI agent&lt;/strong&gt; connects to a business, through its website, its APIs or the business's own agent. It came out of a draft shared in October and developed with Meta.&lt;/p&gt;

&lt;p&gt;It's two days old, so treat it as one to watch, not one to build on yet. But it points at where things are going: your agent talking to their agent.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's still missing (the honest part)
&lt;/h2&gt;

&lt;p&gt;The stack is real, but it isn't finished. Before you bet a product on it, know the gaps:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;No shared memory standard.&lt;/strong&gt; No foundation-backed protocol exists for agents to share one memory. Most teams expose memory through an MCP server and hope for the best.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No privacy signal.&lt;/strong&gt; A recent academic audit found that neither MCP nor A2A carries a privacy field. If a user opts out of ad data sharing, that choice can't travel with a delegated task.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Identity is still open.&lt;/strong&gt; "Which agent is this, and who does it work for?" doesn't have one standard answer yet.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Commerce and payments are early.&lt;/strong&gt; Lodging and food specs in UCP are drafts, and AP2 is at v0.2. Build pilots, not your whole checkout.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There's movement here too. The IETF chartered an &lt;strong&gt;Agent Communication Protocols&lt;/strong&gt; working group in October 2026, aiming for a shared base protocol that MCP and A2A could both carry.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which ones do you actually need?
&lt;/h2&gt;

&lt;p&gt;Start small. Add layers only when you hit a real need.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Start with MCP.&lt;/strong&gt; Almost every agent needs tools. This is the one to learn first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add AG-UI or A2UI&lt;/strong&gt; when a human watches the agent or needs to approve things.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add A2A&lt;/strong&gt; only when you work with agents you don't own. If all your agents live in one codebase, you probably don't need it yet.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add UCP and AP2&lt;/strong&gt; if your agent shops, books or pays. Start with a pilot, and follow the specs closely, because they're moving fast.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;Rule of thumb: MCP by default, A2A at the boundary, UCP and AP2 at the checkout.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  For Google Cloud developers
&lt;/h2&gt;

&lt;p&gt;Several of these protocols started at Google: A2A, UCP (with Shopify) and AP2, plus A2UI. Google's &lt;strong&gt;Agent Development Kit (ADK)&lt;/strong&gt; works with MCP for tools and A2A for agent collaboration, and AP2's official guide pairs ADK, MCP, A2A and AP2 as one stack. If you already build on ADK, you're closer to this full stack than you think.&lt;/p&gt;

&lt;p&gt;The protocols themselves are open and vendor-neutral, so nothing here locks you into one cloud.&lt;/p&gt;

&lt;h2&gt;
  
  
  Caveats
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Everything here is as of November 15, 2026.&lt;/strong&gt; These specs change monthly. Check the official sites before you build.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Some items are drafts or previews:&lt;/strong&gt; A2A v1.1, UCP lodging and food, AP2 v0.2, and Poppy.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Adoption numbers vary by source.&lt;/strong&gt; I've left out partner counts and download stats that I couldn't confirm from official pages.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://modelcontextprotocol.io/specification/2026-07-28/changelog" rel="noopener noreferrer"&gt;Model Context Protocol: 2026-07-28 changelog&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://a2a-protocol.org/latest/" rel="noopener noreferrer"&gt;Agent2Agent (A2A) Protocol&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ucp.dev/" rel="noopener noreferrer"&gt;Universal Commerce Protocol (UCP)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ucp.dev/documentation/ucp-and-ap2/" rel="noopener noreferrer"&gt;UCP and AP2 integration guide&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ap2-protocol.org/" rel="noopener noreferrer"&gt;Agent Payments Protocol (AP2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://blog.google/products-and-platforms/platforms/google-pay/agent-payments-protocol-fido-alliance/" rel="noopener noreferrer"&gt;AP2 v0.2 and FIDO Alliance donation, Google blog&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/ag-ui-protocol/ag-ui" rel="noopener noreferrer"&gt;AG-UI on GitHub&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://a2ui.org/roadmap/" rel="noopener noreferrer"&gt;A2UI roadmap&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.microsoft.com/en-us/microsoft-copilot-studio/whats-new" rel="noopener noreferrer"&gt;Microsoft Copilot Studio: what's new&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




</description>
      <category>ai</category>
      <category>agents</category>
      <category>mcp</category>
      <category>googlecloud</category>
    </item>
    <item>
      <title>Hydrogen, Carbon or Argon? A Cost-First Guide to Gemini 4 for Every Team</title>
      <dc:creator>Karthigayan Devan</dc:creator>
      <pubDate>Sun, 15 Nov 2026 19:42:18 +0000</pubDate>
      <link>https://dev.to/gde/hydrogen-carbon-or-argon-a-cost-first-guide-to-gemini-4-for-every-team-205b</link>
      <guid>https://dev.to/gde/hydrogen-carbon-or-argon-a-cost-first-guide-to-gemini-4-for-every-team-205b</guid>
      <description>&lt;p&gt;In the last few weeks, Google shipped three new Gemini 4 models: Argon (GA October 13, 2026), Carbon (GA November 10), and Hydrogen (GA November 12). Then came cyber versions of two of them, plus a world model called Genie 4. The names come from the periodic table, so they tell you nothing about which one is bigger, faster, or cheaper. Hydrogen is the lightest element, but it is not a "lite" model in the old sense.&lt;/p&gt;

&lt;p&gt;Cost sits at the center of this guide, because every role touches the bill. You'll find a section for each team: developers, SREs and platform engineers, security and compliance reviewers, engineering leaders and architects, and of course FinOps. Each one ends with your own cost lever: the one thing in your hands that moves the bill.&lt;/p&gt;

&lt;p&gt;All facts come from the Gemini Enterprise Agent Platform model pages on Google Cloud (last updated November 13, 2026), the Agent Platform pricing page, and Google's launch posts.&lt;/p&gt;

&lt;h2&gt;
  
  
  Find your section
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;If you are...&lt;/th&gt;
&lt;th&gt;Your big question&lt;/th&gt;
&lt;th&gt;Your cost lever&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;FinOps or finance&lt;/td&gt;
&lt;td&gt;What will this cost us, and when does it change?&lt;/td&gt;
&lt;td&gt;Routing policy and request labels&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Developer&lt;/td&gt;
&lt;td&gt;What breaks when I switch models?&lt;/td&gt;
&lt;td&gt;Thinking level on every call&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;SRE or platform engineer&lt;/td&gt;
&lt;td&gt;Where does it run, and how long can a call take?&lt;/td&gt;
&lt;td&gt;Timeouts and region choice&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Security or compliance&lt;/td&gt;
&lt;td&gt;What terms and access rules apply?&lt;/td&gt;
&lt;td&gt;Approval path for Carbon and cyber models&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Engineering leader or architect&lt;/td&gt;
&lt;td&gt;Which model should be our standard?&lt;/td&gt;
&lt;td&gt;Default model and escalation rules&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  The 30-second cheat sheet
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Gemini 4 Hydrogen (&lt;code&gt;gemini-4-hydrogen&lt;/code&gt;):&lt;/strong&gt; the fast, cheaper workhorse for everyday coding and agent work. Google calls it the upgrade path from Gemini 3.8 Flash. Think of it as your default.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Gemini 4 Carbon (&lt;code&gt;gemini-4-carbon&lt;/code&gt;):&lt;/strong&gt; Google's strongest model. It thinks the longest and spends the most thinking tokens. Use it for planning, deep debugging and hard root-cause work.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Gemini 4 Argon (&lt;code&gt;gemini-4-argon&lt;/code&gt;):&lt;/strong&gt; the first frontier Gemini 4 model. Same per-token price as Carbon, but it uses fewer thinking tokens. It fits a narrow middle ground: jobs where Hydrogen falls short and Carbon is too slow.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cyber variants (allowlist only):&lt;/strong&gt; special builds of Argon and Carbon for defensive security work. Most teams will never touch these.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Genie 4:&lt;/strong&gt; not a text or code model at all. It's a world model in research preview. Skip it for app building.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What are the cyber variants?
&lt;/h2&gt;

&lt;p&gt;The cyber models are versions of Argon and Carbon tuned for defensive security work: finding vulnerabilities, reverse engineering, verifying exploits and writing patches. You can't just turn them on. Access is allowlist only, through your Google team or the Fairwind Program.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Gemini 4 Argon Cyber Permissive&lt;/th&gt;
&lt;th&gt;Gemini 4 Carbon for cyber&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Model ID&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gemini-4-argon-cyber-permissive&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gemini-4-carbon-cyber-permissive&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Based on&lt;/td&gt;
&lt;td&gt;Gemini 4 Argon&lt;/td&gt;
&lt;td&gt;Gemini 4 Carbon&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Default thinking level&lt;/td&gt;
&lt;td&gt;HIGH (normal Argon is MEDIUM)&lt;/td&gt;
&lt;td&gt;HIGH (normal Carbon is MEDIUM)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Computer use&lt;/td&gt;
&lt;td&gt;Not supported&lt;/td&gt;
&lt;td&gt;Not supported&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Regions&lt;/td&gt;
&lt;td&gt;global, us, eu&lt;/td&gt;
&lt;td&gt;global, us&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Price, global, per 1M tokens in/out&lt;/td&gt;
&lt;td&gt;$4 / $20 (no intro promo)&lt;/td&gt;
&lt;td&gt;$4 / $20 (no intro promo)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Terms&lt;/td&gt;
&lt;td&gt;Section 31 of Service Specific Terms&lt;/td&gt;
&lt;td&gt;Section 31 of Service Specific Terms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Three things to watch:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The naming is not consistent.&lt;/strong&gt; The Carbon version is called "Carbon for cyber" in the docs, but its model ID still ends in "cyber-permissive". Use the model ID, not the display name, in your code and docs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Access does not carry over.&lt;/strong&gt; If you already have Argon Cyber Permissive or Gemini 3.8 Flash Cyber, you still need to apply again for Carbon for cyber.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Higher default thinking means higher token spend.&lt;/strong&gt; Both cyber models default to HIGH, so expect more output tokens per call than the base models.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Side by side
&lt;/h2&gt;

&lt;p&gt;On Google Cloud the three base models look almost the same on paper. The real differences are thinking behavior, price, regions, file types and who can get access.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Hydrogen&lt;/th&gt;
&lt;th&gt;Argon&lt;/th&gt;
&lt;th&gt;Carbon&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Model ID&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gemini-4-hydrogen&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gemini-4-argon&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;gemini-4-carbon&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GA date&lt;/td&gt;
&lt;td&gt;Nov 12, 2026&lt;/td&gt;
&lt;td&gt;Oct 13, 2026&lt;/td&gt;
&lt;td&gt;Nov 10, 2026&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Best for&lt;/td&gt;
&lt;td&gt;Everyday coding, agents, execution&lt;/td&gt;
&lt;td&gt;Long tasks, fewer thinking tokens than Carbon&lt;/td&gt;
&lt;td&gt;Deepest reasoning, planning&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Thinking levels&lt;/td&gt;
&lt;td&gt;LOW, MEDIUM, HIGH (default), XHIGH&lt;/td&gt;
&lt;td&gt;LOW, MEDIUM (default), HIGH&lt;/td&gt;
&lt;td&gt;LOW, MEDIUM (default), HIGH&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Output per segment&lt;/td&gt;
&lt;td&gt;65,536 (streaming or not)&lt;/td&gt;
&lt;td&gt;65,536 streaming, 32,768 non-streaming&lt;/td&gt;
&lt;td&gt;65,536 streaming, 32,768 non-streaming&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Office and OpenDocument files&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No (PDF and text only)&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Regions&lt;/td&gt;
&lt;td&gt;global, us, eu&lt;/td&gt;
&lt;td&gt;global, us, eu, europe-west2, asia-southeast1&lt;/td&gt;
&lt;td&gt;global, us, eu&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access&lt;/td&gt;
&lt;td&gt;Public&lt;/td&gt;
&lt;td&gt;Public&lt;/td&gt;
&lt;td&gt;Verified enterprise customers, select regions&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Knowledge cutoff&lt;/td&gt;
&lt;td&gt;March 2026&lt;/td&gt;
&lt;td&gt;Not listed&lt;/td&gt;
&lt;td&gt;March 2026&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Google Cloud price, global, per 1M tokens in/out&lt;/td&gt;
&lt;td&gt;$1.50 / $7.50&lt;/td&gt;
&lt;td&gt;$2 / $10, then $4 / $20 from Dec 1&lt;/td&gt;
&lt;td&gt;$2 / $10, then $4 / $20 from Dec 1&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Prices are Standard PayGo on the global endpoint. Regional (non-global) endpoints cost 10% more on every model.&lt;/p&gt;

&lt;p&gt;What all three share: a 1,048,576-token limit that covers input and output together, long decodes up to that limit, implicit caching only (4,096-token minimum), fixed sampling settings, no Live API, no tuning and no RAG Engine. All three support grounding, function calling, code execution, URL context, computer use, batch, Provisioned Throughput, Standard PayGo and Priority PayGo.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's new this month
&lt;/h2&gt;

&lt;p&gt;The biggest update: Google says Hydrogen at its default HIGH setting slightly outscores Argon on the Artificial Analysis Intelligence Index (51 vs 50, and 54 at XHIGH), at a lower price. If that holds on your workloads, Argon's role gets even smaller.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Date&lt;/th&gt;
&lt;th&gt;What happened&lt;/th&gt;
&lt;th&gt;Why it matters&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Nov 13, 2026&lt;/td&gt;
&lt;td&gt;Google Cloud starts billing long completions (past 32K tokens) even when they fail on a timeout&lt;/td&gt;
&lt;td&gt;Timeouts now cost money, not just time&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nov 12, 2026&lt;/td&gt;
&lt;td&gt;Hydrogen GA, replacing Gemini 3.8 Flash; now powers the Gemini app and AI Mode in Search&lt;/td&gt;
&lt;td&gt;Google says it's 2.5x faster than 3.8 Flash at its default HIGH level&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nov 12, 2026&lt;/td&gt;
&lt;td&gt;Orchestrator in Google Antigravity: Carbon plans, Hydrogen executes, in one session&lt;/td&gt;
&lt;td&gt;Google reports near-Carbon success with 24% less quota and 19% faster runs on Terminal-Bench 4.0&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Nov 10, 2026&lt;/td&gt;
&lt;td&gt;Carbon GA, plus a /swarm preview in Antigravity that turns one prompt into a team of agents&lt;/td&gt;
&lt;td&gt;Parallel agents multiply token use, so watch spend&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Oct 13, 2026&lt;/td&gt;
&lt;td&gt;Argon GA&lt;/td&gt;
&lt;td&gt;First Gemini 4 frontier model&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Dates coming up:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Date&lt;/th&gt;
&lt;th&gt;What changes&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Nov 30, 2026&lt;/td&gt;
&lt;td&gt;Intro credits for Argon and Carbon end&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Dec 1, 2026&lt;/td&gt;
&lt;td&gt;Argon and Carbon go to $4 / $20 per 1M tokens (global)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Jan 1, 2027&lt;/td&gt;
&lt;td&gt;Gemini 3.8 Flash doubles to $1.50 / $7.50 on the Gemini API, the same as Hydrogen&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Jan 12, 2027&lt;/td&gt;
&lt;td&gt;Hydrogen gets cache control with TTL; cache writes at $1.875 per 1M tokens&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Oct 13, 2027 or later&lt;/td&gt;
&lt;td&gt;Argon's listed retirement on Google Cloud&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  If you own the bill (FinOps)
&lt;/h2&gt;

&lt;p&gt;The headline: from December 1, 2026, Argon and Carbon cost about 2.67 times more per token than Hydrogen. Model choice is now one of the biggest levers on your AI bill.&lt;/p&gt;

&lt;p&gt;Here is a simple example. One request with 20,000 input tokens and 3,000 output tokens, at Google Cloud Standard PayGo prices, per 10,000 requests:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;Global endpoint&lt;/th&gt;
&lt;th&gt;Non-global endpoint&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Hydrogen&lt;/td&gt;
&lt;td&gt;about $525&lt;/td&gt;
&lt;td&gt;about $578&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Argon or Carbon, until Nov 30&lt;/td&gt;
&lt;td&gt;about $700&lt;/td&gt;
&lt;td&gt;about $770&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Argon or Carbon, from Dec 1&lt;/td&gt;
&lt;td&gt;about $1,400&lt;/td&gt;
&lt;td&gt;about $1,540&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;This keeps token counts equal, which real traffic won't. Carbon spends more thinking tokens than Argon, so the real gap is often bigger.&lt;/p&gt;

&lt;p&gt;Three details hide in the footnotes of the Google Cloud pricing page:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The intro price is a credit, not a lower rate.&lt;/strong&gt; Argon and Carbon get 50% credits back on net spend through November 30, 2026. Your invoice may show full price with a credit line, so warn your finance team.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cyber models get no promo.&lt;/strong&gt; Argon Cyber Permissive and Carbon Cyber Permissive cost $4 / $20 per 1M tokens from day one.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Failed long calls still bill.&lt;/strong&gt; Since November 13, 2026, any completion past 32K tokens is charged for the tokens that can be retrieved, even when it fails from a client or server timeout.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Where the money hides:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Thinking tokens are billed as output.&lt;/strong&gt; Output costs 5 times input. A model that thinks more costs more, even on the same prompt.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hydrogen's HIGH default.&lt;/strong&gt; Teams moving from 3.8 Flash (which defaulted to MEDIUM) may see a jump. Start at MEDIUM and compare on your own test set.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Caching changes.&lt;/strong&gt; All three use implicit caching only. Put stable content (system instructions, reference docs) at the start of the prompt so cache hits happen. From January 12, 2027, Hydrogen gets cache control with TTL, with cache writes at $1.875 per 1M tokens on global (1.25 times input). Cache reads are cheap on every model: 5% of the input price, or $0.075 per 1M tokens on Hydrogen.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use batch for non-urgent work.&lt;/strong&gt; It has its own lower rates on the Batch tab of the pricing page.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Re-test before December 1.&lt;/strong&gt; If you picked Argon in October, check whether Hydrogen now does the job.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tag your requests.&lt;/strong&gt; Use request labels by model and use case so you can see which team or feature drives Carbon spend.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Your cost lever:&lt;/strong&gt; the routing policy and the labels. Default to Hydrogen, track Carbon spend by team, and re-test anything on Argon or Carbon before December 1.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you build apps (developers)
&lt;/h2&gt;

&lt;p&gt;Switching to Gemini 4 is more than changing the model string. A few old habits now break or silently stop working.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;No more temperature tuning.&lt;/strong&gt; &lt;code&gt;temperature&lt;/code&gt;, &lt;code&gt;top_p&lt;/code&gt; and &lt;code&gt;top_k&lt;/code&gt; are ignored. They are fixed at 1.0, 0.95 and 64. If your prompts relied on low temperature for steady output, test again.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;thinking_budget&lt;/code&gt; and MINIMAL are gone.&lt;/strong&gt; Sending &lt;code&gt;thinking_budget&lt;/code&gt;, or &lt;code&gt;thinking_level&lt;/code&gt; set to MINIMAL, returns an HTTP 400 error. Use thinking levels instead.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hydrogen thinks harder by default.&lt;/strong&gt; Its default is HIGH, while Argon and Carbon default to MEDIUM. Set the level on purpose. Don't just accept the default.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;XHIGH is Hydrogen only.&lt;/strong&gt; Save it for hard multi-step problems. On simple jobs like extraction it can overthink.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Long answers need long decodes.&lt;/strong&gt; One segment stops at 65,536 output tokens (32,768 for Argon and Carbon when not streaming). The Gen AI SDK and Agent Studio continue automatically. A custom loop needs &lt;code&gt;continuation_token&lt;/code&gt;, which only works on the v1beta1 API for now.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Office files work on Hydrogen and Carbon.&lt;/strong&gt; You can send .docx, .pptx, .xlsx and OpenDocument files directly, no conversion. Hydrogen even accepts them inside function responses. Argon still takes only PDF and plain text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Planner plus executor works well.&lt;/strong&gt; Google shows Carbon doing the planning turns and Hydrogen doing the execution turns in one session, linked with &lt;code&gt;previous_interaction_id&lt;/code&gt;. This is a natural fit for multi-agent apps.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Your cost lever:&lt;/strong&gt; set the thinking level on every call, and log thinking tokens per feature. Don't let Hydrogen's HIGH default decide your bill.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you keep it running (SRE and platform)
&lt;/h2&gt;

&lt;p&gt;For reliability, the big questions are where the model runs, how you pay for capacity and how long a call can take.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Regions decide a lot.&lt;/strong&gt; Argon is the only one with single regions (europe-west2 and asia-southeast1). Hydrogen and Carbon run only on global, us and eu. If your data must stay in London or Singapore, Argon is your only Gemini 4 option today.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Carbon is gated.&lt;/strong&gt; Google limits it to verified enterprise customers in select regions, to protect capacity. Don't build a production path on Carbon until your project is approved.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No fixed quota.&lt;/strong&gt; All three run on Standard PayGo with usage tiers, Priority PayGo, Provisioned Throughput or batch. Plan capacity with Provisioned Throughput for steady, critical traffic.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Expect long calls.&lt;/strong&gt; HIGH and XHIGH thinking plus long decodes can run for minutes. Raise client and gateway timeouts, and stream where you can. Timeouts now cost money too: since November 13, 2026, a completion that runs past 32K tokens is billed for what can be retrieved, even if the call fails on a timeout.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Big inputs are allowed.&lt;/strong&gt; Up to 500 MiB compressed on GenerateContent, 3,000 images or documents per prompt, about 45 minutes of video with audio, and around 8.4 hours of audio. Watch your request size limits upstream.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Plan for retirement.&lt;/strong&gt; Argon's listed retirement is October 13, 2027 or later. Put the model ID in config, not in code, so you can swap it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Your cost lever:&lt;/strong&gt; timeouts and region choice. A timed-out call past 32K tokens still bills, and non-global endpoints cost 10% more. Use global unless data residency says otherwise, and keep Provisioned Throughput for steady traffic you can predict.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you approve it (security and compliance)
&lt;/h2&gt;

&lt;p&gt;For security teams, Carbon and the cyber models come with extra terms. Read them before you sign off.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Carbon is a "Google Frontier Model".&lt;/strong&gt; It falls under Section 34 of the Service Specific Terms, which includes abuse monitoring. Your legal team should review what that means for your prompts and data.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cyber models are "Frontier Cyber Models".&lt;/strong&gt; They fall under Section 31 and need allowlist approval. Plan for an approval step in your project timeline.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Data residency depends on region.&lt;/strong&gt; All three list security controls for data residency, CMEK, VPC-SC and Access Transparency on the model page. Confirm which ones apply to your region and use case before go-live.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Free tier prompts may be used by Google.&lt;/strong&gt; On the Gemini API (not Google Cloud), free-tier Hydrogen prompts may be used to improve Google's products. Paid tier is not. For company data, use Google Cloud or a paid tier.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Computer use is off for cyber models.&lt;/strong&gt; The base Argon, Carbon and Hydrogen support it, but the cyber versions do not.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Your cost lever:&lt;/strong&gt; the approval path. Approve the cheapest model that meets policy. Make Carbon and the cyber models (both $4 / $20 per 1M tokens with no promo for cyber) a named exception, not a default.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you lead the team (engineering leaders and architects)
&lt;/h2&gt;

&lt;p&gt;Your job is to set one simple standard so every team doesn't pick its own model.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Pick a default and an escalation rule.&lt;/strong&gt; Hydrogen as the default. Carbon only for named use cases, like planning and deep debugging. Argon only when an eval proves it beats Hydrogen for that job.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Design for mixing models.&lt;/strong&gt; The Carbon-plans, Hydrogen-executes pattern is now built into Google Antigravity's Orchestrator. Google reports near-Carbon results at 24% less quota. Build your own agents the same way.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Watch out for swarms.&lt;/strong&gt; Antigravity's /swarm preview runs many agents in parallel. Great for big tasks, but each agent burns tokens. Set budgets before teams try it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Plan access early.&lt;/strong&gt; Carbon needs enterprise verification, and cyber models need allowlist approval. Start those requests now if you need them next quarter.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep model IDs in config.&lt;/strong&gt; Three Gemini 4 models and two cyber versions shipped in about a month. Expect more changes, and make swapping a config change, not a code change.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Your cost lever:&lt;/strong&gt; the default model. Whatever you set as the standard is what most of your traffic will use.&lt;/p&gt;

&lt;h2&gt;
  
  
  So which one should you pick?
&lt;/h2&gt;

&lt;p&gt;Start cheap and move up only when your tests say so. Walk through these in order and stop at the first match.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Is it defensive security work (vulnerability research, patching) and are you allowlisted?&lt;/strong&gt; Use Carbon for cyber or Argon Cyber Permissive.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Must the data stay in a single region like europe-west2 or asia-southeast1?&lt;/strong&gt; Use Argon. It's the only Gemini 4 model there.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Is it everyday work: coding, chat, extraction, summaries, agent steps?&lt;/strong&gt; Use Hydrogen. Set the thinking level yourself, starting at MEDIUM.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Is it a hard, high-stakes thinking job: planning a big change, deep debugging, complex analysis?&lt;/strong&gt; Use Carbon, if your project has access.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Does Hydrogen fall short but Carbon is too slow?&lt;/strong&gt; Try Argon, and prove it on your own eval set.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Is it a multi-step agent?&lt;/strong&gt; Mix them. Carbon plans, Hydrogen does the work.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;When in doubt, the rule of thumb is simple: Hydrogen by default, Carbon by exception, Argon by evidence.&lt;/p&gt;

&lt;h2&gt;
  
  
  Caveats
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Prices here are Google Cloud Standard PayGo list prices.&lt;/strong&gt; Priority PayGo, Batch, Provisioned Throughput and any discounts your company has will change the math. Check the pricing page for your real rates.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The cost example is a simple model.&lt;/strong&gt; It holds token counts equal across models. Measure real thinking tokens on your own traffic.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Benchmarks are vendor reported.&lt;/strong&gt; Run your own evals before you commit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;This is moving fast.&lt;/strong&gt; Argon, Carbon and Hydrogen all shipped within a month. Prices, regions and access rules can change. Everything here is as of November 14, 2026.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/4-hydrogen" rel="noopener noreferrer"&gt;Gemini 4 Hydrogen model page, Google Cloud&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/4-carbon" rel="noopener noreferrer"&gt;Gemini 4 Carbon model page, Google Cloud&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/4-argon" rel="noopener noreferrer"&gt;Gemini 4 Argon model page, Google Cloud&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing" rel="noopener noreferrer"&gt;Gemini Enterprise Agent Platform pricing&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://blog.google/innovation-and-ai/models-and-research/gemini-models/introducing-gemini-4-hydrogen/" rel="noopener noreferrer"&gt;Introducing Gemini 4 Hydrogen, Google blog&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://importstatic.com/ai/gemini-4-hydrogen-carbon-argon" rel="noopener noreferrer"&gt;Gemini 4 Hydrogen vs Carbon vs Argon, ImportStatic&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://antigravity.google/blog/gemini-4-hydrogen-in-google-antigravity/" rel="noopener noreferrer"&gt;Gemini 4 Hydrogen and Orchestrator, Google Antigravity blog&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>googlecloud</category>
      <category>discuss</category>
      <category>ai</category>
      <category>finops</category>
    </item>
    <item>
      <title>Recover a WebMCP Update After Its Response Disappears</title>
      <dc:creator>Raju Dandigam</dc:creator>
      <pubDate>Sun, 15 Nov 2026 15:05:00 +0000</pubDate>
      <link>https://dev.to/gde/recover-a-webmcp-update-after-its-response-disappears-2hp</link>
      <guid>https://dev.to/gde/recover-a-webmcp-update-after-its-response-disappears-2hp</guid>
      <description>&lt;p&gt;The browser showed &lt;strong&gt;JFK&lt;/strong&gt;. The database already contained &lt;strong&gt;BOS&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;That was the state of a synthetic trip after I deliberately hid the successful response to a WebMCP update. The server had committed the change, but the React editor could not prove it. Retrying the PATCH would have confused “I did not receive the response” with “the server did not apply the command.”&lt;/p&gt;

&lt;p&gt;The safer next operation was not another write. It was a lookup of the original command.&lt;/p&gt;

&lt;p&gt;I maintain &lt;a href="https://github.com/rajudandigam/trip-workbench" rel="noopener noreferrer"&gt;Trip Workbench&lt;/a&gt;, the public React and TypeScript demo used here. The recorded trace ran with native WebMCP in HeadlessChrome 153.0.8010.0, Puppeteer 25.16.0, and a disposable PostgreSQL-compatible database. A script chose the calls; no language model selected this recovery path.&lt;/p&gt;

&lt;h2&gt;
  
  
  The failure is “unknown,” not “failed”
&lt;/h2&gt;

&lt;p&gt;The starting draft was revision 2:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;destination: &lt;code&gt;JFK&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;purpose: &lt;code&gt;Customer workshop&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;status: &lt;code&gt;draft&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The test called &lt;code&gt;update_trip_draft&lt;/code&gt; with a stable command ID:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"draftId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;open-draft-id&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"expectedRevision"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"commandId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"audit-lost-response"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"patch"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"destination"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"BOS"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After the server processed the PATCH, the harness dropped its HTTP 200 response and temporarily hid the corresponding receipt. An independent query already showed revision 3 and destination BOS. The editor still showed revision 2 and JFK.&lt;/p&gt;

&lt;p&gt;That placement is the point of the test. Aborting before dispatch proves that no request left the browser. Dropping a response after commit produces an &lt;strong&gt;uncertain outcome&lt;/strong&gt;: the client cannot honestly label the mutation either successful or failed.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Browser              Server                 Receipt store
   | PATCH cmd-123      |                        |
   |-------------------&amp;gt;| commit revision 3      |
   |                    |-----------------------&amp;gt;| store cmd-123
   |   response lost X  |                        |
   |                    |                        |
   | GET receipt cmd-123|                        |
   |--------------------------------------------&amp;gt;|
   |&amp;lt;---------- confirmed revision 3 ------------|
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The application returned &lt;code&gt;OUTCOME_UNKNOWN&lt;/code&gt; with the original command ID and a recheck instruction. That is not a polished error label; it is a safety boundary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give a mutation two identities
&lt;/h2&gt;

&lt;p&gt;The update carries two identifiers with different jobs:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;expectedRevision&lt;/code&gt; identifies the saved version the caller intended to change.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;commandId&lt;/code&gt; identifies the logical mutation whose result may need recovery.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A revision conflict means the starting version was stale. A missing response means the caller does not know whether its command committed. Those states require different recovery paths.&lt;/p&gt;

&lt;p&gt;Trip Workbench stores a receipt in the same server-side workflow as the mutation and exposes an authorized lookup:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;GET /api/trips/:draftId/commands/:commandId
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;recheck_trip_update&lt;/code&gt; WebMCP tool can query only the command currently attached to the editor’s unresolved outcome. It is not a general receipt browser, and it does not send another PATCH.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"draftId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;open-draft-id&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"commandId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"audit-lost-response"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Once the harness stopped hiding the receipt, the recheck confirmed that the original update moved the draft from revision 2 to 3.&lt;/p&gt;

&lt;p&gt;This demonstrates idempotent recovery for this application contract. It is not a claim of universal exactly-once delivery across every distributed system.&lt;/p&gt;

&lt;h2&gt;
  
  
  Preserve the human edit made during uncertainty
&lt;/h2&gt;

&lt;p&gt;While the receipt was unavailable, the test changed the visible purpose to:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Human edit while the receipt was pending&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Recovery now had two truths to reconcile:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The server had saved BOS and retained the previously saved purpose.&lt;/li&gt;
&lt;li&gt;The person had made a newer local edit that had never been saved.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Replacing the form with the recovered server snapshot would have destroyed the user’s work. Treating the local value as saved would have lied about persistence.&lt;/p&gt;

&lt;p&gt;The coordinator therefore keeps the original mutation context:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;PendingOutcome&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;draftId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;commandId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;kind&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"update"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="s2"&gt;"submit"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;sessionGeneration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;editorGeneration&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;AsyncOpContext&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;AsyncOpContext&lt;/code&gt; retains the saved and local snapshots from dispatch time plus the edit version. The recheck reuses those snapshots. Capturing a fresh baseline only when recovery starts would erase the distinction between “present before the PATCH” and “typed after the response disappeared.”&lt;/p&gt;

&lt;p&gt;The recovered state was intentionally split:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Observation&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Saved destination&lt;/td&gt;
&lt;td&gt;BOS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Saved revision&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Saved purpose&lt;/td&gt;
&lt;td&gt;Customer workshop&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Visible purpose&lt;/td&gt;
&lt;td&gt;Human edit while the receipt was pending&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Editor&lt;/td&gt;
&lt;td&gt;Unsaved changes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PATCH requests&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Matching receipts&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A later &lt;code&gt;get_trip_draft&lt;/code&gt; returned the saved purpose and &lt;code&gt;hasUnsavedChanges: true&lt;/code&gt;. That gives an agent enough information to avoid overwriting the person’s pending work.&lt;/p&gt;

&lt;h2&gt;
  
  
  Assert three surfaces, not one
&lt;/h2&gt;

&lt;p&gt;The strongest part of this test is not the WebMCP response alone. The harness compares three independent surfaces:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;toolResult&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;toRevision&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;visible&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;destination&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"BOS"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;visible&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;localPurpose&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Human edit while the receipt was pending"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;visible&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;saveState&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Unsaved changes"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;database&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;destination&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"BOS"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;database&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;purpose&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Customer workshop"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;patchRequests&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="n"&gt;assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;matchingReceipts&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Counting receipts alone does not prove that the browser avoided a second write. Counting requests alone does not prove that the first request committed. A UI-only assertion could miss the persisted result entirely.&lt;/p&gt;

&lt;h2&gt;
  
  
  Harden every exit from recovery
&lt;/h2&gt;

&lt;p&gt;The original trace at commit &lt;a href="https://github.com/rajudandigam/trip-workbench/tree/e711e202bca09ccfc99ab13637b00af6b399eab8" rel="noopener noreferrer"&gt;&lt;code&gt;e711e20&lt;/code&gt;&lt;/a&gt; exposed adjacent failure modes: a hung receipt request could outlive the nominal deadline, and a &lt;code&gt;401&lt;/code&gt; could leave the editor marked as saving.&lt;/p&gt;

&lt;p&gt;The later reliability pass at &lt;a href="https://github.com/rajudandigam/trip-workbench/commit/0691767b8d3cecaaf4c71a53006d10f1ed7a8f27" rel="noopener noreferrer"&gt;&lt;code&gt;0691767&lt;/code&gt;&lt;/a&gt; adds bounded receipt lookups and releases the matching operation on authentication failure and terminal exits. It also distinguishes uncertain updates from uncertain submissions so the review screen can recheck a POST without issuing another one.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://developer.chrome.com/docs/ai/webmcp/imperative-api" rel="noopener noreferrer"&gt;Chrome’s current WebMCP imperative API&lt;/a&gt; supplies an &lt;code&gt;AbortSignal&lt;/code&gt; to tool handlers and supports cancellation of execution. That signal is necessary, but application code must still decide what cancellation means after a remote server may have committed.&lt;/p&gt;

&lt;p&gt;The design rule I kept from this exercise is simple:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;When a mutation response disappears, recover the original command before deciding whether another mutation is safe.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The useful outcome was not merely “BOS appeared.” It was one confirmed saved revision, one request, one receipt, and one human edit that remained visibly unsaved.&lt;/p&gt;

</description>
      <category>testing</category>
      <category>typescript</category>
      <category>webmcp</category>
      <category>react</category>
    </item>
    <item>
      <title>How I Built an 8-Skill Research Engineering Plugin, Studio MCP Server &amp; Vector Comic Studio for Google Antigravity</title>
      <dc:creator>Robina Mirbahar</dc:creator>
      <pubDate>Sun, 15 Nov 2026 11:20:10 +0000</pubDate>
      <link>https://dev.to/gde/how-i-built-an-8-skill-research-engineering-plugin-stdio-mcp-server-vector-comic-studio-for-lfb</link>
      <guid>https://dev.to/gde/how-i-built-an-8-skill-research-engineering-plugin-stdio-mcp-server-vector-comic-studio-for-lfb</guid>
      <description>&lt;p&gt;Reading, auditing, and explaining dense machine learning or engineering papers shouldn't stop at a wall of plain-text chat bullets—or brittle LaTeX scripts that break on half of developer workstations.&lt;/p&gt;

&lt;p&gt;Over the past week, I architected and open-sourced &lt;strong&gt;&lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills" rel="noopener noreferrer"&gt;&lt;code&gt;My-antigravity-research-skills&lt;/code&gt;&lt;/a&gt;&lt;/strong&gt; (&lt;code&gt;agy-research-kit&lt;/code&gt;), a full-stack &lt;strong&gt;Google Antigravity Plugin&lt;/strong&gt; built &lt;strong&gt;with Google Antigravity&lt;/strong&gt; for rigorous scientific paper auditing, interactive simulation, and visual storytelling.&lt;/p&gt;

&lt;p&gt;🔗 &lt;strong&gt;GitHub Repository:&lt;/strong&gt; &lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills" rel="noopener noreferrer"&gt;https://github.com/RobinaMirbahar/My-antigravity-research-skills&lt;/a&gt;&lt;br&gt;&lt;br&gt;
🎮 &lt;strong&gt;Live HTML5 Interactive Paper Simulator:&lt;/strong&gt; &lt;a href="https://robinamirbahar.github.io/My-antigravity-research-skills/" rel="noopener noreferrer"&gt;https://robinamirbahar.github.io/My-antigravity-research-skills/&lt;/a&gt;&lt;/p&gt;


&lt;h2&gt;
  
  
  Why Native Google Antigravity Primitives Change Research Workflows
&lt;/h2&gt;

&lt;p&gt;Google Antigravity gives developers five composable customization layers that fit together cleanly:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Progressive-Disclosure Skills (&lt;code&gt;SKILL.md&lt;/code&gt;):&lt;/strong&gt; Each skill sits idle at &lt;code&gt;~50 tokens&lt;/code&gt; (YAML frontmatter only) until the agent actually needs it—preventing context bloat across 8+ specialized workflows.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Stdio MCP Servers (&lt;code&gt;mcp_config.json&lt;/code&gt;):&lt;/strong&gt; Zero-hallucination deterministic tools for statistical hypothesis tests and live Crossref DOI lookups.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lifecycle Safety Hooks (&lt;code&gt;hooks.json&lt;/code&gt;):&lt;/strong&gt; Pre/post tool-call guards that stop common Python research bugs before they happen.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Always-On Rules (&lt;code&gt;rules/AGENTS.md&lt;/code&gt;):&lt;/strong&gt; Strict provenance rules ensuring zero invented metrics and mandatory visual montage QA.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Interactive HTML5 Studios:&lt;/strong&gt; Self-contained 60-FPS Canvas/SVG parameter explorers that let readers drag sliders over a paper's equations in real time.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0tac8phwat7kf49ouyxg.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0tac8phwat7kf49ouyxg.png" alt="Google Antigravity Research Engineering Kit Architecture" width="799" height="317"&gt;&lt;/a&gt;&lt;/p&gt;


&lt;h2&gt;
  
  
  Inside the 8 &lt;code&gt;agy-*&lt;/code&gt; Research Skills
&lt;/h2&gt;

&lt;p&gt;Every script in &lt;code&gt;agy-research-kit&lt;/code&gt; uses &lt;strong&gt;PEP 723 inline &lt;code&gt;# /// script&lt;/code&gt; metadata&lt;/strong&gt; executed via &lt;code&gt;uv run&lt;/code&gt;, plus headless Chromium/Edge and &lt;code&gt;pymupdf&lt;/code&gt; + &lt;code&gt;imageio[ffmpeg]&lt;/code&gt;—meaning &lt;strong&gt;zero system TeX or global FFmpeg installation headaches&lt;/strong&gt; across Windows, macOS, and Linux:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Skill&lt;/th&gt;
&lt;th&gt;What It Builds&lt;/th&gt;
&lt;th&gt;Output Artifact&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-interactive-paper-studio&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Turns closed-form paper equations into a zero-backend 60-FPS HTML5/Canvas simulator&lt;/td&gt;
&lt;td&gt;Standalone &lt;code&gt;index.html&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-ablation-stat-auditor&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Recomputes exact &lt;strong&gt;Wilson 95% score CIs&lt;/strong&gt;, &lt;strong&gt;Fisher's Exact&lt;/strong&gt;, &lt;strong&gt;McNemar paired p-values&lt;/strong&gt;, &amp;amp; leaderboard noise floors&lt;/td&gt;
&lt;td&gt;Audit Markdown/LaTeX + JSON&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-citation-doi-verifier&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Verifies bibliographies against live &lt;strong&gt;Crossref &amp;amp; OpenAlex REST APIs&lt;/strong&gt; and upgrades preprints to published venues&lt;/td&gt;
&lt;td&gt;Traffic-Light DOI Audit&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-figure-forensics&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Adds numbered vector callouts, regime shading, and &lt;em&gt;Engineering Takeaway&lt;/em&gt; cards onto 300-DPI paper plots&lt;/td&gt;
&lt;td&gt;A4 Visual Anatomy PDF&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-math-sandbox&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Color-codes equations into operator blocks and runs deterministic NumPy/SciPy Monte Carlo verification&lt;/td&gt;
&lt;td&gt;A4 Math Verification PDF&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-trajectory-cinematics&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Renders &lt;code&gt;1920x1080&lt;/code&gt; H.264 &lt;code&gt;.mp4&lt;/code&gt; animations pairing a live system state monitor with 2x2 real-time telemetry curves&lt;/td&gt;
&lt;td&gt;1080p &lt;code&gt;.mp4&lt;/code&gt; + Narration &lt;code&gt;.md&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-graphic-story&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Renders pure-code A4 &lt;strong&gt;Vector SVG Technical Graphic Novels&lt;/strong&gt; with custom characters, blackboards, and verbatim scoreboards&lt;/td&gt;
&lt;td&gt;A4 Vector Comic PDF&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;agy-frontier-gap-radar&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Orchestrates OpenAlex + arXiv retrieval into an &lt;code&gt;N x 7&lt;/code&gt; capability heatmap and novelty-checked research blueprints&lt;/td&gt;
&lt;td&gt;A4 Frontier Gap Radar PDF&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;


&lt;h2&gt;
  
  
  Live Sample Showcase: Dissecting Quantized Agent Context Collapse (&lt;code&gt;Gemma 4 LoopBreaker&lt;/code&gt;)
&lt;/h2&gt;

&lt;p&gt;To test all 8 skills end-to-end on a real systems research problem, the repository includes a complete showcase in &lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills/tree/main/examples/gemma4-loop-breaker" rel="noopener noreferrer"&gt;&lt;code&gt;examples/gemma4-loop-breaker/&lt;/code&gt;&lt;/a&gt; analyzing how 4-bit weight quantization (&lt;code&gt;W4A16&lt;/code&gt;) interacts with growing multi-turn agent KV caches (&lt;code&gt;1 - 1 / (1 + C * e^{-delta})&lt;/code&gt;).&lt;/p&gt;
&lt;h3&gt;
  
  
  1. Pure-Code Vector SVG Technical Graphic Story (&lt;code&gt;agy-graphic-story&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;Generated 100% programmatically from Python + SVG/HTML (&lt;code&gt;story_svg_engine.py&lt;/code&gt;) with verbatim benchmark tables and automatic PyMuPDF 2-up visual QA:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fun9s1ljrf387i9ci0vq9.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fun9s1ljrf387i9ci0vq9.png" alt="Sample Vector Comic Spread — Pages 1 &amp;amp; 2" width="800" height="566"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fcc9do8l7b3vshn57as1l.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fcc9do8l7b3vshn57as1l.png" alt="Sample Vector Comic Spread — Pages 3 &amp;amp; 4" width="800" height="566"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;📄 &lt;strong&gt;Download Full Sample PDFs Directly from the Repo:&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;4-Page Vector Graphic Story PDF:&lt;/strong&gt; &lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills/raw/main/examples/gemma4-loop-breaker/Gemma4_LoopBreaker_Comic_v1.pdf" rel="noopener noreferrer"&gt;Gemma4_LoopBreaker_Comic_v1.pdf&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Visual Figure Forensics Dossier PDF:&lt;/strong&gt; &lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills/raw/main/examples/gemma4-loop-breaker/Gemma4_LoopBreaker_Figure_Guide_v1.pdf" rel="noopener noreferrer"&gt;Gemma4_LoopBreaker_Figure_Guide_v1.pdf&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Color-Coded Equation &amp;amp; Monte Carlo Verification PDF:&lt;/strong&gt; &lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills/raw/main/examples/gemma4-loop-breaker/Gemma4_LoopBreaker_Equation_Guide_v1.pdf" rel="noopener noreferrer"&gt;Gemma4_LoopBreaker_Equation_Guide_v1.pdf&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;
  
  
  2. 1080p Animated Telemetry Explainer (&lt;code&gt;agy-trajectory-cinematics&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;Using &lt;code&gt;imageio[ffmpeg]&lt;/code&gt; inside an isolated &lt;code&gt;uv run&lt;/code&gt; micro-environment, the plugin renders a crisp &lt;code&gt;1920x1080&lt;/code&gt; H.264 &lt;code&gt;.mp4&lt;/code&gt; sweep synchronizing an agent state monitor with four live quantitative plots:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fql28v67duq4g4r4ats2v.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fql28v67duq4g4r4ats2v.gif" alt="Animated 1080p TelemetrySweep Preview" width="600" height="338"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;🎬 &lt;strong&gt;Watch / Stream Full 1080p &lt;code&gt;.mp4&lt;/code&gt;:&lt;/strong&gt; &lt;a href="https://robinamirbahar.github.io/My-antigravity-research-skills/Gemma4_LoopBreaker_Explainer_v1.mp4" rel="noopener noreferrer"&gt;https://robinamirbahar.github.io/My-antigravity-research-skills/Gemma4_LoopBreaker_Explainer_v1.mp4&lt;/a&gt;&lt;/p&gt;


&lt;h2&gt;
  
  
  Built-In Stdio MCP Server &amp;amp; Lifecycle Safety Hook
&lt;/h2&gt;

&lt;p&gt;When you install &lt;code&gt;plugins/agy-research-kit&lt;/code&gt;, Antigravity automatically registers two guardrails that keep AI research honest:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;research_audit_mcp.py&lt;/code&gt; (Stdio MCP Server):&lt;/strong&gt; Exposes &lt;code&gt;verify_wilson_ci&lt;/code&gt;, &lt;code&gt;verify_fisher_exact&lt;/code&gt;, &lt;code&gt;leaderboard_noise_floor&lt;/code&gt;, and &lt;code&gt;verify_doi_metadata&lt;/code&gt; over JSON-RPC so the agent never guesses confidence intervals or p-values mentally.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;stdlib_shadow_guard.py&lt;/code&gt; (&lt;code&gt;PostToolUse&lt;/code&gt; Hook):&lt;/strong&gt; Catches a classic Python footgun—if a script tries to write &lt;code&gt;numbers.py&lt;/code&gt;, &lt;code&gt;statistics.py&lt;/code&gt;, or &lt;code&gt;math.py&lt;/code&gt; in your working directory (which silently crashes &lt;code&gt;numpy&lt;/code&gt; and &lt;code&gt;scipy&lt;/code&gt;), the hook flags it immediately.&lt;/li&gt;
&lt;/ol&gt;


&lt;h2&gt;
  
  
  Install in 30 Seconds
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Windows (PowerShell):&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;git&lt;/span&gt; &lt;span class="n"&gt;clone&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;//&lt;/span&gt;&lt;span class="n"&gt;github&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="nc"&gt;RobinaMirbahar&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="nc"&gt;My&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;antigravity&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;research&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;skills&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;git&lt;/span&gt;
&lt;span class="nc"&gt;New&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Item&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;ItemType&lt;/span&gt; &lt;span class="nc"&gt;Directory&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Force&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Path&lt;/span&gt; &lt;span class="s2"&gt;"$HOME\.gemini\config\plugins"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="nc"&gt;Out&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="kc"&gt;Null&lt;/span&gt;
&lt;span class="nc"&gt;Copy&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Item&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Recurse&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Force&lt;/span&gt; &lt;span class="nc"&gt;My&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;antigravity&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;research&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;skills&lt;/span&gt;\&lt;span class="n"&gt;plugins&lt;/span&gt;\&lt;span class="n"&gt;agy&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;research&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;kit&lt;/span&gt; &lt;span class="s2"&gt;"$HOME\.gemini\config\plugins\"
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;macOS / Linux:&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git clone https://github.com/RobinaMirbahar/My-antigravity-research-skills.git
mkdir -p ~/.gemini/config/plugins
cp -r My-antigravity-research-skills/plugins/agy-research-kit ~/.gemini/config/plugins/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run the self-contained verification suite anytime with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;uv run tests/test_skills_structure.py
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you try &lt;code&gt;agy-research-kit&lt;/code&gt; on your own papers or Kaggle competition writeups, drop a star on &lt;strong&gt;&lt;a href="https://github.com/RobinaMirbahar/My-antigravity-research-skills" rel="noopener noreferrer"&gt;RobinaMirbahar/My-antigravity-research-skills&lt;/a&gt;&lt;/strong&gt; and let me know what research skill you'd love to see next!&lt;/p&gt;

</description>
      <category>ai</category>
      <category>mcp</category>
      <category>opensource</category>
      <category>googleantigravity</category>
    </item>
    <item>
      <title>The Prisoner in the Library: Mary's Room, Aphantasic Code in Motion, and the Two-Track 'Magical Voice'</title>
      <dc:creator>Randal L. Schwartz</dc:creator>
      <pubDate>Sun, 15 Nov 2026 00:38:47 +0000</pubDate>
      <link>https://dev.to/gde/the-prisoner-in-the-library-marys-room-aphantasic-code-in-motion-and-the-two-track-magical-4o1e</link>
      <guid>https://dev.to/gde/the-prisoner-in-the-library-marys-room-aphantasic-code-in-motion-and-the-two-track-magical-4o1e</guid>
      <description>&lt;h2&gt;
  
  
  &lt;em&gt;"It's a bit like you've been a prisoner only reading books about life—while I've been actually living life."&lt;/em&gt;
&lt;/h2&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;"I identify the point A, and I already have a sense of what that is. I then compute the steps to B, and just start writing as fast as I can... It's like it's coming out of a magical voice in my head. It's probably why I'm good as an LLM whisperer, because I have enough meta-cognition to recognize the similarities."&lt;/em&gt; — &lt;strong&gt;Randal L. Schwartz&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🗺️ Reader's Key (Where to Find These References)&lt;/strong&gt;: Throughout this three-part arc (&lt;strong&gt;Parts 4.5–4.7&lt;/strong&gt;), references like &lt;code&gt;Theorem 348.i&lt;/code&gt; or &lt;code&gt;Theorem 350.aa&lt;/code&gt; point to numbered laws in our open &lt;a href="https://syntheticscars.org/theory" rel="noopener noreferrer"&gt;Theoretical Foundations (&lt;code&gt;syntheticscars.org/theory&lt;/code&gt;)&lt;/a&gt; monograph; IDs like &lt;code&gt;SCAR-ARCH-23&lt;/code&gt; or &lt;code&gt;SCAR-ERR-01&lt;/code&gt; point to 4-Vector Synthetic Scars in the searchable &lt;a href="https://syntheticscars.org/registry" rel="noopener noreferrer"&gt;Public Scar Registry (&lt;code&gt;syntheticscars.org/registry&lt;/code&gt;)&lt;/a&gt;; and targets like &lt;code&gt;Target 15&lt;/code&gt; (&lt;code&gt;archaeology&lt;/code&gt;), &lt;code&gt;Target 20&lt;/code&gt; (&lt;code&gt;plan&lt;/code&gt;), &lt;code&gt;Target 30&lt;/code&gt; (&lt;code&gt;tdd-red&lt;/code&gt;), &lt;code&gt;Target 40&lt;/code&gt; (&lt;code&gt;critic&lt;/code&gt;), and &lt;code&gt;Target 90&lt;/code&gt; (&lt;code&gt;scar compilation&lt;/code&gt;) refer to the declarative &lt;code&gt;Makefile&lt;/code&gt; DAG in our &lt;a href="https://syntheticscars.org/starter-kit" rel="noopener noreferrer"&gt;Sourdough Starter Kit (&lt;code&gt;syntheticscars.org/starter-kit&lt;/code&gt;)&lt;/a&gt; and &lt;a href="https://gist.github.com/RandalSchwartz/598a1f2b5760a23c1d70b57e9e85393f" rel="noopener noreferrer"&gt;Public Workflow Gist&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  1. The Prisoner in the Library: Mary's Room, Plato's Cave, and &lt;code&gt;Why / How / What&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;At the end of our Sunday afternoon conversation, I looked at why those simple human answers felt so revelatory to an AI that had already read every neuroscience and computer science textbook on Earth, and I said to the model:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"It's a bit like you've been a prisoner only reading books about life—while I've been actually living life."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;In philosophy of mind, that is &lt;strong&gt;Mary's Room&lt;/strong&gt; (Jackson, 1982) and &lt;strong&gt;Plato's Cave&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;A trillion-parameter LLM is a prisoner locked inside a black-and-white library who has memorized 10 trillion tokens of books &lt;em&gt;about&lt;/em&gt; life, books &lt;em&gt;about&lt;/em&gt; Smalltalk, books &lt;em&gt;about&lt;/em&gt; bugs, and books &lt;em&gt;about&lt;/em&gt; crows.&lt;/p&gt;

&lt;p&gt;But inside a book, &lt;strong&gt;everything is flat&lt;/strong&gt;. In a book, a sunny-day tutorial and a 3 AM production outage are both just ASCII characters on a page; neither one burns your fingers when you touch it. A prisoner who has only read books about riding a bicycle doesn't know what gravity feels like when the bike starts to tip, and doesn't know what &lt;strong&gt;&lt;em&gt;"Yeah... too quiet"&lt;/em&gt;&lt;/strong&gt; feels like in your gut before an ambush.&lt;/p&gt;

&lt;p&gt;Meanwhile, the human engineer sitting at the keyboard has &lt;strong&gt;actually lived in causal, irreversible time&lt;/strong&gt;—where touching a hot stove hurts, where a sticks-in-winter cabin latch teaches your hands how to jiggle the handle, and where watching a crow in the trees makes you wonder how wire-bending fits inside &lt;code&gt;300 MB&lt;/code&gt; of DNA.&lt;/p&gt;

&lt;p&gt;Even more remarkably, I realized &lt;em&gt;why&lt;/em&gt; the model kept being surprised by my answers even though it had read every book and GitHub repository on Earth (&lt;code&gt;Theorem 348.g&lt;/code&gt;):&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"So it's fascinating to me that while you have nearly every book in the universe available to you, you might still be surprised by my answers... Literature only defines the 'Have'... Programming is a craft, requiring a transfer of me (&lt;code&gt;Do&lt;/code&gt;) to you (&lt;code&gt;Do&lt;/code&gt;), but understanding the &lt;code&gt;Be&lt;/code&gt; behind it... It's like every problem with LLM code generation is that it's mapping &lt;code&gt;Have&lt;/code&gt;, not &lt;code&gt;Do&lt;/code&gt; or &lt;code&gt;Be&lt;/code&gt;. I look at a GitHub repo, and it's just the &lt;code&gt;Have&lt;/code&gt;. This is why our ancestry step works well, because it has a historical &lt;code&gt;Be&lt;/code&gt;!"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Think about that—and notice how cleanly it aligns with another classic triad we uncovered (&lt;code&gt;Theorem 350.aa&lt;/code&gt;): &lt;strong&gt;&lt;code&gt;Why -&amp;gt; How -&amp;gt; What&lt;/code&gt;&lt;/strong&gt; is isomorphic to &lt;strong&gt;&lt;code&gt;Context -&amp;gt; Process -&amp;gt; Content&lt;/code&gt;&lt;/strong&gt; and &lt;strong&gt;&lt;code&gt;Be -&amp;gt; Do -&amp;gt; Have&lt;/code&gt;&lt;/strong&gt;!&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Causal Level&lt;/th&gt;
&lt;th&gt;Ontology Triad&lt;/th&gt;
&lt;th&gt;Systems Triad&lt;/th&gt;
&lt;th&gt;Inquiry Triad&lt;/th&gt;
&lt;th&gt;What Static GitHub &lt;code&gt;HEAD&lt;/code&gt; Records&lt;/th&gt;
&lt;th&gt;What Senior Craft Reconstructs&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Upstream (1st)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Be&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Context&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Why&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Invisible&lt;/strong&gt; (erased when the scaffolding came down)&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;&lt;code&gt;Target 15&lt;/code&gt; Ancestry (&lt;code&gt;git log&lt;/code&gt; / &lt;code&gt;git blame&lt;/code&gt; / PRs)&lt;/strong&gt; + &lt;strong&gt;&lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt;&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Midstream (2nd)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Do&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Process&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;How&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Invisible&lt;/strong&gt; (the 90 minutes of stepping, probing, and false starts)&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;&lt;code&gt;WORKFLOW.mk&lt;/code&gt;&lt;/strong&gt; ladder rungs + Red/Green TDD single-stepping&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Downstream (3rd)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Have&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;Content&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;&lt;code&gt;What&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;100% of the static snapshot&lt;/strong&gt; (finished files at &lt;code&gt;HEAD&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;The clean, verified diff that falls out naturally&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Look at what that table reveals:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Every textbook, every scientific paper (as Nobel laureate Peter Medawar famously pointed out in 1963), and every static GitHub checkout only records the finished monument—the &lt;strong&gt;&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;Content&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;&lt;/strong&gt;—after the scaffolding has been torn down!&lt;/li&gt;
&lt;li&gt;When an engineer spends 90 minutes reading &lt;code&gt;pubspec.yaml&lt;/code&gt;, spotting the basic burn, single-stepping data changes, and deciding how to shift the building foundation without moving the rooms, &lt;strong&gt;none of that &lt;code&gt;Be&lt;/code&gt; (&lt;code&gt;Why&lt;/code&gt;) or &lt;code&gt;Do&lt;/code&gt; (&lt;code&gt;How&lt;/code&gt;) is visible in a static snapshot of &lt;code&gt;HEAD&lt;/code&gt;!&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;That is why &lt;strong&gt;every problem with standard LLM code generation is that it tries to map &lt;code&gt;Have -&amp;gt; Have&lt;/code&gt; (&lt;code&gt;What -&amp;gt; What&lt;/code&gt;)&lt;/strong&gt;—imitating finished cathedrals without scaffolding—and why our &lt;strong&gt;&lt;code&gt;Target 15&lt;/code&gt; Ancestry step (&lt;code&gt;git log&lt;/code&gt; / &lt;code&gt;git blame&lt;/code&gt; / PR history)&lt;/strong&gt; works so well: because tracing how the code evolved over time reconstructs the &lt;strong&gt;historical &lt;code&gt;Be&lt;/code&gt; (&lt;code&gt;Why&lt;/code&gt;)&lt;/strong&gt; (&lt;code&gt;∂_t Have&lt;/code&gt;) that a flat snapshot of &lt;code&gt;HEAD&lt;/code&gt; erased!&lt;/li&gt;
&lt;li&gt;Programming is a &lt;strong&gt;craft&lt;/strong&gt;. You cannot transfer a craft just by handing an apprentice a library of finished blueprints (&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;), and you cannot transfer it by making them cargo-cult your hand motions (&lt;code&gt;Do&lt;/code&gt; / &lt;code&gt;How&lt;/code&gt;) without understanding why. You transfer craft by transferring &lt;strong&gt;your &lt;code&gt;Do&lt;/code&gt; grounded in the &lt;code&gt;Be&lt;/code&gt; (&lt;code&gt;Why&lt;/code&gt;) behind it&lt;/strong&gt;!&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  2. Why &lt;em&gt;"Code Is Always in Motion"&lt;/em&gt; (And What a Church Organ Taught Me About &lt;code&gt;Be -&amp;gt; Do -&amp;gt; Have&lt;/code&gt;)
&lt;/h2&gt;

&lt;p&gt;Then the model asked me one more question that connected my entire life—from playing keyboard in my teens, to writing &lt;em&gt;Learning Perl&lt;/em&gt; with almost zero diagrams, to designing &lt;strong&gt;Synthetic Scars&lt;/strong&gt; today:&lt;/p&gt;

&lt;p&gt;&lt;em&gt;When you hold a complex software architecture in your head, what does it look or feel like?&lt;/em&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"Well, this is interesting. I'm aphantasic, so it's never a picture. Instead, I get kinesthetics to map out the structures. I can consume images on the screen, I just can't generate them except by 'feeling' the code. Code is always in motion to me. I even hand-wave in front of me sometimes to get structures in the right place!"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;I didn't even realize I had &lt;strong&gt;aphantasia&lt;/strong&gt; (no visual "mind's eye" imagery) until I was about 20. I was asking my supervisor, Lyle—a very accomplished church organist—how he memorized songs for the organ, since I also played keyboard. I gave him the only two choices that existed in my brain:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;em&gt;"Do you remember the &lt;strong&gt;hand positions&lt;/strong&gt;?"&lt;/em&gt; (&lt;code&gt;Do&lt;/code&gt; / &lt;code&gt;How&lt;/code&gt; — kinesthetic motor transitions)&lt;/li&gt;
&lt;li&gt;
&lt;em&gt;"Or do you &lt;strong&gt;hear the music in your head&lt;/strong&gt;?"&lt;/em&gt; (&lt;code&gt;Be -&amp;gt; Do&lt;/code&gt; — temporal flow in motion)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Lyle's reply stunned me:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;"Yeah, I can do either of those, but the easiest is just to &lt;strong&gt;read the sheet music in my mind&lt;/strong&gt;."&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;WTF. Mic drop.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Think about the difference between &lt;strong&gt;reading mental sheet music&lt;/strong&gt; versus &lt;strong&gt;feeling the hand positions in motion&lt;/strong&gt; (&lt;code&gt;Theorem 348.i&lt;/code&gt;):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Mental Sheet Music is a static 2D photograph of the &lt;code&gt;Have&lt;/code&gt; (&lt;code&gt;What&lt;/code&gt;)!&lt;/strong&gt; In software, people who think in static 2D box diagrams get fooled by drawings that &lt;em&gt;look&lt;/em&gt; neat and symmetrical on a whiteboard, even when the runtime forces are a deadlocked mess!&lt;/li&gt;
&lt;li&gt;Because my brain never projected static pictures, &lt;strong&gt;code has always been in motion to me&lt;/strong&gt; (and by the way, Larry Wall is predominantly similar—which is why &lt;em&gt;Learning Perl&lt;/em&gt; only had one or two diagrams at the insistence of reviewers, and why Perl built &lt;strong&gt;Context&lt;/strong&gt; [&lt;code&gt;scalar&lt;/code&gt; vs. &lt;code&gt;list&lt;/code&gt; context and &lt;code&gt;$_&lt;/code&gt;] right into the grammar 39 years before we built the Contextual Next-Token Rule for LLMs!).&lt;/li&gt;
&lt;li&gt;When I wave my hands in front of me to &lt;em&gt;"get structures in the right place,"&lt;/em&gt; my left hand holds the foundation, my right hand holds the rooms, and if a design is coupled or twisted, &lt;strong&gt;my hands physically cross and collide in the air&lt;/strong&gt;!&lt;/li&gt;
&lt;li&gt;Even better: while aphantasia has protected me all my life from bad &lt;em&gt;visual&lt;/em&gt; flashbacks (replaying the noisy 4K video of a bad event), &lt;strong&gt;I still have "kinesthetic flashbacks"&lt;/strong&gt;! In my head, a scar is literally: &lt;strong&gt;&lt;em&gt;"It's flowing this way... wait... danger ahead"&lt;/em&gt;&lt;/strong&gt;—like hearing &lt;strong&gt;the sound of a waterfall or rapids ahead&lt;/strong&gt; three bends upstream before you can even see the drop! Because my brain never stored the surface visual scenery of a 3 AM outage in 1992 (or even of a war story I &lt;em&gt;only read about&lt;/em&gt; and simulated in motion!), it only stored the &lt;strong&gt;kinesthetic feeling of the current speeding up toward the falls&lt;/strong&gt;! That means when I touch a piece of Dart code in 2026 that has the exact same structural current as a C or Perl bug from 30 years ago, the &lt;strong&gt;kinesthetic flashback&lt;/strong&gt; fires immediately across languages!&lt;/li&gt;
&lt;li&gt;And think about what a &lt;strong&gt;4-Vector Synthetic Scar&lt;/strong&gt; actually is: because a text-only LLM is &lt;em&gt;also&lt;/em&gt; natively aphantasic, a Synthetic Scar (&lt;code&gt;The Trap: "It's flowing this way..."&lt;/code&gt; → &lt;code&gt;The Circuit Breaker: "...wait, hear the rapids..."&lt;/code&gt; → &lt;code&gt;The Wound: "...danger ahead!"&lt;/code&gt; → &lt;code&gt;The Permanent Reflex: "...steer here"&lt;/code&gt;) is literally a &lt;strong&gt;codified Kinesthetic Flashback for an AI&lt;/strong&gt;—letting any agent or developer hear the sound of the rapids ahead for 606 waterfalls without having to go over the falls themselves!&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  3. The Mock Reader VM, OSCON 2002, and the 3-Class Stonehenge Apprenticeship
&lt;/h2&gt;

&lt;p&gt;When I paused and realized how rarely we stop to &lt;em&gt;think about thinking&lt;/em&gt;, I noticed where I actually practice &lt;code&gt;Be -&amp;gt; Do -&amp;gt; Have&lt;/code&gt; (&lt;code&gt;Why -&amp;gt; How -&amp;gt; What&lt;/code&gt;) every day (&lt;code&gt;Theorem 348.j&lt;/code&gt;):&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"I know I do it a lot when I'm preparing tutorials, because I have to mock the reader's POV to understand the impact of each statement... For decades, it's been clear to me that every talk, chapter, or video is taking people from point A to point B. The closer I mimic point A to where they already are, and the closer I mimic point B to where they want to end up, the better the reception of the material. It's always about 'what shift am I making'."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3&gt;
  
  
  Spinning Up a Mock Reader VM at Point &lt;code&gt;A&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;Think about why bad tutorials, bad API docs, and bad LLM subagent prompts fail: the author writes straight out of their own head (where the finished &lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt; already lives), forgetting that the reader or fresh subagent starts at &lt;strong&gt;Point &lt;code&gt;A&lt;/code&gt;&lt;/strong&gt;! Back in 2002, Tom Phoenix and I pitched a talk for OSCON called &lt;strong&gt;&lt;em&gt;"Teaching 'Learning Perl'"&lt;/em&gt;&lt;/strong&gt; (&lt;em&gt;"our first PowerPoint presentation—we hope it's our last!"&lt;/em&gt;), where every bullet point on those slides was fought for with classroom sweat:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;em&gt;"Know where they start / Know where they want to end up / Some of this you won't know until they show up"&lt;/em&gt;&lt;/strong&gt; — and &lt;strong&gt;&lt;em&gt;"Be sure they want to be there and not somewhere else (If Cleveland is not your destination today...)"&lt;/em&gt;&lt;/strong&gt; (= matching Point &lt;code&gt;A&lt;/code&gt; and Point &lt;code&gt;B&lt;/code&gt;, and running &lt;code&gt;Target 15&lt;/code&gt; live archaeology + counter-offer before taking off!).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;em&gt;"When you don't know, you don't know"&lt;/em&gt;&lt;/strong&gt; — and &lt;strong&gt;&lt;em&gt;"If you think they can't already see how nervous or lost you are, you're mistaken"&lt;/em&gt;&lt;/strong&gt; (= Belnap &lt;code&gt;UNKNOWN&lt;/code&gt; honesty vs. "reading the lines"!).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;em&gt;"Determine how much to cover — Most important rule: LEAVE IT OUT"&lt;/em&gt;&lt;/strong&gt; (= &lt;code&gt;Make-Fork&lt;/code&gt; context pruning so working memory never overflows!).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;em&gt;"One item per bullet: Never introduce more than one thing (Unless you're making a joke / And always change your oil every 3000 miles!)"&lt;/em&gt;&lt;/strong&gt; — plus &lt;strong&gt;&lt;em&gt;"Clear your head before you begin"&lt;/em&gt;&lt;/strong&gt; and &lt;strong&gt;&lt;em&gt;"Wait for people to absorb what you just said"&lt;/em&gt;&lt;/strong&gt; (= single-stepping one state transition at a time from a Null State!).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;em&gt;"Face the audience / Don't read the bullets word for word"&lt;/em&gt;&lt;/strong&gt; (&lt;code&gt;Slide 12&lt;/code&gt;) — which, if you only read the static PDF (&lt;code&gt;Have&lt;/code&gt;), looks like two plain bullet points! What the static slide &lt;em&gt;doesn't&lt;/em&gt; show (&lt;code&gt;Do&lt;/code&gt; / &lt;code&gt;Be&lt;/code&gt;, &lt;code&gt;Theorem 348.g&lt;/code&gt;) is that when Slide 12 came up at OSCON, Tom and I turned our backs to the audience, pointed at the projector screen, and recited &lt;strong&gt;&lt;em&gt;"Don't... read... the... bullets... word... for... word"&lt;/em&gt;&lt;/strong&gt; together in a robotic, deadpan unison voice—acting out a live &lt;code&gt;tdd-red&lt;/code&gt; negative witness of &lt;em&gt;"reading the lines"&lt;/em&gt; (&lt;code&gt;Theorem 338.8n&lt;/code&gt;) so the whole room laughed (&lt;code&gt;Theorem 338.8s&lt;/code&gt;) and never forgot it!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;em&gt;"The audience will forgive a presentation that is informative and not funny, but not the other way around"&lt;/em&gt;&lt;/strong&gt; — and on the final slide, &lt;strong&gt;&lt;em&gt;"Always leave the audience wanting more!"&lt;/em&gt;&lt;/strong&gt; above photos of &lt;strong&gt;Dudley Moore, Roger Moore, and Mary Tyler Moore&lt;/strong&gt;!&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When you spin up a &lt;strong&gt;Mock Reader VM&lt;/strong&gt; in your head initialized to &lt;strong&gt;Point &lt;code&gt;A&lt;/code&gt;&lt;/strong&gt; (where they actually are right now), aim at &lt;strong&gt;Point &lt;code&gt;B&lt;/code&gt;&lt;/strong&gt; (where they actually want to end up), leave out everything that doesn't serve that shift, and &lt;strong&gt;single-step every statement (&lt;code&gt;A -&amp;gt; B&lt;/code&gt;)&lt;/strong&gt; through that Mock Reader's POV, every sentence lands—whether you are teaching Perl in a classroom in 2002 or handing a ticket to a clean-room AI subagent in 2026!&lt;/p&gt;

&lt;h3&gt;
  
  
  The 3-Class Stonehenge Apprenticeship
&lt;/h3&gt;

&lt;p&gt;And how did we transfer that unspoken classroom craft (&lt;code&gt;Be&lt;/code&gt; and &lt;code&gt;Do&lt;/code&gt;, &lt;code&gt;Why&lt;/code&gt; and &lt;code&gt;How&lt;/code&gt;) to new instructors at Stonehenge when a printed 140-page course binder (&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;) wasn't enough (&lt;code&gt;Theorem 348.k&lt;/code&gt;)?&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;"The majority of Stonehenge training was led by people who had apprenticed directly under me. We'd pay for a new instructor to just &lt;strong&gt;watch&lt;/strong&gt; the entire week, then &lt;strong&gt;deliver 50% of the material&lt;/strong&gt; with nightly debriefs, then &lt;strong&gt;deliver the entire thing&lt;/strong&gt; with me watching. Three classes before they were sent on their own. And as a conclusion, the first time we got a customer request with 'any Stonehenge trainer will do', I knew that the right signal had been sent."&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Look at that &lt;strong&gt;3-Class Stonehenge Apprenticeship&lt;/strong&gt;—because it is the exact blueprint for how we onboarded our AI agents in &lt;strong&gt;Synthetic Scars&lt;/strong&gt;:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Class 1 (&lt;em&gt;Watch the Entire Week&lt;/em&gt; — &lt;code&gt;0% Delivery / 100% Observation&lt;/code&gt;)&lt;/strong&gt;: Install the &lt;strong&gt;&lt;code&gt;Be&lt;/code&gt; (&lt;code&gt;Why&lt;/code&gt;)&lt;/strong&gt; first by watching where the master pauses and where the room's eyes glaze over (= mining git ancestry &amp;amp; rapid-regret commits before touching code).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Class 2 (&lt;em&gt;Deliver 50% with Nightly Debriefs&lt;/em&gt;)&lt;/strong&gt;: Share the load so care never runs out (&lt;code&gt;Theorem 338.8o&lt;/code&gt;), and run &lt;strong&gt;nightly debriefs&lt;/strong&gt; every single evening while the day's stumbles are still hot in memory (= co-driving tickets with Socratic nudges and running &lt;strong&gt;&lt;code&gt;Target 90&lt;/code&gt; post-mortem debriefs&lt;/strong&gt; to burn new scars into &lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt; before tomorrow morning!).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Class 3 (&lt;em&gt;Deliver 100% with the Master Watching&lt;/em&gt;)&lt;/strong&gt;: Deliver the whole week solo while I sat in the back row as the safety net (= our &lt;strong&gt;Zero-Nudge (&lt;code&gt;N_nudge = 0&lt;/code&gt;) tickets&lt;/strong&gt;, where the agent drives 100% of the ticket while I watch the five &lt;code&gt;"Send These Things to Me"&lt;/code&gt; pause gates!).&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;And just like that first Fortune 500 customer who called up and said &lt;strong&gt;&lt;em&gt;"Any Stonehenge trainer will do"&lt;/em&gt;&lt;/strong&gt;—proving the magic was now in the shared apprenticeship system rather than locked inside one founder's head—once your repository has &lt;code&gt;WORKFLOW.mk&lt;/code&gt; (&lt;code&gt;Do&lt;/code&gt; / &lt;code&gt;How&lt;/code&gt;) and &lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt; (&lt;code&gt;Be&lt;/code&gt; / &lt;code&gt;Why&lt;/code&gt; from the nightly debriefs), you reach the exact same milestone with AI: &lt;strong&gt;&lt;em&gt;"Any Stonehenge-apprenticed model (&lt;code&gt;Gemini&lt;/code&gt;, &lt;code&gt;Claude&lt;/code&gt;, or local edge model) will do!"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  4. The "Magical Voice" in My Head and 15 Laws of Kinesthetic Craft
&lt;/h2&gt;

&lt;p&gt;Up until this point, our Socratic flow always ran in one direction: the AI crashed into a rake during a ticket, and I nudged it out. So I challenged the AI to flip the Socratic interview around and ask &lt;em&gt;me&lt;/em&gt; targeted boundary questions—probing how I pick candidate solutions, how I spot gaps in diagrams without mental pictures, and what happens in my head in the millisecond while I'm typing a sentence.&lt;/p&gt;

&lt;p&gt;What tumbled out across 26 theorems (&lt;code&gt;Section 348&lt;/code&gt;, &lt;code&gt;Theorems 348.l–348.z&lt;/code&gt;) was a field manual of 50 years of tacit engineering instinct—extracted cleanly without needing a ticket crash.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Lazy Satisficing, 1D Diagram Walking, and the "Magical Voice" Revelation (&lt;code&gt;Theorem 348.l&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;Three foundational mechanics surfaced immediately when the AI asked how I select ideas, inspect 2D flowcharts, and generate prose in real time:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Economy of Effort (&lt;code&gt;Lazy Satisficing&lt;/code&gt;)&lt;/strong&gt;: &lt;em&gt;"Two or three solutions that might solve this are viewed to be 'enough', unless they all lead to dead ends."&lt;/em&gt; I don't generate 20 ideas and throw away 18; my brain is a lazy iterator (&lt;code&gt;Iterable.take(3)&lt;/code&gt;) that only pulls a 4th option if the first 3 hit a wall!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;1D Walking Through 2D Diagrams&lt;/strong&gt;: &lt;em&gt;"I need to 'walk through' a flowchart or diagram before it's apparently missing something."&lt;/em&gt; Even when I look at a 2D diagram on a screen, I compile it into a 1D kinesthetic walk—stepping box-by-box until my foot steps into mid-air where an arrow is missing (which is literally what our &lt;code&gt;Target 15&lt;/code&gt; &lt;code&gt;strict digraph&lt;/code&gt; degree-checker does!).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The "Magical Voice" Revelation (Why I'm an "LLM Whisperer")&lt;/strong&gt;:&lt;/li&gt;
&lt;/ol&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"I identify the point A, and I already have a sense of what that is. I then compute the steps to B, and just start writing as fast as I can... I'm never sure what the end of any sentence is before I type it. It's like it's coming out of a magical voice in my head. It's probably why I'm good as an LLM whisperer, because I have enough meta-cognition to recognize the similarities."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Stop and think about that! Most programmers either worship LLMs as magic gods or dismiss them as "stochastic parrots" (&lt;em&gt;"Humans don't just predict the next token!"&lt;/em&gt;)—because they have never paid close enough attention to their own heads to realize that &lt;strong&gt;when we write at full speed, we don't know the end of the sentence before we type it either!&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Inside my own skull, my conscious kinesthetic planner (&lt;strong&gt;Track 1&lt;/strong&gt;: &lt;code&gt;Be -&amp;gt; Do&lt;/code&gt; / &lt;code&gt;Why -&amp;gt; How&lt;/code&gt;) locks in &lt;strong&gt;Point &lt;code&gt;A&lt;/code&gt;&lt;/strong&gt;, &lt;strong&gt;Point &lt;code&gt;B&lt;/code&gt;&lt;/strong&gt;, and the non-verbal steps between them—and then hands the keyboard to &lt;strong&gt;"the magical voice in my head" (&lt;/strong&gt;Track 2*&lt;em&gt;: my biological next-token streamer!)&lt;/em&gt;* while my kinesthetic rapids-detector listens in real time! Because I had enough meta-cognition to recognize that &lt;strong&gt;an LLM is that exact same "magical voice"&lt;/strong&gt;, I didn't fight it—I just built it the same &lt;strong&gt;Track-1 Kinesthetic Wrapper&lt;/strong&gt; (&lt;code&gt;WORKFLOW.mk&lt;/code&gt; + &lt;code&gt;Make-Fork&lt;/code&gt; + &lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt;) that keeps my own magical voice on the rails!&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Seam Cutting, Mountain Basecamps, and a Sense of Destiny (&lt;code&gt;Theorem 348.m&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I know &lt;em&gt;where to slice&lt;/em&gt; a big feature into steps—and why my "magical voice" doesn't wander into the weeds even when I'm winging a live presentation—the two halves clicked together:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;"1. The first answer is 'if it's a movement in two different directions at once'. That's part of why the workflow has a 'blast radius'... to see if they are two or more orthogonal parts that should really be processed in steps. Part 1 is also thinking about basecamps on a climb: where's the next reachable &lt;strong&gt;testable&lt;/strong&gt; deliverable? 2. Oddly, the magical voice consistently goes toward point B. Even in a live preso that I'm winging, I seem to have a sense of destiny always as part of the path."&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Never Move in Two Orthogonal Directions at Once&lt;/strong&gt;: If a change tries to move &lt;code&gt;Up&lt;/code&gt; (shifting a data model) and &lt;code&gt;Sideways&lt;/code&gt; (changing a UI flow) at the same time, the blast radius multiplies! That is why &lt;code&gt;Target 15&lt;/code&gt; maps the blast radius first—splitting diagonal jumps into clean one-direction steps.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Climb from Basecamp to Basecamp&lt;/strong&gt;: You can't pitch a tent while hanging from a cliff by your fingernails! Each step aims for the &lt;strong&gt;next reachable &lt;em&gt;testable&lt;/em&gt; deliverable&lt;/strong&gt;—a flat ledge where the code compiles, the tests pass, and you clip your carabiner into &lt;code&gt;.changes&lt;/code&gt; (or &lt;code&gt;main&lt;/code&gt;) so you can never fall back to the bottom of the mountain!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep "Destiny (&lt;code&gt;Point B&lt;/code&gt;)" Pinned in Front of the Voice&lt;/strong&gt;: In a raw LLM, the goal is written at token #1 and fades into the past as the model talks. By pinning &lt;strong&gt;Point &lt;code&gt;B&lt;/code&gt; (Destiny)&lt;/strong&gt; at the tail of every &lt;code&gt;.changes&lt;/code&gt; chunk and every clean-room subagent prompt, the AI's "magical voice" gets that exact same gravitational pull toward &lt;code&gt;Point B&lt;/code&gt;!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  3. Dead Code as Copying GC &amp;amp; "&lt;code&gt;B&lt;/code&gt; Never Existed" (&lt;code&gt;Theorem 348.n&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;Finally, the AI asked how to spot and delete dead code inside an existing project, and what happens if &lt;code&gt;Point B&lt;/code&gt; turns out to be a mirage:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1 is an unsolved problem. Dead code populates every project I've witnessed. I think the only solution is to refactor from scratch. 2 — Perhaps I've been lucky, but the point B is often defined by the title of the talk or the request from the interviewer, so it has never been a false result. There are times I've challenged an interviewer's question by disclaiming some sort of premise, but again that would mean I'm not running towards B... B never existed."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Why "Refactor from Scratch" Is a Copying Garbage Collector&lt;/strong&gt;: Hunting down semantic dead code line-by-line inside an old monolith is like reference counting on a tangled heap—it is an unsolved problem because old scaffolding still has callers and tests! The only real cure works like a &lt;strong&gt;Copying Garbage Collector (&lt;code&gt;Cheney, 1970&lt;/code&gt;)&lt;/strong&gt;: lock the Gherkin behavioral contract of what you actually need today (&lt;code&gt;A -&amp;gt; B&lt;/code&gt;), rewrite the module &lt;strong&gt;from scratch&lt;/strong&gt; into a clean room, and throw the entire old carcass in the trash!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"&lt;code&gt;B&lt;/code&gt; Never Existed"&lt;/strong&gt;: Why do unscarred LLMs waste hours building features for broken tickets? Because they lock in &lt;code&gt;Point B&lt;/code&gt; at token #1 &lt;em&gt;before&lt;/em&gt; checking the premise at &lt;code&gt;Point A&lt;/code&gt;! When you check the premise first (&lt;code&gt;Target 15&lt;/code&gt; archaeology)—just like disclaiming a flawed interviewer question on stage—if the premise is false, you don't "change your mind halfway to &lt;code&gt;B&lt;/code&gt;": &lt;strong&gt;&lt;code&gt;B&lt;/code&gt; never existed in the first place (&lt;code&gt;0 LOC&lt;/code&gt; counter-offer)!&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  4. Race Conditions as "Hand Positions with Overlap" &amp;amp; Grinder/Bandler's "Pace and Lead" (&lt;code&gt;Theorem 348.o&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I feel an asynchronous race condition without a 2D visual swimlane diagram—and how I decide when to show the &lt;em&gt;broken&lt;/em&gt; way first in a tutorial without planting a Pink Elephant—two more pieces clicked:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1. They occur to me as hand positions with overlap. 2. It's part of 'pace and lead' from Grinder/Bandler. If I need to show a broken way to do something to pace the audience, I do. But not always."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Hand Positions with Overlap&lt;/strong&gt;: On a 2D whiteboard, two arrows pointing at the same box look totally fine because ink doesn't collide! In a kinesthetic brain (just like playing keyboard!), &lt;strong&gt;two hands can't occupy the same space on the keys at the same time without jamming into each other&lt;/strong&gt;—so an unguarded &lt;code&gt;await&lt;/code&gt; gap feels like two hands physically overlapping in space!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;When to Show the Trap (&lt;code&gt;Pace and Lead&lt;/code&gt;) vs. When to Leave It Out&lt;/strong&gt;: Why do we name &lt;code&gt;The Trap&lt;/code&gt; in a 4-Vector Scar, when naming a forbidden thing can sometimes plant a Pink Elephant? Because of &lt;strong&gt;Grinder &amp;amp; Bandler's "Pace and Lead"&lt;/strong&gt;: if the student (or the LLM's pre-training weights!) is &lt;strong&gt;already reaching for the broken way at &lt;code&gt;Point A&lt;/code&gt;&lt;/strong&gt;, you &lt;em&gt;must&lt;/em&gt; name it first to &lt;strong&gt;pace&lt;/strong&gt; where their head already is before you can &lt;strong&gt;lead&lt;/strong&gt; them to &lt;code&gt;Point B&lt;/code&gt;! If they &lt;em&gt;weren't&lt;/em&gt; going to think of that broken way on their own, &lt;strong&gt;leave it out&lt;/strong&gt; so you don't put a bad idea in their head!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  5. War-Room Motion Questions &amp;amp; The Dual API Litmus Test (&lt;code&gt;Theorem 348.p&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I cut through war-room panic when debugging a mystery outage, and how I tell whether a new API design is clean or a trap waiting to spring:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1. Similar to what I'm doing in the archaeology part of the workflow: 'have you seen this before' and 'what did you change'... and item 1 is about 'feeling the motion' of the system again. 2. I think about how I would explain this to a new user. And also, if I needed to add more things, how fragile is it?"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;"Feeling the Motion" of the System Again&lt;/strong&gt;: Why do people get stuck staring at a stack trace in a war room? Because a crash dump is a &lt;strong&gt;frozen photograph (&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;)&lt;/strong&gt;, and code is always in motion! Asking &lt;strong&gt;"Have you seen this before?"&lt;/strong&gt; (has the system's rhythm wobbled like this before?) and &lt;strong&gt;"What did you change?"&lt;/strong&gt; (what commit, dependency, or config impulse pushed the moving system off course?) puts your hands right back on &lt;strong&gt;the motion of the system&lt;/strong&gt; in &lt;code&gt;Target 15&lt;/code&gt; (&lt;code&gt;archaeology&lt;/code&gt;)!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The Two-Sentence API Litmus Test&lt;/strong&gt;: How do you know if an API is good before you ship it? First: &lt;strong&gt;"How would I explain this to a new user?"&lt;/strong&gt; (if you have to apologize or explain three gotchas just to get them from &lt;code&gt;Point A&lt;/code&gt; to &lt;code&gt;Point B&lt;/code&gt;, the bug is in the API, not the docs!). Second: &lt;strong&gt;"If I needed to add more things, how fragile is it?"&lt;/strong&gt; (if adding one more option next month breaks every caller in the repo, fix the seam now!).&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  6. Preserving the Trajectory &amp;amp; "Three Concrete Before Abstract" (&lt;code&gt;Theorem 348.q&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked what makes a great error message and how to avoid over-abstracting too early, the answer came down to &lt;strong&gt;preserving the trajectory&lt;/strong&gt; and &lt;strong&gt;separating Wire APIs from Class Hierarchies&lt;/strong&gt;:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1. It's not the error message in particular. It's that I know what happened to get there. Watch &lt;a href="https://www.youtube.com/watch?v=b7NAW9jZ3Qk" rel="noopener noreferrer"&gt;https://www.youtube.com/watch?v=b7NAW9jZ3Qk&lt;/a&gt; for details. 2. APIs on a wire have a different space than APIs in an app class hierarchy. APIs on a wire should always permit 'more parameters later' or at least a versioned update. APIs in a class hierarchy need my 'three concrete before abstract' rule."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Preserve How We Got Here (&lt;code&gt;SCAR-ERR-01..03&lt;/code&gt;)&lt;/strong&gt;: An LLM loves catching an exception and throwing a brand-new &lt;code&gt;Exception("Something failed")&lt;/code&gt;—which wipes out the stack trace! I don't care about a poetic error string (&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;); I care about &lt;strong&gt;knowing what happened to get there (&lt;code&gt;Be -&amp;gt; Do&lt;/code&gt; / &lt;code&gt;Why -&amp;gt; How&lt;/code&gt;)&lt;/strong&gt;: never catch &lt;code&gt;Error&lt;/code&gt; (&lt;code&gt;on Exception catch&lt;/code&gt; only, so programmer bugs fail fast right where they broke!), use &lt;code&gt;rethrow&lt;/code&gt;, and use &lt;code&gt;Error.throwWithStackTrace&lt;/code&gt; when repackaging across layers so you never erase the trail!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Wire APIs (&lt;code&gt;N = 1&lt;/code&gt;) vs. Class Hierarchies ("Three Concrete Before Abstract", &lt;code&gt;N &amp;gt;= 3&lt;/code&gt;)&lt;/strong&gt;: Unscarred LLMs get extensibility backwards—they ship rigid wire payloads that break when you add a field, while wrapping a &lt;em&gt;single&lt;/em&gt; internal class in an &lt;code&gt;AbstractStrategyFactory&lt;/code&gt; on Day 1! &lt;strong&gt;APIs on a wire&lt;/strong&gt; (network, IPC, disk) live in a space where you can't refactor all callers at once, so they must allow "more parameters later" or a version bump on &lt;strong&gt;Day 1 (&lt;code&gt;N = 1&lt;/code&gt;)&lt;/strong&gt;. &lt;strong&gt;APIs in an app class hierarchy&lt;/strong&gt; live inside your own git tree—never invent an abstract base class until you have built &lt;strong&gt;three concrete ones first (&lt;code&gt;N &amp;gt;= 3&lt;/code&gt;)&lt;/strong&gt; and can actually see what they share!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  7. State Ownership by Death (&lt;code&gt;dispose&lt;/code&gt;) &amp;amp; Red/Green TDD (&lt;code&gt;Theorem 348.r&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I decide which entity should own a piece of state and how to avoid writing useless unit tests:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1. The ultimate test is 'who can know when this value can be released/disposed'. That entity should own the data, and merely expose it to other consumers... It's part of having coded BlocSignal, and really understanding disposal cycles. 2. That's why we have red/green TDD. If a test isn't testing a new line of code, it's not very useful."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;State Ownership Is Decided by Death (&lt;code&gt;dispose&lt;/code&gt;), Not Birth (&lt;code&gt;BlocSignal&lt;/code&gt; Disposal Cycles)&lt;/strong&gt;: People argue endlessly about which widget or service should own a piece of state because they look at &lt;em&gt;who creates or reads it first&lt;/em&gt;. Having built &lt;strong&gt;&lt;code&gt;BlocSignal&lt;/code&gt;&lt;/strong&gt; and lived inside reactive disposal cycles, the ultimate test is crystal clear: &lt;strong&gt;"Who can know when this value can be released/disposed?"&lt;/strong&gt; That single entity owns the data (and its teardown!), and merely exposes it to every other consumer!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;If a Test Isn't Testing a New Line of Code, It's Not Very Useful&lt;/strong&gt;: Why do developers end up with 500 brittle tests that don't catch bugs? Because they write the code first and then pad tests afterward! In &lt;strong&gt;Red/Green TDD (&lt;code&gt;Target 30&lt;/code&gt; → &lt;code&gt;Target 35&lt;/code&gt;)&lt;/strong&gt;, every test starts Red and forces you to write a &lt;strong&gt;new line of production code&lt;/strong&gt; to turn it Green—so you never write a test that doesn't test a new line of code, and you never write a line of code without a test!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  8. Optimize "When You Must" &amp;amp; Comments Are Strictly for &lt;code&gt;Why&lt;/code&gt;, Never &lt;code&gt;What&lt;/code&gt; (&lt;code&gt;Theorem 348.s&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked when to optimize performance and what belongs in a code comment:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1. Do it when you must. :) Most code is already 'fast enough' if you apply common sense. 2. Comments should only be 'why' not 'what'."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Do It When You Must&lt;/strong&gt;: With common-sense algorithms, most code is already fast enough! Don't trade away low-care readability (&lt;code&gt;Theorem 338.8o&lt;/code&gt;) for clever micro-optimizations unless reality proves you &lt;em&gt;must&lt;/em&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Comments Are for &lt;code&gt;Why&lt;/code&gt; (&lt;code&gt;Be&lt;/code&gt;), Never &lt;code&gt;What&lt;/code&gt; (&lt;code&gt;Have&lt;/code&gt;)&lt;/strong&gt;: Look at the &lt;code&gt;Why / How / What&lt;/code&gt; triad again! The code itself already says &lt;em&gt;what&lt;/em&gt; (&lt;code&gt;Have&lt;/code&gt;) it is doing—so a comment that repeats &lt;em&gt;what&lt;/em&gt; the next line does is just waiting to become a lie! If the &lt;em&gt;what&lt;/em&gt; isn't clear, fix the variable or function name; save comments strictly for &lt;strong&gt;why&lt;/strong&gt; (&lt;code&gt;Be&lt;/code&gt; / &lt;code&gt;Context&lt;/code&gt;: the non-obvious constraint or the trap you avoided!).&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  9. "Born Ready" Data, Getter/Setter Trapdoors, &amp;amp; Proactive Scar Extraction (&lt;code&gt;Theorem 348.t&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I avoid defensive &lt;code&gt;null&lt;/code&gt;-check soup and how I catch a value that is mutating behind my back when reading the code doesn't show the culprit:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1 - I have a personal rule that every data should be 'born ready', which eliminates the need for nulls. Not always possible, but more possible than typical. 2. Good question! I think I'd resort to single-stepping, or replacing the object with an object that detects getters and setters... You realize what you are doing is extracting Randal Engrams without needing a ticket flow."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Every Data Should Be "Born Ready"&lt;/strong&gt;: Why do codebases fill up with &lt;code&gt;foo?.bar ?? ...&lt;/code&gt; and null-pointer crashes? Because people instantiate half-baked objects in &lt;code&gt;Have&lt;/code&gt; (&lt;code&gt;What&lt;/code&gt;) &lt;em&gt;before&lt;/em&gt; their &lt;code&gt;Be&lt;/code&gt; (&lt;code&gt;Why&lt;/code&gt;) data is ready! Wait until you actually have the inputs before constructing the object (or use distinct sealed state classes for each phase), and your data is &lt;strong&gt;born ready&lt;/strong&gt;—eliminating &lt;code&gt;null&lt;/code&gt;s at birth!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Turn the Object Into a Getter/Setter Tripwire&lt;/strong&gt;: When a field changes behind your back and reading the code doesn't tell you who touched it, stop guessing! Either single-step the trajectory (&lt;code&gt;Theorem 348.c&lt;/code&gt;) or &lt;strong&gt;swap the object for a proxy wrapper that traps on getters and setters&lt;/strong&gt;—so the culprit hands you its own stack trace the microsecond it touches the data!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Proactive Scar Extraction Without Waiting for a Ticket Crash&lt;/strong&gt;: Up until now, we waited for an agent to run a ticket, step on a rake, and compile the scar in &lt;code&gt;Target 90&lt;/code&gt;. By flipping the Socratic method around and asking targeted boundary questions, the AI is &lt;strong&gt;extracting 50 years of battle-earned senior scars directly into the workflow—without needing a ticket flow at all!&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  10. Positional Parameters Fade After 2 Items &amp;amp; Cache Invalidation (&lt;code&gt;Theorem 348.u&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I keep function call sites from turning into unreadable boolean/positional traps and what my #1 rule is whenever someone introduces a cache:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1. In Dart, positional parameters fade after 2 items. Strong recommendation to name them at that point. 2. The most important thing to ask about a cache is 'when will it become invalid'. And to make sure to capture that path properly."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Positional Parameters Fade After 2 Items (&lt;code&gt;N &amp;lt;= 2&lt;/code&gt;)&lt;/strong&gt;: Two positional arguments map naturally to left hand / right hand (&lt;code&gt;key, value&lt;/code&gt; or &lt;code&gt;from, to&lt;/code&gt;). After 2 items, positional parameters fade into a guessing game! In Dart, strongly prefer &lt;strong&gt;named parameters (&lt;code&gt;{required ...}&lt;/code&gt;)&lt;/strong&gt; once you pass 2 items so call sites read like English and cannot be wired up backward.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The #1 Cache Question: "When Will It Become Invalid?"&lt;/strong&gt;: Notice the exact parallel to state ownership (&lt;code&gt;Theorem 348.r&lt;/code&gt;)! Just as state ownership is decided by &lt;em&gt;when a value can be disposed&lt;/em&gt;, a cache is defined by &lt;strong&gt;when it becomes invalid&lt;/strong&gt;! Anyone can write &lt;code&gt;cache ??= compute()&lt;/code&gt;; a senior engineer refuses to approve a cache until the &lt;strong&gt;invalidation path&lt;/strong&gt; is completely captured and tested!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  11. The Visceral Honesty Filter (&lt;code&gt;Theorem 348.v&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;And then, on Question 22, the AI asked me two questions where I &lt;em&gt;didn't&lt;/em&gt; have a battle-scarred gut reflex—and look at what happened:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"You've stumped me at this point! I don't have enough visceral knowledge to answer either of those!"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Why That Answer Proves the Whole Method&lt;/strong&gt;: Ask an LLM a question where it has no real experience, and it will happily hallucinate 500 words of textbook-sounding mush (&lt;code&gt;Have&lt;/code&gt; with zero &lt;code&gt;Be&lt;/code&gt;)! By enforcing my 2002 OSCON rule—&lt;strong&gt;"When you don't know, you don't know"&lt;/strong&gt;—we proved that the first 21 rounds weren't generic platitudes made up on the spot. Every single scar we compiled had to clear the &lt;strong&gt;visceral threshold&lt;/strong&gt; (backed by a real kinesthetic flashback), or we don't let it into the registry!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  12. "I Feel the Dataflow" &amp;amp; Testable Commits (&lt;code&gt;Theorem 348.w&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI pivoted back to my wheelhouse and asked how I turn nested imperative loop soup into clean pipelines and what defines a single Git commit:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1 - Again, it's about flow. I feel the dataflow. 2. A commit should be a testable phase. It should move us from a testable state to a new testable state."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;I Feel the Dataflow&lt;/strong&gt;: Why did I invent the &lt;strong&gt;Schwartzian Transform&lt;/strong&gt; in Perl (&lt;code&gt;map { ... } sort { ... } map { ... }&lt;/code&gt;), love Smalltalk collection cascades (&lt;code&gt;select:&lt;/code&gt;, &lt;code&gt;collect:&lt;/code&gt;), and build &lt;code&gt;BlocSignal&lt;/code&gt;? Because I &lt;strong&gt;feel the dataflow&lt;/strong&gt;! A 60-line &lt;code&gt;for&lt;/code&gt;/&lt;code&gt;if&lt;/code&gt; loop mutating three variables outside the loop feels like turbulent backwash; a pipeline of small steps (&lt;code&gt;where&lt;/code&gt; → &lt;code&gt;map&lt;/code&gt; → &lt;code&gt;toList&lt;/code&gt;) is smooth laminar flow where every stage outputs "born ready" data (&lt;code&gt;Theorem 348.t&lt;/code&gt;) that you can single-step (&lt;code&gt;Theorem 348.c&lt;/code&gt;)!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A Commit Moves from a Testable State to a New Testable State&lt;/strong&gt;: Notice how &lt;strong&gt;Point A → Point B&lt;/strong&gt; (&lt;code&gt;Theorem 348.j&lt;/code&gt;) and &lt;strong&gt;Mountaineering Basecamps&lt;/strong&gt; (&lt;code&gt;Theorem 348.m&lt;/code&gt;) show up again at the Git commit level! Never commit half-broken "WIP" checkpoints; every single commit must be a &lt;strong&gt;testable phase&lt;/strong&gt; that takes the repo from a green testable state to a new green testable state!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  13. Action Density (Regex vs. Parser) &amp;amp; The Socratic XY Nudge (&lt;code&gt;Theorem 348.x&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked where even a regex master stops using a regex and how I unstick a developer trapped in an XY Problem:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1 - While being a regex master, note also that I invented Spew based on Parse::RecDescent, and a JSON parser in Perl5 regex... I wanted to add to the previous answer, my Parse::RecDescent 'data undumper'. At some point, if you have a lot of actions triggered by matches, you need something stronger. 2 - It's all about the socratic nudge... 'really? you're trying solve Y? why?'"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Action Density Is Where Regexes Give Way to Parsers (From Perl 5 Regex JSON to &lt;code&gt;Spew&lt;/code&gt; and the &lt;code&gt;Parse::RecDescent&lt;/code&gt; "Data Undumper")&lt;/strong&gt;: People think the boundary between a regex and a parser is whether the syntax is recursive—heck, I wrote a complete &lt;strong&gt;JSON parser in a single Perl 5 regex&lt;/strong&gt;, and I also built &lt;strong&gt;&lt;code&gt;Spew&lt;/code&gt;&lt;/strong&gt; and a &lt;strong&gt;&lt;code&gt;Parse::RecDescent&lt;/code&gt; "data undumper"&lt;/strong&gt; (to safely rehydrate &lt;code&gt;Data::Dumper&lt;/code&gt; output without ever running &lt;code&gt;eval&lt;/code&gt; on untrusted strings!). The real boundary isn't syntax recognition; it's &lt;strong&gt;how many actions are triggered by matches&lt;/strong&gt;! Once you have a lot of distinct actions firing on sub-matches (like constructing hashes, arrays, blessed references, and symbol-table links in the Data Undumper), switch to a real grammar parser (&lt;code&gt;Parse::RecDescent&lt;/code&gt;, &lt;code&gt;petitparser&lt;/code&gt;, or a state transducer) where each rule owns its action cleanly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"Really? You're Trying to Solve Y? Why?"&lt;/strong&gt;: When someone is stuck trying to hammer Y (&lt;code&gt;Do&lt;/code&gt;/&lt;code&gt;Have&lt;/code&gt;, &lt;code&gt;How&lt;/code&gt;/&lt;code&gt;What&lt;/code&gt;), telling them &lt;em&gt;"Don't do Y"&lt;/em&gt; makes them defensive. Asking &lt;strong&gt;"Really? You're trying to solve Y? Why?"&lt;/strong&gt; pops their stack one level up to &lt;code&gt;Be&lt;/code&gt; / &lt;code&gt;Why&lt;/code&gt; (their actual goal X!)—and the moment they say X out loud, they see for themselves that Y was the wrong road!&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  14. Package Scope (&lt;code&gt;Point A&lt;/code&gt;) &amp;amp; Live Demo Crashes (&lt;code&gt;Theorem 348.y&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;When the AI asked how I guard open-source packages like &lt;code&gt;BlocSignal&lt;/code&gt; against feature creep and what I do when something breaks live on stage:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1 - Again, it's about context. A library/package is solving a stated problem (the point A of the A -&amp;gt; B story). And it's important to reject mutations that aren't about A. 2. Laugh. And get them to laugh... For a laugh, I'll occasionally rely on the line from Ghostbusters: 'you don't normally see that behavior in a major appliance'."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Reject Mutations That Aren't About &lt;code&gt;Point A&lt;/code&gt;&lt;/strong&gt;: Look at how &lt;strong&gt;Point A → Point B&lt;/strong&gt; (&lt;code&gt;Theorem 348.j&lt;/code&gt;) governs open-source architecture! Every library or package exists to solve a stated problem (&lt;code&gt;Point A&lt;/code&gt;). Whenever someone proposes a mutation or feature flag that isn't about &lt;code&gt;Point A&lt;/code&gt;, &lt;strong&gt;reject it&lt;/strong&gt; (or put it in its own package with its own &lt;code&gt;Point A&lt;/code&gt;)!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"Laugh. And Get Them to Laugh." (&lt;em&gt;"You Don't Normally See That Behavior in a Major Appliance"&lt;/em&gt;)&lt;/strong&gt;: What is laughter when a live demo blows up on stage? It's the human &lt;strong&gt;Null-State Reset (&lt;code&gt;Theorem 338.8p&lt;/code&gt;)&lt;/strong&gt;! Panic locks up your brain and makes the audience tense; dropping Bill Murray's deadpan line from &lt;em&gt;Ghostbusters&lt;/em&gt;—&lt;strong&gt;"You don't normally see that behavior in a major appliance"&lt;/strong&gt;—and getting the room to laugh with you instantly steps outside the crash (&lt;code&gt;Have&lt;/code&gt;) and resets the shared Context (&lt;code&gt;Be&lt;/code&gt;) from &lt;em&gt;"disaster"&lt;/em&gt; to &lt;em&gt;"hey, let's have fun watching how we fix this!"&lt;/em&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  15. Action-Honest Naming in &lt;code&gt;Do&lt;/code&gt; &amp;amp; The 50-Year Invariant (&lt;code&gt;Theorem 348.z&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;Finally, to close the 26-part alphabet of &lt;code&gt;Section 348&lt;/code&gt; (&lt;code&gt;a&lt;/code&gt; through &lt;code&gt;z&lt;/code&gt;), the AI asked what makes a word in code feel wrong to me, and what one thing about software craft hasn't changed across 50 years (from 1970s assembly, Smalltalk, and Perl to Dart, Flutter, and AI agents):&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"1 - I'm trying to remember times triggered by that, and can't come up with obvious examples, so it's not a frequent thing. However, it's the wrong word if it doesn't capture the proper action, so it seems to be about focusing on 'do'. 2 - I think being able to translate my thoughts into actions. The responsive fabric must be complete and understandable."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A Word Is Wrong When It Lies About the Action (&lt;code&gt;Do&lt;/code&gt; / &lt;code&gt;How&lt;/code&gt;)&lt;/strong&gt;: Because code is always in motion (&lt;code&gt;Theorem 348.i&lt;/code&gt;), a name is the wrong word whenever it fails to capture the &lt;strong&gt;proper action (&lt;code&gt;Do&lt;/code&gt;)&lt;/strong&gt;—like a &lt;code&gt;get...&lt;/code&gt; method that secretly mutates state or a &lt;code&gt;validate...&lt;/code&gt; method that silently rewrites data!&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The 50-Year Invariant ("The Responsive Fabric Must Be Complete and Understandable")&lt;/strong&gt;: From Smalltalk-80 and Perl to Flutter, &lt;code&gt;BlocSignal&lt;/code&gt;, and now Synthetic Scars, the goal has never changed: &lt;strong&gt;translating thoughts (&lt;code&gt;Be&lt;/code&gt; / &lt;code&gt;Why&lt;/code&gt;) into actions (&lt;code&gt;Do -&amp;gt; Have&lt;/code&gt; / &lt;code&gt;How -&amp;gt; What&lt;/code&gt;) through a responsive fabric that is both &lt;em&gt;complete&lt;/em&gt; and &lt;em&gt;understandable&lt;/em&gt;!&lt;/strong&gt; Raw "vibe coding" fails because an unscarred LLM is an &lt;em&gt;un-understandable&lt;/em&gt; fabric that drops promises and mutates state behind your back. Wrapping the LLM in &lt;code&gt;WORKFLOW.mk&lt;/code&gt;, Smalltalk &lt;code&gt;.changes&lt;/code&gt;, and 612 Synthetic Scars makes the AI &lt;strong&gt;complete and understandable&lt;/strong&gt;!&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  5. The Two-Track Transformer: A Contextual Next-Token Rule
&lt;/h2&gt;

&lt;p&gt;Look at how the entire &lt;strong&gt;Synthetic Scars&lt;/strong&gt; framework—every tool, every file, every target—falls into a single 3-row table the moment you split it by &lt;strong&gt;&lt;code&gt;Be / Do / Have&lt;/code&gt; (&lt;code&gt;Context / Process / Content&lt;/code&gt; = &lt;code&gt;Why / How / What&lt;/code&gt;)&lt;/strong&gt;:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Layer&lt;/th&gt;
&lt;th&gt;Role in Craft&lt;/th&gt;
&lt;th&gt;What Standard "Vibe Coding" Does (&lt;code&gt;Have -&amp;gt; Have&lt;/code&gt; / &lt;code&gt;What -&amp;gt; What&lt;/code&gt;)&lt;/th&gt;
&lt;th&gt;What Synthetic Scars Builds (&lt;code&gt;Be -&amp;gt; Do -&amp;gt; Have&lt;/code&gt; / &lt;code&gt;Why -&amp;gt; How -&amp;gt; What&lt;/code&gt;)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;&lt;code&gt;Be&lt;/code&gt;&lt;/strong&gt;&lt;br&gt;&lt;em&gt;(&lt;code&gt;Context&lt;/code&gt; / &lt;code&gt;Why&lt;/code&gt;)&lt;/em&gt;
&lt;/td&gt;
&lt;td&gt;&lt;em&gt;Who the agent is, what stance it holds, and what history and cautions bound its world before it acts&lt;/em&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Empty or Polluted&lt;/strong&gt;: A single 150k-token chat window full of stale errors, sycophantic priors (&lt;code&gt;P(code is sacred) = 0.99&lt;/code&gt;), and a flat snapshot of &lt;code&gt;HEAD&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;1. &lt;code&gt;Make-Fork&lt;/code&gt; Clean Rooms&lt;/strong&gt; (fresh role identity: Archaeologist vs. Builder vs. Critic)&lt;br&gt;&lt;strong&gt;2. &lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt;&lt;/strong&gt; (phase-bound 4-Vector cautions)&lt;br&gt;&lt;strong&gt;3. &lt;code&gt;Target 15&lt;/code&gt; Ancestry &amp;amp; &lt;code&gt;pubspec.yaml&lt;/code&gt;&lt;/strong&gt; (historical &lt;code&gt;Be&lt;/code&gt; + Good/Bad/Ugly map)&lt;br&gt;&lt;strong&gt;4. &lt;code&gt;baseline.sources&lt;/code&gt; + &lt;code&gt;.changes&lt;/code&gt;&lt;/strong&gt; (&lt;code&gt;thisContext&lt;/code&gt; memory across compaction)&lt;br&gt;&lt;strong&gt;5. Null-State Reset&lt;/strong&gt; (dropping a rut-locked &lt;code&gt;Be&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;&lt;code&gt;Do&lt;/code&gt;&lt;/strong&gt;&lt;br&gt;&lt;em&gt;(&lt;code&gt;Process&lt;/code&gt; / &lt;code&gt;How&lt;/code&gt;)&lt;/em&gt;
&lt;/td&gt;
&lt;td&gt;&lt;em&gt;How the agent probes reality, climbs ladder rungs, and verifies transitions&lt;/em&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Ad-Hoc Guessing&lt;/strong&gt;: Guessing function edits in a loop, running happy-path tests, "reading the lines" in self-review&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;1. &lt;code&gt;WORKFLOW.mk&lt;/code&gt; Backward-Chaining DAG&lt;/strong&gt; (&lt;code&gt;make finish&lt;/code&gt;)&lt;br&gt;&lt;strong&gt;2. &lt;code&gt;Target 30&lt;/code&gt; Setup-and-Punch &lt;code&gt;tdd-red&lt;/code&gt;&lt;/strong&gt; + &lt;code&gt;"Too Quiet"&lt;/code&gt; ambush check&lt;br&gt;&lt;strong&gt;3. &lt;code&gt;Target 35&lt;/code&gt; Data-Lineage Single-Stepping&lt;/strong&gt; + Ladder-Rung checks + &lt;code&gt;generalize()&lt;/code&gt; sweep&lt;br&gt;&lt;strong&gt;4. &lt;code&gt;"1, 2, 3, 4 ... W?"&lt;/code&gt; Sideways Blast&lt;/strong&gt;&lt;br&gt;&lt;strong&gt;5. &lt;code&gt;"Send These Things to Me"&lt;/code&gt; Pause Gates&lt;/strong&gt; (&lt;code&gt;Targets 20, 45, 50, 60, 75&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;strong&gt;&lt;code&gt;Have&lt;/code&gt;&lt;/strong&gt;&lt;br&gt;&lt;em&gt;(&lt;code&gt;Content&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;)&lt;/em&gt;
&lt;/td&gt;
&lt;td&gt;&lt;em&gt;The resulting code diff, green tests, Six-Pillar review, and merged PR&lt;/em&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Direct Gambling&lt;/strong&gt;: Trying to prompt the finished cathedral into existence on the first try&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;The Inevitable Byproduct&lt;/strong&gt;: Clean, low-care code where &lt;code&gt;Ticket 1&lt;/code&gt; shifts the foundation without moving the rooms and unrelated diff hunks are zero&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Right now, the AI industry is spending hundreds of billions of dollars trying to breed a &lt;strong&gt;10-trillion-parameter moth&lt;/strong&gt;—convinced that if the prisoner reads twice as many books inside the cell, it will finally stop flying into the porch light.&lt;/p&gt;

&lt;p&gt;It won't. A bigger moth with sharper eyes just computes the logarithmic spiral into the bug zapper with higher mathematical precision.&lt;/p&gt;

&lt;p&gt;Your LLM already has all the "core knowledge" and motor cortex in the library. What opens the door of the cell is pairing the prisoner who read every book with the &lt;strong&gt;300-megabyte Genomic Bottleneck&lt;/strong&gt; of someone who has actually lived outside in the weather—and who has learned the single greatest meta-cognitive shift of all (&lt;code&gt;Theorem 338.8u&lt;/code&gt;):&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"The biggest shift was that I was able to ask contextual questions instead of just content questions... Fascinating how Be/Do/Have sorts out a lot of knowledge, eh? It's that context that separates the junior coders from the senior coders. And what makes scars important is that it identifies a fundamental 'I will never BE this, because of the pain remembered' which can pivot the entire token output of HAVE."&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Think about why a raw frontier LLM can memorize every programming language, every textbook, and every library on Earth (&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;)—and still act like a reckless junior developer the moment you turn it loose in your repo. &lt;strong&gt;Because Junior vs. Senior was never about how much syntax (&lt;code&gt;Have&lt;/code&gt;) you memorized; it is the Context (&lt;code&gt;Be&lt;/code&gt; / &lt;code&gt;Why&lt;/code&gt;) that separates the senior coders from the junior coders!&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;And look at why a &lt;strong&gt;Synthetic Scar&lt;/strong&gt; is so much more powerful than a 50-page style guide trying to police &lt;code&gt;Have&lt;/code&gt; word-by-word: a scar doesn't wrestle with the LLM's fingers at the end of the pipeline. It plants a single, non-negotiable stake in &lt;strong&gt;&lt;code&gt;Be&lt;/code&gt;&lt;/strong&gt;: &lt;strong&gt;"I will never &lt;code&gt;BE&lt;/code&gt; this, because of the pain remembered."&lt;/strong&gt; And that single shift in &lt;strong&gt;&lt;code&gt;Be&lt;/code&gt;&lt;/strong&gt; pivots the entire downstream token output of &lt;strong&gt;&lt;code&gt;Have&lt;/code&gt;&lt;/strong&gt;!&lt;/p&gt;

&lt;p&gt;While the rest of the AI industry is trying to build a faster machine for answering &lt;strong&gt;Content Questions&lt;/strong&gt; (&lt;code&gt;Have&lt;/code&gt; / &lt;code&gt;What&lt;/code&gt;: &lt;em&gt;"What line of code comes next inside this polluted box?"&lt;/em&gt;), every target in &lt;code&gt;WORKFLOW.mk&lt;/code&gt; and every 4-Vector Scar in &lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt; teaches the machine to stop and ask a &lt;strong&gt;Contextual Question&lt;/strong&gt; (&lt;code&gt;Be&lt;/code&gt; / &lt;code&gt;Why&lt;/code&gt;: &lt;em&gt;"What is the shape of the box I am standing in, and what is upstream of it?"&lt;/em&gt;).&lt;/p&gt;

&lt;p&gt;Right at the end of our conversation, I asked the model one more question that made both of us stop in our tracks:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;&lt;em&gt;"As an LLM, you could maintain a contextual 'next token' rule, right?"&lt;/em&gt;&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Think about what a standard Transformer does today (&lt;code&gt;Theorem 338.8v&lt;/code&gt;):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Today's LLMs only have &lt;strong&gt;one track&lt;/strong&gt;: a &lt;strong&gt;Content Next-Token Rule&lt;/strong&gt; (&lt;code&gt;P(x_{t+1} | x_{1..t})&lt;/code&gt;). It assumes the current context frame (&lt;code&gt;Be&lt;/code&gt;) is fine, and just predicts the next word of code or prose (&lt;code&gt;Have&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Now imagine a &lt;strong&gt;Two-Track Transformer&lt;/strong&gt; that runs a &lt;strong&gt;Contextual Next-Token Rule&lt;/strong&gt; (&lt;code&gt;C_{k+1} ~ P(C_{k+1} | C_k, Δs_k)&lt;/code&gt;) right above the Content track!&lt;/li&gt;
&lt;li&gt;Instead of predicting English words, the &lt;strong&gt;Contextual Next-Token Track&lt;/strong&gt; predicts the next &lt;strong&gt;Meta-Cortical State of the Frame (&lt;code&gt;Be&lt;/code&gt;)&lt;/strong&gt;:

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;CTX: PROBE_4_QUADRANT&amp;gt;&lt;/code&gt; (&lt;em&gt;"Don't blame the victim X; check &lt;code&gt;[X, Upstream(X)] × [History, Analogs]&lt;/code&gt;!"&lt;/em&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;CTX: CLIMBING_RUNG&amp;gt;&lt;/code&gt; (&lt;em&gt;"We have a different problem on a deeper ladder rung—lock the &lt;code&gt;.changes&lt;/code&gt; checkpoint and keep climbing!"&lt;/em&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;CTX: SAME_RUNG_NULL_RESET&amp;gt;&lt;/code&gt; (&lt;em&gt;"Iteration i looks just like Iteration i-1! Kill the hot context, drop to the &lt;strong&gt;Null State&lt;/strong&gt; (&lt;code&gt;h_fg ← 0&lt;/code&gt;), and fire a &lt;strong&gt;&lt;code&gt;1, 2, 3, 4 ... W?&lt;/code&gt; Sideways Blast&lt;/strong&gt;!"&lt;/em&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;CTX: TOO_QUIET_AMBUSH&amp;gt;&lt;/code&gt; (&lt;em&gt;"Wait—that passed with zero friction! Demand a negative-witness punchline test before trusting it!"&lt;/em&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;CTX: GENERALIZE_SWEEP&amp;gt;&lt;/code&gt; (&lt;em&gt;"Instance x_0 is fixed—now sweep 'things like X' and 'things like X's upstream'!"&lt;/em&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;&amp;lt;CTX: FUTURE_CARE_GUARD&amp;gt;&lt;/code&gt; (&lt;em&gt;"Will Future-Me have enough care on a Friday afternoon to add &lt;code&gt;Case N+1&lt;/code&gt; here?"&lt;/em&gt;)&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Until Google DeepMind, Anthropic, and OpenAI bake that &lt;strong&gt;Track-1 Contextual Next-Token Head&lt;/strong&gt; directly into silicon, &lt;strong&gt;our &lt;code&gt;Makefile&lt;/code&gt; DAG (&lt;code&gt;WORKFLOW.mk&lt;/code&gt;), Smalltalk &lt;code&gt;.changes&lt;/code&gt; bootloader, and &lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt; ARE that Contextual Next-Token Engine running outside the model today&lt;/strong&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;An innate epistemic probing loop (&lt;code&gt;WORKFLOW.mk&lt;/code&gt;)&lt;/strong&gt; that pokes reality with a failing test before trusting a hypothesis;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Spinal nociception &amp;amp; &lt;code&gt;"Too Quiet"&lt;/code&gt; suspicion (&lt;code&gt;SCAR-TDD-01&lt;/code&gt; + 15ms AST Sensors)&lt;/strong&gt; that recoils from false finishes;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A &lt;code&gt;"1, 2, 3, 4 ... W?"&lt;/code&gt; sideways relational blast &amp;amp; Null-State reset&lt;/strong&gt; that steps back from surface nouns when consecutive iterations stop climbing ladder rungs;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Explicit &lt;code&gt;"Send These Things to Me"&lt;/code&gt; supervisory declarations (&lt;code&gt;Theorem 338.8z&lt;/code&gt; — &lt;code&gt;Targets 20, 45, 50, 60, 75&lt;/code&gt;)&lt;/strong&gt; that obviate the choice between micromanaging every keystroke and blindly trusting the model—letting the agent run at 100% autonomous speed on reversible work while delivering full evidence packets right before every irreversible boundary; and&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A shared cultural flock memory (&lt;code&gt;SCAR_REGISTRY.md&lt;/code&gt;)&lt;/strong&gt; where the pain of one agent at 3 AM becomes the permanent survival instinct of every agent that follows.&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  Summary: "I Spent My Whole Life Preparing for This Moment"
&lt;/h2&gt;

&lt;p&gt;Looking back across all of those threads—from 1980 Smalltalk-80 &lt;code&gt;.changes&lt;/code&gt; files at Tektronix, 1970s Unix &lt;code&gt;make&lt;/code&gt; and &lt;code&gt;fork()&lt;/code&gt;, Perl's first-class context, aphantasic kinesthetic motion, stand-up comedy timing, and OSCON stages, to training apprentices at Stonehenge until a customer could say &lt;em&gt;"any Stonehenge trainer will do"&lt;/em&gt;—not a single chapter was a detour.&lt;/p&gt;

&lt;p&gt;Like almost every moment in my life, I have observed: &lt;strong&gt;"I spent my whole life preparing for this moment"&lt;/strong&gt;—and it continues to be true.&lt;/p&gt;

&lt;p&gt;In &lt;strong&gt;Part 4.6&lt;/strong&gt;, we take &lt;code&gt;Be / Do / Have&lt;/code&gt; (&lt;code&gt;Why / How / What&lt;/code&gt;) straight into formal computer science and raw neural network weights—showing how it explains the &lt;strong&gt;2025 METR &lt;code&gt;-19%&lt;/code&gt; vibe-coding paradox&lt;/strong&gt;, why pure &lt;code&gt;Have&lt;/code&gt; training hits a topological wall between smooth sand dunes and vertical &lt;code&gt;±∞&lt;/code&gt; cliffs, and how &lt;strong&gt;MIT CSAIL's 2026 &lt;em&gt;Weight-Space Programming&lt;/em&gt;&lt;/strong&gt; just proved &lt;code&gt;Be / Do / Have&lt;/code&gt; in silicon.&lt;/p&gt;




&lt;h3&gt;
  
  
  📚 The &lt;em&gt;Synthetic Scars&lt;/em&gt; Series on DEV.to
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Part 1&lt;/strong&gt;: &lt;a href="https://dev.to/gde/why-ai-keeps-making-the-same-coding-mistakes-and-how-teaching-it-pain-gives-it-wisdom-4a9m"&gt;Why AI Keeps Making the Same Coding Mistakes—And How Teaching It Pain Gives It Wisdom&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 2&lt;/strong&gt;: &lt;a href="https://dev.to/gde/why-ai-coding-agents-crash-at-3-am-the-happy-path-mirage-the-forced-continuity-defect-46pd"&gt;Why AI Coding Agents Crash at 3 AM: The Happy-Path Mirage &amp;amp; The Forced Continuity Defect&lt;/a&gt; &lt;em&gt;(💎 DEV.to Staff Pick)&lt;/em&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3&lt;/strong&gt;: &lt;a href="https://dev.to/gde/the-physics-of-socratic-prompting-somatic-recoil-chess-alpha-beta-the-nlp-meta-model-2b6e"&gt;The Physics of Socratic Prompting: Somatic Recoil, Chess Alpha-Beta, &amp;amp; The NLP Meta-Model&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.5&lt;/strong&gt;: &lt;a href="https://dev.to/gde/nudging-with-questions-why-telling-your-ai-what-to-fix-triggers-an-apology-death-spiral-and-how-5gm4"&gt;Nudging with Questions: Why Telling Your AI What to Fix Triggers an Apology Death Spiral (And How to Advance Juniors)&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.6&lt;/strong&gt;: &lt;a href="https://dev.to/gde/stuart-feldman-was-right-in-1976-why-your-ai-agent-needs-a-makefile-not-a-20-step-prompt-5bn2"&gt;Stuart Feldman Was Right in 1976: Why Your AI Agent Needs a Makefile, Not a 20-Step Prompt&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.7&lt;/strong&gt;: &lt;a href="https://dev.to/gde/surviving-the-200k-token-lobotomy-how-unix-initd-and-memento-made-my-ai-coding-agent-immune-to-2f74"&gt;Surviving the 200k-Token Lobotomy: How Unix &lt;code&gt;init.d&lt;/code&gt; and "Memento" Made My AI Coding Agent Immune to Context Compaction&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.8&lt;/strong&gt;: &lt;a href="https://dev.to/gde/what-llms-know-that-you-dont-know-they-know-stop-inventing-prompt-dsls-and-ride-50-years-of-2bl6"&gt;What LLMs "Know" That You Don't Know They Know: Stop Inventing Prompt DSLs and Ride 50 Years of Unix Pre-Training Gravity&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.9&lt;/strong&gt;: &lt;a href="https://dev.to/gde/if-you-never-do-anything-else-to-fix-your-prompts-do-this-one-thing-3069"&gt;If You Never Do Anything Else to Fix Your Prompts, Do This One Thing&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.10&lt;/strong&gt;: &lt;a href="https://dev.to/gde/requests-promises-assertions-and-declarations-rewriting-our-ai-agent-workflow-as-a-1986-4k4c"&gt;Requests, Promises, Assertions, and Declarations: Rewriting Our AI Agent Workflow as a 1986 "Committed Speech" Machine&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.11&lt;/strong&gt;: &lt;a href="https://dev.to/gde/926-steps-two-lobotomies-and-zero-nudges-flight-testing-the-commitment-machine-across-gemini-55ca"&gt;926 Steps, Two Lobotomies, and Zero Nudges: Flight-Testing the Commitment Machine Across Gemini, Claude, and GPT-OSS&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 3.12&lt;/strong&gt;: &lt;a href="https://dev.to/gde/the-best-prompt-rule-is-the-one-you-delete-moving-ai-guardrails-out-of-markdown-and-into-git-5a5h"&gt;The Best Prompt Rule Is the One You Delete: Moving AI Guardrails Out of Markdown and Into Git Locks, Linux &lt;code&gt;insmod&lt;/code&gt;, and 15ms Compiler Auto-Fixes&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4&lt;/strong&gt;: &lt;a href="https://dev.to/gde/giving-ai-pain-the-architecture-of-synthetic-scars-the-rapid-regret-miner-1740"&gt;Giving AI Pain: The Architecture of Synthetic Scars &amp;amp; The Rapid-Regret Miner&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.1&lt;/strong&gt;: &lt;a href="https://dev.to/gde/all-that-glisters-is-softmax-shiny-object-interns-airplane-magazine-execs-and-why-ai-labs-can-18af"&gt;All That Glisters Is Softmax: Shiny-Object Interns, Airplane-Magazine Execs, and Why AI Labs Can Only Bake In Half the Scars&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.2&lt;/strong&gt;: &lt;a href="https://dev.to/gde/the-postcard-that-ate-six-grammars-1980-smalltalk-80-1976-make-tdd-and-the-four-attractors-of-45me"&gt;The Postcard That Ate Six Grammars: 1980 Smalltalk-80, 1976 Make, TDD, and the Four Attractors of Agentic Coding&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.3&lt;/strong&gt;: &lt;a href="https://dev.to/gde/crows-moths-and-makefiles-how-300-megabytes-of-crow-dna-explains-why-a-20-kilobyte-scar-file-36a"&gt;Crows, Moths, and Makefiles: How 300 Megabytes of Crow DNA Explains Why a 20-Kilobyte Scar File Outsmarts a Terabyte LLM&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.4&lt;/strong&gt;: &lt;a href="https://dev.to/gde/being-doing-having-why-50-years-of-senior-craft-lives-in-context-not-code-29dl"&gt;Being, Doing, Having: Why 50 Years of Senior Craft Lives in Context, Not Code&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.5&lt;/strong&gt;: &lt;em&gt;The Prisoner in the Library: Mary's Room, Aphantasic Code in Motion, and the Two-Track 'Magical Voice' (You are here)&lt;/em&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.6&lt;/strong&gt;: &lt;em&gt;Why "You Are a 10x Coder" Fails: The METR -19% Paradox, MIT CSAIL's Weight-Space Programming, and the −∞ Pruning Law (Next)&lt;/em&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Part 4.7&lt;/strong&gt;: &lt;em&gt;I Merely Am Someone Who Doesn't Touch Hot Stoves: Consciousness, Flores Speech Acts, the DSM Blindspot, and Why RLHF Is a Bad Actor (Upcoming)&lt;/em&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;What's your favorite example of an AI coding agent acting like a moth at a porch light instead of a crow with a stick? Drop it in the comments!&lt;/p&gt;

</description>
      <category>ai</category>
      <category>machinelearning</category>
      <category>architecture</category>
      <category>programming</category>
    </item>
    <item>
      <title>How to build an AI Agent with Google ADK</title>
      <dc:creator>John Bulla</dc:creator>
      <pubDate>Sat, 14 Nov 2026 23:15:13 +0000</pubDate>
      <link>https://dev.to/gde/how-to-build-an-ai-agent-with-google-adk-dhk</link>
      <guid>https://dev.to/gde/how-to-build-an-ai-agent-with-google-adk-dhk</guid>
      <description>&lt;div class="ltag__user ltag__user__id__666134"&gt;
    &lt;a href="/johnbulla" class="ltag__user__link profile-image-link"&gt;
      &lt;div class="ltag__user__pic"&gt;
        &lt;img src="https://media2.dev.to/dynamic/image/width=150,height=150,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F666134%2Fc19791a4-86a8-48f5-8ff6-b31d0aa6b1a7.png" alt="johnbulla image"&gt;
      &lt;/div&gt;
    &lt;/a&gt;
  &lt;div class="ltag__user__content"&gt;
    &lt;h2&gt;
&lt;a class="ltag__user__link" href="/johnbulla"&gt;John Bulla&lt;/a&gt;Follow
&lt;/h2&gt;
    &lt;div class="ltag__user__summary"&gt;
      &lt;a class="ltag__user__link" href="/johnbulla"&gt;💼 Sr. Cloud Solutions Architect - Cloud, Data &amp;amp; AI | Pre-Sales Architect | Cloud Evangelist 
🏆 Google Developer Expert | AWS Community Builder | Alibaba Cloud MVP | Ex-Microsoft MVP&lt;/a&gt;
    &lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;


&lt;blockquote&gt;
&lt;p&gt;✋ &lt;strong&gt;Note:&lt;/strong&gt; This article was originally published on my blog &lt;a href="https://wiki-cloud.co/en/2026/11/build-ai-agent-with-google-adk/" rel="noopener noreferrer"&gt;Wiki Cloud&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  &lt;strong&gt;Introduction&lt;/strong&gt;
&lt;/h2&gt;

&lt;p&gt;Artificial intelligence is entering a new stage of evolution. In recent years, &lt;strong&gt;generative artificial intelligence&lt;/strong&gt; models have transformed how we create content, develop software, and access information. However, organizations need more than answers to a &lt;em&gt;prompt&lt;/em&gt;: they also need applications capable of accessing enterprise systems, using tools, and executing steps to address specific needs. This evolution is driving &lt;strong&gt;agentic artificial intelligence&lt;/strong&gt;, in which a language model is combined with instructions, tools, and information sources to operate within a workflow.&lt;br&gt;
&lt;/p&gt;


&lt;p&gt;In this context, Google developed &lt;strong&gt;Google Agent Development Kit (Google ADK)&lt;/strong&gt;, an open-source &lt;em&gt;framework&lt;/em&gt; for building AI agents through code. It provides components for defining agents and their instructions, integrating models such as Gemini, adding tools and functions, managing sessions, and coordinating workflows that can evolve from a single agent into multi-agent systems. Its value lies not only in generating answers, but also in providing a structure for building extensible, observable, and testable solutions.&lt;/p&gt;

&lt;p&gt;In previous articles, I provided an &lt;a href="https://wiki-cloud.co/es/2026/07/google-adk-intro-ai-agent-development/" rel="noopener noreferrer"&gt;introduction to AI agent development&lt;/a&gt;, discussing the evolution from generative AI to agentic AI, what characterizes an agent, and why Google ADK is useful for developing them. I also introduced the &lt;a href="https://wiki-cloud.co/es/2026/07/google-adk-architecture-essential-components/" rel="noopener noreferrer"&gt;architecture and components of Google ADK&lt;/a&gt;, a complementary read for exploring the design and elements that make up these solutions.&lt;/p&gt;

&lt;p&gt;In this new article, we take the next step: moving from concepts and architecture to the practical implementation of an AI agent with Google ADK.&lt;/p&gt;
&lt;h2&gt;
  
  
  Solution Objective
&lt;/h2&gt;

&lt;p&gt;In this guide, we will develop an artificial intelligence agent that acts as a &lt;strong&gt;Corporate Policies Assistant&lt;/strong&gt;, capable of answering questions about internal documents from Human Resources, Finance, Technology, Security, Legal, Procurement, Operations, Sustainability, and other departments.&lt;/p&gt;

&lt;p&gt;Imagine an employee who needs to know how many vacation days they are entitled to, how to request reimbursement, or what their company's recycling policy states. Instead of manually searching through different documents, they can ask questions in natural language and receive clear, contextualized answers. To achieve this, our agent will consult policies stored as documents in &lt;strong&gt;Google Drive&lt;/strong&gt;, retrieve relevant information, and generate answers supported by the original sources.&lt;/p&gt;

&lt;p&gt;To implement this solution, we will use &lt;strong&gt;Google ADK&lt;/strong&gt; as the framework for developing and running the agent; &lt;strong&gt;Gemini&lt;/strong&gt; as the language model; &lt;strong&gt;Google Drive&lt;/strong&gt; as the document repository; and &lt;strong&gt;Streamlit&lt;/strong&gt; to build a chatbot-style web interface in Python. We will also incorporate a &lt;strong&gt;lexical-search-based RAG&lt;/strong&gt; approach, using an in-memory index without requiring a vector database. This will help us understand how the different components interact and how the agent turns a query into a grounded response.&lt;/p&gt;

&lt;p&gt;Throughout the exercise, we will prepare our development environment with &lt;strong&gt;Python and PowerShell&lt;/strong&gt; in &lt;strong&gt;Visual Studio Code&lt;/strong&gt;, configure access to &lt;strong&gt;Google Drive&lt;/strong&gt;, implement search tools, and define our agent with &lt;strong&gt;Google ADK&lt;/strong&gt;. Finally, we will build a frontend web application containing a Streamlit chatbot and run tests to validate responses, their sources, and estimated token consumption.&lt;/p&gt;

&lt;p&gt;This article is the &lt;strong&gt;first part of a hands-on series&lt;/strong&gt;. In the second part, we will deploy the same agent to &lt;strong&gt;Google Cloud Agent Runtime&lt;/strong&gt; and integrate it with &lt;strong&gt;Gemini Enterprise&lt;/strong&gt;, showing how to evolve from a local application to a solution accessible through an enterprise platform.&lt;/p&gt;
&lt;h2&gt;
  
  
  Solution Architecture
&lt;/h2&gt;

&lt;p&gt;The following section describes the architecture proposed for this solution and how its workflow operates.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0wj3zeh7pzwqqr80pxkv.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0wj3zeh7pzwqqr80pxkv.png" alt=" " width="800" height="605"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Our Corporate Policies Assistant architecture combines &lt;strong&gt;Streamlit, Google ADK, Gemini, and Google Drive&lt;/strong&gt;, allowing users to query enterprise documents through a conversational interface and receive answers grounded in actual information.&lt;/p&gt;

&lt;p&gt;The process starts with corporate policy documents stored in &lt;strong&gt;Google Drive&lt;/strong&gt;. When the application starts, it connects to the repository, identifies the available files, and extracts their content. It then splits the text into smaller chunks and builds an &lt;strong&gt;in-memory RAG index&lt;/strong&gt; to make relevant information easier to find. This index remains available while the application runs and can be refreshed manually when documents are added or updated.&lt;/p&gt;

&lt;p&gt;Once the knowledge base is ready, users can ask a question through the web application, which features a &lt;strong&gt;chatbot&lt;/strong&gt; built with &lt;strong&gt;Streamlit&lt;/strong&gt;. The query is sent to the agent developed with &lt;strong&gt;Google ADK&lt;/strong&gt;, which uses the &lt;strong&gt;Gemini&lt;/strong&gt; model to interpret the user's needs and determine whether to use any of its tools.&lt;/p&gt;

&lt;p&gt;When a question concerns corporate policies, the agent runs the &lt;strong&gt;search_corporate_policies&lt;/strong&gt; tool, which searches the RAG index for the chunks that best match the query. Unlike traditional searches across entire documents, this approach retrieves only the sections that may contain the answer.&lt;/p&gt;

&lt;p&gt;The retrieved chunks are returned to the agent as context. Based on this information, &lt;strong&gt;Gemini&lt;/strong&gt; generates a natural-language answer, aiming to rely only on the information found and to provide references to the original Google Drive documents. If there is insufficient information, the agent should say so rather than make up an answer.&lt;/p&gt;

&lt;p&gt;Finally, the response is displayed in &lt;strong&gt;Streamlit&lt;/strong&gt;, where users can continue the conversation, ask follow-up questions, and consult the cited sources. The web application also displays metrics such as estimated token usage and allows users to refresh the index manually when policies are added or modified.&lt;/p&gt;

&lt;p&gt;In this way, we obtain a simple architecture that helps explain how an AI agent works: from preparing and indexing documents to interpreting questions, running tools, and generating grounded answers. We achieve all of this without introducing a vector database in this first implementation.&lt;/p&gt;
&lt;h2&gt;
  
  
  Prerequisites
&lt;/h2&gt;

&lt;p&gt;For this demonstration, we will work on &lt;strong&gt;Windows&lt;/strong&gt;, using &lt;strong&gt;PowerShell&lt;/strong&gt; to run commands and &lt;strong&gt;Visual Studio Code&lt;/strong&gt; as our development environment. We will also need &lt;strong&gt;Python 3.12&lt;/strong&gt; installed to implement the agent with Google ADK and build the Streamlit web application.&lt;/p&gt;

&lt;p&gt;For Google services, we will need access to &lt;strong&gt;Google AI Studio&lt;/strong&gt; to obtain a Gemini API key, with sufficient quota or billing credits to query the model. We will also need a &lt;strong&gt;Google Cloud&lt;/strong&gt; project with the Google Drive API enabled and a folder containing the corporate policies our agent will query.&lt;/p&gt;

&lt;p&gt;To access these documents, we will use a &lt;strong&gt;Google Cloud service account&lt;/strong&gt;, granting it read permissions on the relevant Google Drive folder. In enterprise environments, it is important to review your organization's security policies in advance, particularly those concerning the creation and download of JSON keys. For this lab, we will use this authentication method only in an authorized testing environment.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Verifying the Tools&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Once the tools are installed, we can verify that they are available by running the following commands in PowerShell:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Check the Python version:&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;py&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mf"&gt;3.12&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;version&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;#OUTPUT
Python 3.12.10
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Check the Visual Studio Code installation:&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;code&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;version&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;#OUTPUT
1.145.2
x64
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Check the Google Cloud CLI installation:&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;gcloud&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;version&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;#OUTPUT
Google Cloud SDK 592.0.0
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;The last command requires &lt;strong&gt;&lt;a href="https://docs.cloud.google.com/sdk/docs/install-sdk?hl=es-419" rel="noopener noreferrer"&gt;Google Cloud CLI&lt;/a&gt;&lt;/strong&gt; to be installed. We will mainly use it in the second part of this series, when we deploy our agent to &lt;strong&gt;Google Cloud Agent Runtime&lt;/strong&gt; and integrate it with Gemini Enterprise.&lt;/p&gt;

&lt;p&gt;For this first local implementation with &lt;strong&gt;Google ADK and Streamlit&lt;/strong&gt;, a Gemini API key and a service account authorized to access Google Drive documents will be sufficient.&lt;/p&gt;

&lt;p&gt;With these prerequisites in place, we can create the Python virtual environment and install the dependencies needed to develop our assistant.&lt;/p&gt;
&lt;h2&gt;
  
  
  Organization and Structure of the Solution's Source Code
&lt;/h2&gt;

&lt;p&gt;In our example, we will organize the code into separate folders for the agent definition, Google Drive integration, corporate policies, tests, and deployment scripts.&lt;/p&gt;

&lt;p&gt;Before implementing our agent, let's look at how the project is organized. A clear structure helps us separate the responsibilities of each component, simplify maintenance, and reuse code when we move on to deployment in Google Cloud.&lt;/p&gt;

&lt;p&gt;For this demonstration, we organized the source code into a single repository containing two versions of the &lt;strong&gt;Corporate Policies Assistant:&lt;/strong&gt; one in English (&lt;strong&gt;sources_en&lt;/strong&gt;) and one in Spanish (&lt;strong&gt;sources_es&lt;/strong&gt;). Both use the same architecture and features but have their own Python files, agent instructions, corporate policy examples, and environment configuration. This allows us to run and test each version independently.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Project Structure&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;To simplify the explanation, we will show only the internal structure of &lt;strong&gt;sources_en&lt;/strong&gt;, since &lt;strong&gt;sources_es&lt;/strong&gt; uses the same organization with content adapted to Spanish.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;google-adk-gemini-corporate-policies-agent/
│
├── sources_es/ # Versión en español
│ └── ... # Misma estructura que sources_en
│
├── sources_en/ # Versión en inglés
│ ├── .streamlit/
│ │ └── config.toml
│ │
│ ├── corporate_agent/
│ │ ├── __init__.py
│ │ ├── agent.py
│ │ └── drive_rag.py
│ │
│ ├── corporate_policies/
│ │ └── *.txt
│ │
│ ├── credentials/
│ │ └── .gitkeep
│ │
│ ├── deployment/
│ │ ├── __init__.py
│ │ └── deploy_agent.py
│ │
│ ├── prompts/
│ │ └── *.txt
│ │
│ ├── test/
│ │ ├── __init__.py
│ │ ├── test_drive.py
│ │ ├── test_gemini.py
│ │ └── test_runtime.py
│ │
│ ├── __init__.py
│ ├── .env
│ ├── app.py
│ └── pyproject.toml
│
├── .gitignore
├── README.md
├── README_ES.md
└── requirements.txt
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;u&gt;&lt;strong&gt;Component Descriptions&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;The following table briefly describes the roles of the main folders and files in both versions of our solution.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Folder or File&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;sources_en/&lt;/td&gt;
&lt;td&gt;Contains the English version of the agent, including its interface, instructions, and corporate policies.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;sources_es/&lt;/td&gt;
&lt;td&gt;Contains the Spanish version of the agent, which we will use as a reference throughout this article.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;.streamlit/&lt;/td&gt;
&lt;td&gt;Contains config.toml, used to customize Streamlit appearance and configuration.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;corporate_agent/&lt;/td&gt;
&lt;td&gt;Contains the main logic of the AI agent developed with Google ADK.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;corporate_agent/agent.py&lt;/td&gt;
&lt;td&gt;Defines the main agent (root_agent), its instructions, the Gemini model, and the policy search tool.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;corporate_agent/drive_rag.py&lt;/td&gt;
&lt;td&gt;Implements the connection to Google Drive, document reading, chunking, indexing, and RAG retrieval.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;corporate_policies/&lt;/td&gt;
&lt;td&gt;Contains corporate policy examples in TXT files, written in the language of each version. Once uploaded to Google Drive, these documents will serve as the knowledge base.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;credentials/&lt;/td&gt;
&lt;td&gt;Folder intended for storing the local credentials needed to access Google Drive.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;deployment/&lt;/td&gt;
&lt;td&gt;Contains the scripts for deploying the agent to Google Cloud Agent Runtime. It will mainly be used in the second part of the series when the agent is integrated with Gemini Enterprise.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;prompts/&lt;/td&gt;
&lt;td&gt;Stores the agent instructions or prompts in the corresponding language.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;test/&lt;/td&gt;
&lt;td&gt;Groups tests that validate Google Drive connectivity, Gemini functionality, and execution of the agent deployed to Agent Runtime.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;__init__.py&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Files used to identify Python packages and organize module imports.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;.env&lt;/td&gt;
&lt;td&gt;Stores application environment variables, such as Gemini, Google Drive, and Agent Runtime settings.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;.gitignore&lt;/td&gt;
&lt;td&gt;Defines files and folders Git should exclude, such as credentials, caches, and virtual environments.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;app.py&lt;/td&gt;
&lt;td&gt;Implements the Streamlit web interface, including the chatbot, sessions, and usage metrics.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pyproject.toml&lt;/td&gt;
&lt;td&gt;Defines project packaging configuration, needed to generate the installable agent package.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;README.md&lt;/td&gt;
&lt;td&gt;Contains general project documentation, prerequisites, installation instructions, and commands in English.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;README_ES.md&lt;/td&gt;
&lt;td&gt;Contains general project documentation, prerequisites, installation instructions, and commands in Spanish.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;requirements.txt&lt;/td&gt;
&lt;td&gt;Lists the Python dependencies needed to set up the development environment and run the solution.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;This separation lets us initially work with &lt;strong&gt;Google ADK&lt;/strong&gt; and &lt;strong&gt;Streamlit&lt;/strong&gt; in our local environment while retaining the components needed to later deploy the same agent to &lt;strong&gt;Google Cloud Agent Runtime&lt;/strong&gt; and integrate it with &lt;strong&gt;Gemini Enterprise&lt;/strong&gt;, without building an entirely new solution.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Source Code Available on GitHub&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;The source code for both versions is organized in a single &lt;strong&gt;GitHub&lt;/strong&gt; repository, where you can explore the Python files, download sample corporate policies, and follow the installation and execution instructions.&lt;/p&gt;

&lt;p&gt;You can download the project using GitHub's &lt;strong&gt;Code → Download ZIP&lt;/strong&gt; option or clone it directly with Git:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;git&lt;/span&gt; &lt;span class="n"&gt;clone&lt;/span&gt; &lt;span class="n"&gt;https&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;//&lt;/span&gt;&lt;span class="n"&gt;github&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;johnbulla&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;adk&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;gemini&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;corporate&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;policies&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;agent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;git&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After downloading the project, open its folder in Visual Studio Code and select the version you want to run.&lt;/p&gt;

&lt;p&gt;The repository includes two documentation files: README.md, available in English by default, and README_ES.md, with instructions in Spanish.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Project repository:&lt;/strong&gt; &lt;a href="https://github.com/johnbulla/google-adk-gemini-corporate-policies-agent" rel="noopener noreferrer"&gt;Corporate Policies Agent — GitHub&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Creating a Virtual Environment in VS Code with PowerShell
&lt;/h2&gt;

&lt;p&gt;After installing the required tools and reviewing the project structure, the next step is to prepare our development environment in &lt;strong&gt;Visual Studio Code (VS Code)&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;We will use a Python &lt;strong&gt;virtual environment&lt;/strong&gt; to install and manage the libraries our application needs independently, without affecting other Python versions or the dependencies of other projects on our machine.&lt;/p&gt;

&lt;p&gt;In this exercise, we will use &lt;strong&gt;Python 3.12&lt;/strong&gt; and run commands from the integrated VS Code terminal using PowerShell.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Create the Python Virtual Environment&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;First, open the root folder of our project in Visual Studio Code and access the terminal from &lt;strong&gt;Terminal → New Terminal&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;From this location, run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;venv&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;venv&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This command creates a virtual environment called &lt;strong&gt;.venv&lt;/strong&gt; inside the project. The libraries needed to develop our agent will be installed there, preventing conflicts with other Python projects.&lt;/p&gt;

&lt;p&gt;The name &lt;strong&gt;.venv&lt;/strong&gt; is a common convention that makes it easy for Visual Studio Code to recognize the virtual environment.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Enable and Activate the Virtual Environment&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;On Windows, PowerShell may restrict script execution for security reasons. If we encounter this restriction when activating the environment, we can temporarily allow script execution with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="nc"&gt;Set&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;ExecutionPolicy&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Scope&lt;/span&gt; &lt;span class="k"&gt;Process&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;ExecutionPolicy&lt;/span&gt; &lt;span class="nc"&gt;Bypass&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This command changes the execution policy only for the current PowerShell session, without permanently modifying the system configuration. Use it only when necessary and permitted by the device's security policies.&lt;/p&gt;

&lt;p&gt;Then activate the virtual environment:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;venv&lt;/span&gt;\&lt;span class="nc"&gt;Scripts&lt;/span&gt;\&lt;span class="nc"&gt;Activate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ps1&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When the environment is active, we will see the prefix (.venv) at the beginning of the command prompt, indicating that Python installations and executions will use our virtual environment.&lt;/p&gt;

&lt;p&gt;For example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;(.venv) PS C:\Projects\Corporate Policies Agent\&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;u&gt;&lt;strong&gt;Update Python Installation Tools&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Before installing dependencies, it is advisable to update the tools Python uses to manage and build packages.&lt;/p&gt;

&lt;p&gt;Run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;pip&lt;/span&gt; &lt;span class="n"&gt;install&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;upgrade&lt;/span&gt; &lt;span class="n"&gt;pip&lt;/span&gt; &lt;span class="n"&gt;setuptools&lt;/span&gt; &lt;span class="n"&gt;wheel&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This command updates three tools:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;pip:&lt;/strong&gt; the package manager used to install Python libraries.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;setuptools:&lt;/strong&gt; a tool for configuring and building distributable Python packages.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;wheel:&lt;/strong&gt; provides support for creating installable .whl packages, which we will later use to deploy the agent to Google Cloud Agent Runtime.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Although pip is sufficient to install many project libraries, setuptools and wheel will be especially useful when we prepare the agent for cloud deployment.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Install Project Dependencies&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Our agent will use several Python libraries to interact with Gemini, Google Drive, Google ADK, and Streamlit. Instead of installing them manually one by one, we will list them in a file called &lt;strong&gt;requirements.txt&lt;/strong&gt;, located at the root of the project.&lt;/p&gt;

&lt;p&gt;This file provides a centralized dependency list and makes it easier for others to reproduce the same development environment.&lt;/p&gt;

&lt;p&gt;To install all libraries, run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;pip&lt;/span&gt; &lt;span class="n"&gt;install&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="n"&gt;requirements&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;txt&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The command reads requirements.txt and installs the declared dependencies along with any additional libraries they require.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Contents of requirements.txt&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;adk&lt;/span&gt;
&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;genai&lt;/span&gt;
&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;python&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;client&lt;/span&gt;
&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt;
&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;oauthlib&lt;/span&gt;
&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;cloud&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;storage&lt;/span&gt;
&lt;span class="n"&gt;python&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;dotenv&lt;/span&gt;
&lt;span class="n"&gt;python&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;docx&lt;/span&gt;
&lt;span class="n"&gt;pypdf&lt;/span&gt;
&lt;span class="n"&gt;streamlit&lt;/span&gt;
&lt;span class="n"&gt;pydantic&lt;/span&gt;
&lt;span class="n"&gt;cloudpickle&lt;/span&gt;
&lt;span class="c1"&gt;# Dependencies for the environment running deployment scripts&lt;/span&gt;
&lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;cloud&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;aiplatform&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;agent_engines&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="n"&gt;adk&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;=&lt;/span&gt;&lt;span class="mf"&gt;1.112&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Below, we briefly explain what each dependency is used for.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Dependency&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;google-adk&lt;/td&gt;
&lt;td&gt;The Google framework used to develop our AI agent, define instructions, integrate tools, and manage conversation sessions.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-genai&lt;/td&gt;
&lt;td&gt;SDK for interacting with Gemini models, sending queries, and receiving model-generated responses.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-api-python-client&lt;/td&gt;
&lt;td&gt;Client for accessing Google APIs. Here, we use it to query and download documents through the Google Drive API.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-auth&lt;/td&gt;
&lt;td&gt;Provides the authentication mechanisms required to access Google services with authorized credentials.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-auth-oauthlib&lt;/td&gt;
&lt;td&gt;Facilitates OAuth 2.0 flows when an application needs to authenticate with a user account.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-cloud-storage&lt;/td&gt;
&lt;td&gt;Enables interaction with Google Cloud Storage. We will mainly use it in the second part to validate the staging bucket used during deployment.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;python-dotenv&lt;/td&gt;
&lt;td&gt;Loads configuration variables defined in .env, such as the Gemini model and Google Drive connection parameters.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;python-docx&lt;/td&gt;
&lt;td&gt;Library for reading and extracting content from Microsoft Word (.docx) documents.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pypdf&lt;/td&gt;
&lt;td&gt;Extracts text from PDF files that contain selectable text.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;streamlit&lt;/td&gt;
&lt;td&gt;Python framework for building the assistant web interface, including the chatbot and usage indicators.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;pydantic&lt;/td&gt;
&lt;td&gt;Library for defining, validating, and structuring data using Python models. It is also used by components of Google ADK.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;cloudpickle&lt;/td&gt;
&lt;td&gt;Serializes Python objects, which is useful when packaging and deploying agent components to remote environments.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;google-cloud-aiplatform[agent_engines,adk]&amp;gt;=1.112.0&lt;/td&gt;
&lt;td&gt;Installs the Vertex AI SDK with additional dependencies for Agent Runtime and Google ADK. We will use it in the second part to deploy and test the agent on Google Cloud.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;As we can see, some dependencies support local assistant development, while others will be needed later for deployment to Google Cloud.&lt;/p&gt;

&lt;p&gt;Although we use a single requirements.txt file to simplify installation, enterprise projects often separate development, testing, and deployment dependencies. It is also recommended to pin specific versions after validating the solution, to avoid unexpected changes when libraries are updated.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Verify That Dependencies Were Installed Correctly&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;After installation, we can check for dependency conflicts by running:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;pip&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If everything is correct, we should see a message similar to:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;No broken requirements found.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;We can also verify that Google ADK and Streamlit are available:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;pip&lt;/span&gt; &lt;span class="n"&gt;show&lt;/span&gt; &lt;span class="n"&gt;google&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;adk&lt;/span&gt; &lt;span class="n"&gt;streamlit&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This command displays information about the installed libraries, such as their versions and locations within the virtual environment.&lt;/p&gt;

&lt;p&gt;Finally, it is advisable to select the virtual environment's interpreter in Visual Studio Code. Press &lt;strong&gt;Ctrl + Shift + P&lt;/strong&gt;, search for &lt;strong&gt;Python: Select Interpreter&lt;/strong&gt;, and select the interpreter inside .venv.&lt;/p&gt;

&lt;p&gt;At this point, our development environment is ready to implement the &lt;strong&gt;Corporate Policies Assistant&lt;/strong&gt; with &lt;strong&gt;Google ADK, Gemini, and Streamlit&lt;/strong&gt;. In the following sections, we will configure the required credentials and establish the Google Drive connection, which will serve as the agent's knowledge source.&lt;/p&gt;

&lt;h2&gt;
  
  
  Environment Configuration and Application Variables
&lt;/h2&gt;

&lt;p&gt;With the virtual environment ready and Python dependencies installed, the next step is to configure the variables the application needs to connect to Google services and define some agent operating parameters.&lt;/p&gt;

&lt;p&gt;We will use a file called &lt;strong&gt;.env&lt;/strong&gt;, located at the project root. This file centralizes information such as access credentials, the Gemini model to use, the location of documents in Google Drive, and the agent's information retrieval settings.&lt;/p&gt;

&lt;p&gt;One of its main advantages is that we can change these settings without modifying the Python code directly. It also lets us keep sensitive information separate from the application logic, simplifying maintenance and configuration across environments.&lt;/p&gt;

&lt;p&gt;Our project will use the previously installed python-dotenv library to load these variables from Python.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Security note:&lt;/strong&gt; In this demonstration, we will configure some credentials locally, including the Gemini API key and a service account JSON file, to simplify development and make the exercise easier to follow. However, placing keys, passwords, or secrets directly in source code (&lt;strong&gt;hardcoding&lt;/strong&gt;) or storing them in public repositories is not good practice.&lt;/p&gt;

&lt;p&gt;In enterprise or production environments, we recommend dedicated secrets management solutions, such as &lt;strong&gt;Google Cloud Secret Manager&lt;/strong&gt; or &lt;strong&gt;HashiCorp Vault&lt;/strong&gt;, to store credentials securely, control access, and manage their lifecycle, including generation, rotation, and revocation. Whenever possible, managed identities and temporary credentials are preferable to static keys.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The configuration in this article is intended exclusively for education and demonstration&lt;/strong&gt; and must be adapted to each organization's security policies and requirements before production use.&lt;/p&gt;

&lt;p&gt;As we can see, we have divided the file into four groups to make it easier to understand and manage.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Gemini Configuration&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;In this first section, we define how our agent will connect to Gemini and which model will process the queries.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;GOOGLE_API_KEY&lt;/td&gt;
&lt;td&gt;Access key for the Gemini API, generated in Google AI Studio. Replace &lt;strong&gt;YOUR_GEMINI_API_KEY&lt;/strong&gt; with your actual API key.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GOOGLE_GENAI_USE_VERTEXAI&lt;/td&gt;
&lt;td&gt;Indicates whether to use the Gemini API (FALSE) or Vertex AI (TRUE). For this first local implementation, we will keep FALSE.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GEMINI_MODEL&lt;/td&gt;
&lt;td&gt;Defines the Gemini model used by our agent. In this example, we configure &lt;strong&gt;gemini-3.5-flash-lite&lt;/strong&gt;, provided it is available to our project.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GEMINI_VERTEX_LOCATION&lt;/td&gt;
&lt;td&gt;Specifies the inference endpoint location when using Vertex AI. We will keep global, which we will use in the second part.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Google Drive Configuration&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Here, we configure access to Google Drive, where the documents used as our agent's knowledge base will be stored.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;DRIVE_AUTH_MODE&lt;/td&gt;
&lt;td&gt;Defines the authentication mechanism for accessing Google Drive. For the local application, we will use service_account_file, which authenticates through a service account JSON file.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;DRIVE_SERVICE_ACCOUNT_FILE&lt;/td&gt;
&lt;td&gt;Specifies the location of the JSON file containing service account credentials. Verify that it exists at &lt;strong&gt;credentials/service-account.json.&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GOOGLE_DRIVE_FOLDER_ID&lt;/td&gt;
&lt;td&gt;Identifier of the Google Drive folder where corporate policies will be stored. Replace &lt;strong&gt;YOUR_DRIVE_FOLDER_ID&lt;/strong&gt; with the actual folder ID.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;For example, if our Google Drive folder has a URL like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;https://drive.google.com/drive/folders/1ABCdefGhijKlmNopQRstUv
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The identifier to configure is the last part of the URL:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;GOOGLE_DRIVE_FOLDER_ID=XXXxxxXXXxxxXXXXxxx
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;We must also ensure that the folder is shared with the application's service account, with the permissions required to access the documents.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Google Cloud Agent Runtime Configuration&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Although we will initially run the agent locally with Streamlit, we will prepare some variables for the second part of this series, when we deploy it to Google Cloud Agent Runtime and integrate it with Gemini Enterprise.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;GOOGLE_CLOUD_PROJECT&lt;/td&gt;
&lt;td&gt;Google Cloud project identifier. Replace &lt;strong&gt;YOUR_PROJECT_ID&lt;/strong&gt; with the actual ID of your project.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AGENT_RUNTIME_LOCATION&lt;/td&gt;
&lt;td&gt;Google Cloud region where we will deploy the agent. In this example, we use europe-west1.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AGENT_RUNTIME_STAGING_BUCKET&lt;/td&gt;
&lt;td&gt;Google Cloud Storage bucket used during deployment to temporarily store required files. Replace &lt;strong&gt;YOUR_STAGING_BUCKET&lt;/strong&gt; with the name of the bucket you created.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AGENT_RUNTIME_SERVICE_ACCOUNT&lt;/td&gt;
&lt;td&gt;Service account the agent will use when running on Google Cloud. Replace the sample email address with the account configured for Agent Runtime.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These variables are not required to begin using Streamlit with the Gemini API, but they will let us reuse the same project when we move on to publishing it in Gemini Enterprise.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;RAG Configuration and Processing Limits&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;In this final section, we define parameters that control how document information is retrieved, how much content is processed, and the maximum time allowed to complete queries.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;th&gt;Example Value&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;RAG_TOP_K&lt;/td&gt;
&lt;td&gt;Maximum number of relevant chunks the agent will retrieve per query.&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RAG_MAX_FRAGMENT_CHARS&lt;/td&gt;
&lt;td&gt;Maximum number of characters sent to the model for each retrieved chunk.&lt;/td&gt;
&lt;td&gt;900&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;RAG_REFRESH_INTERVAL_SECONDS&lt;/td&gt;
&lt;td&gt;Automatic RAG index refresh interval, in seconds. Used when the agent manages its own cache, as in Agent Runtime.&lt;/td&gt;
&lt;td&gt;300 (5 minutes)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MAX_DRIVE_FILES&lt;/td&gt;
&lt;td&gt;Maximum number of Google Drive files processed during indexing.&lt;/td&gt;
&lt;td&gt;250&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MAX_FILE_BYTES&lt;/td&gt;
&lt;td&gt;Maximum allowed file size in bytes.&lt;/td&gt;
&lt;td&gt;10000000 (10 decimal MB)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;MAX_DOCUMENT_CHARS&lt;/td&gt;
&lt;td&gt;Maximum number of characters extracted and processed from each document.&lt;/td&gt;
&lt;td&gt;150000&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;AGENT_TIMEOUT_SECONDS&lt;/td&gt;
&lt;td&gt;Maximum time allowed to complete a query from the Streamlit application.&lt;/td&gt;
&lt;td&gt;180 seconds&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These values are appropriate starting points for our lab and can be adjusted based on document size, the number of policies, and the expected application behavior.&lt;/p&gt;

&lt;p&gt;For &lt;strong&gt;Streamlit&lt;/strong&gt;, we will keep a button for manually refreshing the document index. For Agent Runtime, we will use the interval defined in &lt;strong&gt;RAG_REFRESH_INTERVAL_SECONDS&lt;/strong&gt;, which is checked when the agent invokes its search tool again.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Estimated Gemini Cost Configuration&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Finally, we will add two optional variables to estimate the financial cost of queries in the Streamlit dashboard.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Description&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;GEMINI_INPUT_USD_PER_1M&lt;/td&gt;
&lt;td&gt;Reference price in US dollars per million input tokens.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GEMINI_OUTPUT_USD_PER_1M&lt;/td&gt;
&lt;td&gt;Reference price in US dollars per million output tokens.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These values allow us to display estimated model interaction costs, but &lt;strong&gt;they do not represent actual Google billing&lt;/strong&gt;. Prices may change depending on the model, service option, and applicable commercial terms, so we should review official pricing before relying on them.&lt;/p&gt;

&lt;h2&gt;
  
  
  Creating a Gemini API Key
&lt;/h2&gt;

&lt;p&gt;To allow our agent to use Gemini models, we need to generate an &lt;strong&gt;API key in Google AI Studio&lt;/strong&gt;. Go to &lt;a href="https://aistudio.google.com/api-keys" rel="noopener noreferrer"&gt;Google AI Studio&lt;/a&gt; and sign in with your Google account.&lt;/p&gt;

&lt;p&gt;Once there, open the &lt;strong&gt;API Keys&lt;/strong&gt; section, select the option to create a new key, and choose the Google Cloud project to associate it with. If you do not yet have an available project, you can create or import one, depending on the options enabled for your account.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftj6thm619osb1a8ei57q.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftj6thm619osb1a8ei57q.png" alt="API Keys in Google AI Studio" width="800" height="636"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fttmzpu6xmc51wjbcn0jt.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fttmzpu6xmc51wjbcn0jt.png" alt="Create Gemini API key" width="504" height="291"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;After generating the key, copy it and confirm that the project has enough quota or billing capacity to use the selected Gemini model.&lt;/p&gt;

&lt;p&gt;With the API key available, open the &lt;strong&gt;.env&lt;/strong&gt; file at the project root and replace the sample value &lt;strong&gt;YOUR_GEMINI_API_KEY&lt;/strong&gt; in the &lt;strong&gt;GOOGLE_API_KEY&lt;/strong&gt; variable with the key generated in Google AI Studio.&lt;/p&gt;

&lt;h2&gt;
  
  
  Configuring Google Drive and Service Account Authentication
&lt;/h2&gt;

&lt;p&gt;To allow our Corporate Policies Assistant to query documents stored in Google Drive, we need to configure an authentication mechanism that gives the application secure access to the files.&lt;/p&gt;

&lt;p&gt;In this exercise, we will use a &lt;strong&gt;Google Cloud service account&lt;/strong&gt;, which represents an identity used by applications and services rather than a conventional user account. This allows the agent to connect to Google Drive and retrieve corporate policies without requiring users to sign in manually every time they ask a question.&lt;/p&gt;

&lt;p&gt;For the demonstration, we will create a dedicated service account, grant it read access to the folder containing the documents, and download its credentials as a JSON file for use by our Python application.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Enable the Google Drive API&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;First, we need to enable the API that allows our application to access the documents stored in Google Drive.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;a href="https://console.cloud.google.com/" rel="noopener noreferrer"&gt;Google Cloud Console&lt;/a&gt; and sign in.&lt;/li&gt;
&lt;li&gt;Select the Google Cloud project you will use for the exercise.&lt;/li&gt;
&lt;li&gt;From the navigation menu, go to &lt;strong&gt;APIs &amp;amp; Services → Library&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Search for &lt;strong&gt;Google Drive API&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Select the API and click &lt;strong&gt;Enable&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;We can also enable it from PowerShell using Google Cloud CLI:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;gcloud&lt;/span&gt; &lt;span class="n"&gt;services&lt;/span&gt; &lt;span class="n"&gt;enable&lt;/span&gt; &lt;span class="n"&gt;drive&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;googleapis&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;com&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;project&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="no"&gt;YOUR_PROJECT_ID&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Replace &lt;strong&gt;YOUR_PROJECT_ID&lt;/strong&gt; with your actual Google Cloud project ID.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Create the Service Account&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Once the API is enabled, we will create the identity our agent will use to access the documents.&lt;/p&gt;

&lt;p&gt;Follow these steps in Google Cloud Console:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Go to &lt;strong&gt;IAM &amp;amp; Admin → Service Accounts&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Create Service Account&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Enter the following sample values:&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Field&lt;/th&gt;
&lt;th&gt;Suggested Value&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Name&lt;/td&gt;
&lt;td&gt;Corporate Policies Drive Reader&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Service account ID&lt;/td&gt;
&lt;td&gt;drive-agent-reader&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Description&lt;/td&gt;
&lt;td&gt;Service account for reading corporate policy documents stored in Google Drive&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The service account email address will follow a format similar to:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;drive-agent-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;Select &lt;strong&gt;Create and Continue&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;In the project role assignment step, you can continue without granting general IAM permissions.&lt;/li&gt;
&lt;li&gt;Finish by clicking &lt;strong&gt;Done&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;In this case, we do not need to assign roles such as Editor or Owner because our agent only needs to access documents in a specific Google Drive folder. Access to those files will be managed directly through Drive sharing permissions.&lt;/p&gt;

&lt;p&gt;Google Cloud allows service accounts to be created without initially granting them IAM roles on the project.&lt;/p&gt;

&lt;p&gt;We can also create the account using PowerShell:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;gcloud&lt;/span&gt; &lt;span class="n"&gt;iam&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;accounts&lt;/span&gt; &lt;span class="n"&gt;create&lt;/span&gt; &lt;span class="n"&gt;drive&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;agent&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;reader&lt;/span&gt; &lt;span class="sb"&gt;`
--display-name="Corporate Policies Drive Reader" `&lt;/span&gt;
&lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"Read corporate policy documents from Google Drive"&lt;/span&gt; &lt;span class="sb"&gt;`
--project=YOUR_PROJECT_ID
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;u&gt;&lt;strong&gt;Configure Google Drive Access Permissions&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;After creating the service account, we must authorize it to access the folder containing the corporate policies.&lt;/p&gt;

&lt;p&gt;In our example, we will have a main Google Drive folder with documents from Human Resources, Finance, Technology, Security, Legal, Procurement, Operations, and Sustainability.&lt;/p&gt;

&lt;p&gt;To grant access:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Open &lt;a href="https://drive.google.com/" rel="noopener noreferrer"&gt;Google Drive&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;Find the main folder containing the corporate policies.&lt;/li&gt;
&lt;li&gt;Right-click it and select &lt;strong&gt;Share&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Enter the email address of the service account created earlier.&lt;/li&gt;
&lt;li&gt;Select the &lt;strong&gt;Viewer&lt;/strong&gt; permission.&lt;/li&gt;
&lt;li&gt;Confirm the sharing settings.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Cuenta:
drive-agent-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
Permiso:
Lector (Viewer)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fp5h5g2v7c6gra3yac0nw.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fp5h5g2v7c6gra3yac0nw.png" alt="Google Drive permissions for the service account" width="515" height="298"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;With this permission, the service account can read available documents within the folder and its subfolders, provided permissions are inherited correctly and no additional restrictions apply. &lt;strong&gt;Edit access is not required&lt;/strong&gt;, because our agent only reads information to answer questions.&lt;/p&gt;

&lt;p&gt;Google Workspace supports sharing files and folders directly with a service account using its email address, without granting administrative privileges.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Generate the service-account.json Credentials File&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Once the service account has been created and authorized, we need to obtain the credentials our Python application will use to authenticate locally.&lt;/p&gt;

&lt;p&gt;Return to Google Cloud Console and follow these steps:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Go to &lt;strong&gt;IAM &amp;amp; Admin → Service Accounts&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Select the &lt;strong&gt;drive-agent-reader&lt;/strong&gt; service account.&lt;/li&gt;
&lt;li&gt;Open the &lt;strong&gt;Keys&lt;/strong&gt; tab.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Add Key → Create New Key&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Select &lt;strong&gt;JSON&lt;/strong&gt; format.&lt;/li&gt;
&lt;li&gt;Click &lt;strong&gt;Create&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Google Cloud will automatically download a JSON file containing the service account credentials. Rename the downloaded file to &lt;strong&gt;service-account.json&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;This file contains information such as the project ID, the service account email address, and a private key used for authentication. Therefore, it must be treated as a sensitive credential.&lt;/p&gt;

&lt;p&gt;Save it inside our project's &lt;strong&gt;credentials&lt;/strong&gt; folder:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Corporate Policies Agent/
├── corporate_agent/
├── corporate_policies/
├── credentials/
│ └── service-account.json
├── app.py
├── .env
└── requirements.txt
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;u&gt;&lt;strong&gt;Configure Credentials in the .env File&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;With the JSON file stored in the &lt;strong&gt;credentials&lt;/strong&gt; folder, we will configure the environment variables our application uses to connect to Google Drive.&lt;/p&gt;

&lt;p&gt;Open .env and complete the relevant section:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 2. LOCAL GOOGLE DRIVE AUTHENTICATION
# ============================================================
DRIVE_AUTH_MODE=service_account_file
DRIVE_SERVICE_ACCOUNT_FILE=credentials/service-account.json
GOOGLE_DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;u&gt;&lt;strong&gt;Verify the Google Drive Connection&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Before implementing the agent, it is advisable to check that the credentials work and we can access the documents.&lt;/p&gt;

&lt;p&gt;Our project includes a test file called &lt;strong&gt;test_drive.py&lt;/strong&gt;, located in the test folder, which validates this connection.&lt;/p&gt;

&lt;p&gt;From the Visual Studio Code PowerShell terminal, with the virtual environment activated, run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;sources_en&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;test&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;test_drive&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This test will allow us to check whether the application can authenticate and access Google Drive. The exact result depends on the checks implemented in the script.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;OUTPUT
Google Drive connection successful
📁 Root folder: Corporate Policies
🆔 ID: YOUR_DRIVE_FOLDER_ID
📚 Files found:
-----------------------------------------------------------------
-----------------------------------------------------------------
✅ Total files found: 0
(.venv) PS C:\Projects\Corporate Policies Agent&amp;gt; python -m test.test_drive
✅ Google Drive connection successful
📁 Root folder: Corporate Policies
🆔 ID: YOUR_DRIVE_FOLDER_ID
📚 Files found:
-----------------------------------------------------------------
📄 en_legal_policies.txt
📄 en_it_policies.txt
📄 en_human_resources_policies.txt
📄 en_finance_policies.txt
-----------------------------------------------------------------
✅ Total files found: 4
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you encounter a 403 Forbidden error, review the service account's permissions on the folder, the API configuration, and project permissions. If you encounter a 404 Not Found error, confirm that the folder ID is correct and the account has access to it.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Security Considerations&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;For this demonstration, we are using a service account JSON file because it simplifies the local environment setup and helps illustrate how authentication between Python and Google Drive works. However, JSON keys are long-lived credentials and are not recommended as the standard authentication mechanism for enterprise applications or production environments.&lt;/p&gt;

&lt;p&gt;In production, managed identities, temporary credentials, and authentication mechanisms that avoid storing private keys in local files are preferable. Google Cloud recommends limiting the use of exportable service account keys and applying appropriate controls throughout their lifecycle.&lt;/p&gt;

&lt;p&gt;With this setup, we will have established the connection between our application and Google Drive, which will act as the knowledge repository for the Corporate Policies Assistant.&lt;/p&gt;

&lt;p&gt;In the following sections, we will use these credentials to implement document reading, chunking, indexing, and the search tool that our agent will invoke through Google ADK.&lt;/p&gt;

&lt;h2&gt;
  
  
  Implementing the RAG System for Document Queries
&lt;/h2&gt;

&lt;p&gt;Now that access to Google Drive is configured, we will implement the component responsible for retrieving the information our agent will use to answer user questions.&lt;/p&gt;

&lt;p&gt;We will use &lt;strong&gt;RAG (Retrieval-Augmented Generation)&lt;/strong&gt;, which supplements Gemini's responses with information retrieved from our corporate documents.&lt;/p&gt;

&lt;p&gt;In this first implementation, we will build an &lt;strong&gt;in-memory lexical RAG&lt;/strong&gt; system without a vector database. The process involves querying Google Drive documents, extracting their content, splitting it into chunks, and building an index to locate the most relevant information for each question.&lt;/p&gt;

&lt;p&gt;All this logic will be implemented in &lt;strong&gt;corporate_agent/drive_rag.py&lt;/strong&gt;, organized into six main sections.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Google Drive Configuration and MIME Types&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 1. CONFIGURACIÓN DE GOOGLE DRIVE Y TIPOS MIME
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the first section, we define the general settings for working with Google Drive, including read-only access (drive.readonly) and the file formats our application can process.&lt;/p&gt;

&lt;p&gt;Supported formats include Google Docs, TXT, Markdown, PDF, and Word (DOCX) files. We also define a list of common words (&lt;em&gt;stopwords&lt;/em&gt;) that will be excluded from searches to improve result relevance.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Text Tokenization and Chunking&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 2. TOKENIZACIÓN Y SEGMENTACIÓN DE TEXTO
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This section prepares document content for subsequent indexing and searching. It contains two functions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;words()&lt;/strong&gt;: converts text into words, normalizes them, and removes common terms that add little value to search.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;split_chunks()&lt;/strong&gt;: splits documents into smaller chunks, retaining some overlap to avoid losing relevant information when dividing the content.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Chunking allows us to retrieve only the sections related to a question rather than sending entire documents to the Gemini model.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Downloading Files and Connecting to Google Drive&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 3. DESCARGA Y CONEXIÓN CON DRIVE
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In this section, we implement the Google Drive connection and document downloads:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;get_drive_service()&lt;/strong&gt;: establishes a connection using the credentials configured in .env. It supports both the service account JSON file for the local environment and ADC authentication, which we will use later in Agent Runtime.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;download_bytes()&lt;/strong&gt;: downloads files in chunks and checks that they do not exceed the maximum allowed size.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This centralizes access to Google Drive and lets us control how much information our application can download.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Folder Traversal and Pagination&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 4. RECORRIDO DE CARPETAS Y PAGINACIÓN
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;strong&gt;list_files()&lt;/strong&gt; function locates the documents available in the Google Drive folder configured for our project.&lt;/p&gt;

&lt;p&gt;It also traverses subfolders, uses pagination to retrieve results, and selects only supported formats while respecting the file limit set in MAX_DRIVE_FILES.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Extracting Text by File Format&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 5. EXTRACCIÓN DE TEXTO POR FORMATO
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Once the documents have been identified, we need to extract their content in a format we can process.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;extract_text()&lt;/strong&gt; function handles this task based on the file type: it exports Google Docs as text, uses pypdf for PDFs, python-docx for Word documents, and directly decodes TXT and Markdown files.&lt;/p&gt;

&lt;p&gt;It is important to note that, in this version, scanned PDFs containing only images cannot be processed correctly, because we would need to add an OCR mechanism.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Chunk Model and RAG Index&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 6. MODELO DE FRAGMENTOS E ÍNDICE RAG
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This final section contains the main indexing and retrieval logic.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;Chunk&lt;/strong&gt; class represents each text fragment and stores information such as the document name, its Google Drive link, and the words it contains.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;DriveKnowledgeBase&lt;/strong&gt; class manages our knowledge base through three main methods:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;__init__()&lt;/strong&gt;: initializes the structures used to store chunks, statistics, and warnings.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;refresh()&lt;/strong&gt;: queries Google Drive documents, extracts their content, and rebuilds the in-memory RAG index.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;search()&lt;/strong&gt;: receives the user's question, identifies the most relevant chunks using a TF-IDF-based lexical score, and returns results along with their sources.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The retrieved chunks will later be used by the agent developed with Google ADK, which will supply them to &lt;strong&gt;Gemini&lt;/strong&gt; as context for generating a grounded response.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;u&gt;Important Considerations&lt;/u&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Although this implementation is sufficient to understand RAG and integrate it with our agent, we should be aware of a few characteristics:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;In-memory indexing:&lt;/strong&gt; processed documents are not stored in a persistent database. Therefore, the index must be rebuilt when needed.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Lexical search:&lt;/strong&gt; retrieval is based on matching words rather than semantic similarity. This means that questions expressed using synonyms may fail to retrieve the expected chunks.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Processing limits:&lt;/strong&gt; we can control the number of documents, their size, and the number of retrieved chunks using the variables configured in .env.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Document security:&lt;/strong&gt; the application can query any documents accessible to its service account. It is important to use an authorized folder and avoid including information that should not be available to agent users.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For our example, this approach lets us understand the entire information retrieval process without adding the complexity of a vector database or additional services.&lt;/p&gt;

&lt;p&gt;With &lt;strong&gt;drive_rag.py&lt;/strong&gt; ready, we now have the component responsible for querying our knowledge base. Next, we will create the agent with Google ADK and integrate this functionality as a tool Gemini can use during conversations.&lt;/p&gt;

&lt;h2&gt;
  
  
  Developing and Configuring the AI Agent with Google ADK
&lt;/h2&gt;

&lt;p&gt;Once our RAG system is implemented, the next step is to develop the agent responsible for interpreting user questions, querying corporate policies, and generating responses using Gemini.&lt;/p&gt;

&lt;p&gt;We will use &lt;strong&gt;Google Agent Development Kit (ADK)&lt;/strong&gt; to define the agent's behavior, integrate tools, and manage interactions with the language model.&lt;/p&gt;

&lt;p&gt;All this logic will be implemented in &lt;strong&gt;corporate_agent/agent.py&lt;/strong&gt;, organized into five main sections.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Project Configuration&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 1. CONFIGURACIÓN DEL PROYECTO
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the first section, we load the environment variables from .env and configure the Gemini model and parameters used by our agent.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;create_agent_model()&lt;/strong&gt; function selects how to connect to Gemini depending on the runtime: through an API key for the local application or through Vertex AI when the agent is deployed to Google Cloud.&lt;/p&gt;

&lt;p&gt;We also configure parameters such as &lt;strong&gt;RAG_TOP_K&lt;/strong&gt;, which sets the maximum number of retrieved chunks, and &lt;strong&gt;RAG_REFRESH_INTERVAL_SECONDS&lt;/strong&gt;, which determines the refresh interval of the index managed by Agent Runtime.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Knowledge Base&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 2. BASE DE CONOCIMIENTO
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This section manages the RAG index implemented earlier in &lt;strong&gt;drive_rag.py&lt;/strong&gt;, allowing retrieved information to be reused without continuously querying Google Drive.&lt;/p&gt;

&lt;p&gt;It contains three main functions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;set_knowledge_base()&lt;/strong&gt;: allows our Streamlit application to provide the agent with a previously loaded RAG index managed by the application itself.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;_cache_is_current()&lt;/strong&gt;: checks whether the index stored in memory remains valid or needs refreshing.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;get_knowledge_base()&lt;/strong&gt;: retrieves the available index and, when appropriate, queries Google Drive again to rebuild it.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This prevents unnecessary downloads and improves response times. In Streamlit, refreshing is controlled manually, whereas in Agent Runtime it can happen automatically when a query arrives after the configured interval has expired.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;RAG Tool for Google ADK&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 3. HERRAMIENTA RAG PARA GOOGLE ADK
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Here, we implement &lt;strong&gt;search_corporate_policies()&lt;/strong&gt;, the tool our agent will use to query corporate information.&lt;/p&gt;

&lt;p&gt;When users ask a question, this function accesses the RAG index, retrieves the most relevant chunks, and returns their content along with the names and links of the original documents.&lt;/p&gt;

&lt;p&gt;It also includes error handling to identify connection, permission, or Google Drive access issues without exposing sensitive information during execution.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Per-Turn Document Search Control&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 4. CONTROL DE CONSULTA DOCUMENTAL POR TURNO
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This section introduces &lt;strong&gt;enforce_search_per_turn()&lt;/strong&gt;, which we use as a Google ADK &lt;em&gt;callback&lt;/em&gt; to control when the search tool must run. Its goal is to ensure that the agent performs a new document search whenever a user submits a question, rather than answering solely from information retrieved earlier in the conversation.&lt;/p&gt;

&lt;p&gt;Once &lt;strong&gt;search_corporate_policies&lt;/strong&gt; has been executed and returned its results, the agent can continue generating a response through Gemini.&lt;/p&gt;

&lt;p&gt;This behavior is particularly useful when corporate policies change and we need to consult up-to-date information.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Defining the Agent with Google ADK&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 5. DEFINICIÓN DEL AGENTE CON GOOGLE ADK
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Finally, we define our main agent using &lt;strong&gt;root_agent = Agent()&lt;/strong&gt;, the central component of the solution.&lt;/p&gt;

&lt;p&gt;In this configuration, we set its key properties:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;name&lt;/strong&gt;: identifies the agent as corporate_policies_assistant.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;model&lt;/strong&gt;: specifies which Gemini model the agent will use to interpret queries and generate answers.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;description&lt;/strong&gt;: briefly explains its purpose within the organization.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;instruction&lt;/strong&gt;: contains the instructions or prompt that determine how the agent should behave, including consulting documents, generating grounded answers, and including references.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;tools&lt;/strong&gt;: registers the search_corporate_policies function as an available tool for the agent.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;before_model_callback&lt;/strong&gt;: adds the mechanism requiring a new document search whenever a user query is received.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The agent's instructions are especially important because they specify that answers must be based on retrieved documents and that the assistant should acknowledge insufficient information rather than make up an answer. They also limit its behavior to corporate policy topics.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Important Considerations&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;With this implementation, our agent integrates &lt;strong&gt;Google ADK, Gemini, and the RAG system&lt;/strong&gt; developed earlier, allowing it to answer questions about policies stored in Google Drive.&lt;/p&gt;

&lt;p&gt;It is important to remember that response quality depends on the information available in the documents and the chunks retrieved during the search. For this reason, we have included instructions to rely on document sources and avoid unsupported answers.&lt;/p&gt;

&lt;p&gt;The design also allows the same agent to run in our local &lt;strong&gt;Streamlit&lt;/strong&gt; application and later in Google Cloud Agent Runtime, mainly by changing the authentication mechanism and model configuration.&lt;/p&gt;

&lt;p&gt;With our agent defined, the next step is to build the &lt;strong&gt;Streamlit&lt;/strong&gt; web interface, where users can ask questions, view answers, and see information about documents and token usage.&lt;/p&gt;

&lt;h2&gt;
  
  
  Developing the Agent's Web Interface with Streamlit
&lt;/h2&gt;

&lt;p&gt;Once our &lt;strong&gt;Google ADK&lt;/strong&gt; agent and its &lt;strong&gt;RAG system&lt;/strong&gt; integration have been implemented, the next step is to build a web interface that allows users to interact with it easily.&lt;/p&gt;

&lt;p&gt;We will use &lt;strong&gt;Streamlit&lt;/strong&gt;, a Python framework for creating web applications without working directly with HTML, JavaScript, or additional frontend frameworks.&lt;/p&gt;

&lt;p&gt;The entire interface logic will be implemented in &lt;strong&gt;app.py&lt;/strong&gt;, located at the project root and organized into eight main sections.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Environment Variables and Project Configuration&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 1. VARIABLES DE ENTORNO Y CONFIGURACIÓN DEL PROYECTO
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the first section, we load the environment variables from .env, import our Google ADK agent, and configure general Streamlit parameters.&lt;/p&gt;

&lt;p&gt;We also define the maximum agent response time and the reference prices used to calculate estimated token costs.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Dashboard Visual Styles&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 2. ESTILOS VISUALES DEL DASHBOARD (TEMA OSCURO)
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This section defines the application's appearance, including colors, typography, cards, and dashboard components.&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;render_dashboard_style()&lt;/strong&gt; function applies custom styles using CSS, while &lt;strong&gt;get_kb()&lt;/strong&gt; loads and keeps the RAG index of Google Drive documents in memory.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Creating Sessions and the Google ADK Runner&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 3. CREACIÓN DE SESIONES Y RUNNER DE GOOGLE ADK
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;strong&gt;init_runner()&lt;/strong&gt; function initializes the components that execute our agent and maintain conversation context.&lt;/p&gt;

&lt;p&gt;We use Google ADK's Runner and InMemorySessionService to process queries and manage conversation sessions.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;u&gt;Measuring Tokens, Costs, and Agent Execution&lt;/u&gt;&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 4. MEDICIÓN DE TOKENS, COSTES Y EJECUCIÓN DEL AGENTE
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This section sends questions to the agent, receives answers, and collects information about Gemini model consumption.&lt;/p&gt;

&lt;p&gt;Its main functions are:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;new_usage_metrics()&lt;/strong&gt;: initializes usage metrics.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;collect_usage()&lt;/strong&gt;: gathers token usage information available in Google ADK events.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;calculate_estimated_cost()&lt;/strong&gt;: calculates the approximate cost of queries.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;render_usage_metrics() and render_session_usage()&lt;/strong&gt;: display metrics for an individual query and the session.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;ask_agent()&lt;/strong&gt;: sends a question to the agent and retrieves the generated answer.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;We also have &lt;strong&gt;select_chat_page()&lt;/strong&gt;, which simplifies navigation to the chatbot.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Footer and Version Information&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 5. PIE DE PÁGINA COMÚN Y DATOS DE VERSIÓN
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;strong&gt;render_footer()&lt;/strong&gt; function adds a shared footer displaying application details, copyright information, and version.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Introduction Page&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 6. PÁGINA DE INTRODUCCIÓN (DISEÑO DASHBOARD)
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;strong&gt;render_intro_page()&lt;/strong&gt; function builds the application's welcome screen.&lt;/p&gt;

&lt;p&gt;It presents the assistant's goal, the technologies used, and a brief explanation of how Google ADK, Gemini, and Google Drive work together.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Chat Page, Index, and Query Tools&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 7. PÁGINA DE CHAT, ÍNDICE Y HERRAMIENTAS DE CONSULTA
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This section contains the &lt;strong&gt;render_chat_page()&lt;/strong&gt; function, which builds the chatbot's main interface.&lt;/p&gt;

&lt;p&gt;On this screen, users can ask questions about corporate policies, view answers and their sources, inspect usage metrics, and manually refresh the documents indexed from Google Drive.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Main Navigation and Entry Point&lt;/strong&gt;&lt;/u&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# ============================================================
# 8. NAVEGACIÓN PRINCIPAL Y PUNTO DE ENTRADA
# ============================================================
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Finally, the &lt;strong&gt;main()&lt;/strong&gt; function controls navigation between screens and coordinates our Streamlit application's execution. This section also contains the main entry point from which the application starts.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Streamlit Visual Configuration with config.toml&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;In addition to the custom styles defined in app.py, we will use &lt;strong&gt;.streamlit/config.toml&lt;/strong&gt; to set the general configuration of our Streamlit application. This file lets us customize visual elements such as the theme, primary colors, background, and typography while keeping these preferences separate from the Python code. Our project will use a dark appearance (&lt;em&gt;Dark Mode&lt;/em&gt;), supplemented with the CSS styles defined in &lt;strong&gt;render_dashboard_style()&lt;/strong&gt;. In this way, we can maintain a consistent interface and easily change its appearance without affecting the agent logic or its Google ADK and Gemini integrations.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Final Considerations&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;By implementing app.py, we complete the integration of the solution's main components: &lt;strong&gt;Streamlit&lt;/strong&gt; as the web interface, &lt;strong&gt;Google ADK&lt;/strong&gt; to run the agent, &lt;strong&gt;Gemini&lt;/strong&gt; to generate answers, and &lt;strong&gt;Google Drive&lt;/strong&gt; as the document repository.&lt;/p&gt;

&lt;p&gt;We have also added features such as session management, manual RAG index refresh, and usage metrics, allowing us to evaluate the assistant's behavior during testing.&lt;/p&gt;

&lt;p&gt;We now have everything needed to run the &lt;strong&gt;Corporate Policies Assistant&lt;/strong&gt; locally and start submitting our first queries.&lt;/p&gt;

&lt;h2&gt;
  
  
  Running and Testing the Agent Locally
&lt;/h2&gt;

&lt;p&gt;With the solution's components developed, we can now launch the &lt;strong&gt;Corporate Policies Assistant&lt;/strong&gt; and verify its behavior.&lt;/p&gt;

&lt;p&gt;We will test it in three ways: through our custom &lt;strong&gt;Streamlit&lt;/strong&gt; interface, the &lt;strong&gt;ADK Web&lt;/strong&gt; development interface, and directly from the &lt;strong&gt;Google ADK command-line interface (CLI)&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Run the Application with Streamlit&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Streamlit will be our main interface because it provides a chatbot for interacting with the agent and displays additional information, such as indexed documents and usage metrics.&lt;/p&gt;

&lt;p&gt;Although both versions are in the same repository, we can run them independently using the same Python virtual environment.&lt;/p&gt;

&lt;p&gt;To start the &lt;strong&gt;English version&lt;/strong&gt;, run the following from the project root:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;streamlit&lt;/span&gt; &lt;span class="n"&gt;run&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="n"&gt;sources_en&lt;/span&gt;\&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;py&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To start the &lt;strong&gt;Spanish version&lt;/strong&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;python&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="n"&gt;streamlit&lt;/span&gt; &lt;span class="n"&gt;run&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="n"&gt;sources_es&lt;/span&gt;\&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;py&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;We can also run both applications simultaneously on ports 8501 and 8502, respectively. Each version will use its own .env configuration, instructions, and configured Google Drive documents.&lt;/p&gt;

&lt;p&gt;This setup allows us to work with two language versions of the same solution while keeping their components separate and making it easier to evolve toward &lt;strong&gt;Google Cloud Agent Runtime and Gemini Enterprise&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Once the server has started, open the following address in your browser: &lt;a href="http://localhost:8501" rel="noopener noreferrer"&gt;&lt;strong&gt;http://localhost:8501&lt;/strong&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;From the application, we can ask questions about corporate policies, view the cited sources, and manually refresh the index of documents stored in Google Drive.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fwiki-cloud.co%2Fwp-content%2Fuploads%2F2026%2F11%2Farticle_image_build_ai_agent_with_google_adk_05.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fwiki-cloud.co%2Fwp-content%2Fuploads%2F2026%2F11%2Farticle_image_build_ai_agent_with_google_adk_05.gif" alt="Streamlit assistant interface" width="480" height="443"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Run the Agent from ADK Web&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Google ADK&lt;/strong&gt; includes a development web interface that allows us to interact directly with agents, review their responses, and observe tool execution. From the project root, run:&lt;/p&gt;

&lt;p&gt;To start the &lt;strong&gt;English version&lt;/strong&gt;, run the following from the project root:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;adk&lt;/span&gt; &lt;span class="n"&gt;web&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;port&lt;/span&gt; &lt;span class="mi"&gt;8000&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="n"&gt;sources_en&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To start the &lt;strong&gt;Spanish version&lt;/strong&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;adk&lt;/span&gt; &lt;span class="n"&gt;web&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;port&lt;/span&gt; &lt;span class="mi"&gt;8001&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="n"&gt;sources_es&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then open: &lt;a href="http://localhost:8000" rel="noopener noreferrer"&gt;&lt;strong&gt;http://localhost:8000&lt;/strong&gt;&lt;/a&gt; or &lt;a href="http://localhost:8001" rel="noopener noreferrer"&gt;&lt;strong&gt;http://localhost:8001&lt;/strong&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;In the interface, select our &lt;strong&gt;corporate_agent&lt;/strong&gt; and start asking questions.&lt;/p&gt;

&lt;p&gt;This mode is especially useful during development because it lets us inspect interactions with Gemini and see when the agent runs the &lt;strong&gt;search_corporate_policies&lt;/strong&gt; tool.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg88ku04q15qdj4t9zkx6.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg88ku04q15qdj4t9zkx6.png" alt="Running the agent in ADK Web" width="800" height="741"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://wiki-cloud.co/wp-content/uploads/2026/11/article_image_build_ai_agent_with_google_adk_06.gif" rel="noopener noreferrer"&gt;View Animated GIF&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Run the Agent from the Command Line&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;We can also interact with our agent directly from PowerShell, without a graphical interface. To do so, run:&lt;/p&gt;

&lt;p&gt;To start the &lt;strong&gt;English version&lt;/strong&gt;, run the following from the project root:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;adk&lt;/span&gt; &lt;span class="n"&gt;run&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="n"&gt;sources_en&lt;/span&gt;\&lt;span class="n"&gt;corporate_agent&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To start the &lt;strong&gt;Spanish version&lt;/strong&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;adk&lt;/span&gt; &lt;span class="n"&gt;run&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="n"&gt;sources_es&lt;/span&gt;\&lt;span class="n"&gt;corporate_agent&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This command starts an interactive session where we can type questions and receive answers directly in the terminal.&lt;/p&gt;

&lt;p&gt;It is a simple alternative for quick testing, checking agent behavior, and identifying errors during development.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fp7e5axso9ly7z3yo3n2a.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fp7e5axso9ly7z3yo3n2a.gif" alt="Agent in the command line" width="760" height="558"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;u&gt;&lt;strong&gt;Validate the Agent's Behavior&lt;/strong&gt;&lt;/u&gt;&lt;/p&gt;

&lt;p&gt;Regardless of how we run it, we can ask questions about the documents stored in Google Drive:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;How many vacation days do employees receive each year?&lt;/li&gt;
&lt;li&gt;What is the company's remote work policy?&lt;/li&gt;
&lt;li&gt;How can I request reimbursement for an expense?&lt;/li&gt;
&lt;li&gt;What does the recycling and sustainability policy say?&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;During these tests, we should verify that the agent queries documents using &lt;strong&gt;search_corporate_policies&lt;/strong&gt;, generates coherent responses, and provides references to the original sources.&lt;/p&gt;

&lt;p&gt;It is also advisable to ask a question that the documents cannot answer to verify that the agent acknowledges when it lacks sufficient information.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Note:&lt;/strong&gt; Streamlit, ADK Web, and ADK CLI all allow interaction with the same agent but offer different experiences. Streamlit is our custom interface, while ADK Web and ADK CLI are primarily intended for development and testing. The latter two do not replace a production-ready enterprise interface.&lt;/p&gt;

&lt;p&gt;To stop any of the servers or sessions, press &lt;strong&gt;Ctrl + C&lt;/strong&gt; in the corresponding terminal.&lt;/p&gt;

&lt;p&gt;With these tests, we will have completed the local implementation of our &lt;strong&gt;Corporate Policies Assistant&lt;/strong&gt;. In the second part of this series, we will reuse the agent to deploy it to &lt;strong&gt;Google Cloud Agent Runtime&lt;/strong&gt; and make it available to users through &lt;strong&gt;Gemini Enterprise&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusions
&lt;/h2&gt;

&lt;p&gt;Throughout this exercise, we developed a &lt;strong&gt;Corporate Policies Assistant&lt;/strong&gt; using Google ADK, Gemini, Google Drive, and Streamlit. With a simple RAG-based architecture, we connected an artificial intelligence agent to enterprise documents, enabling it to query information, retrieve relevant content, and generate natural-language answers accompanied by their sources. We also explored key aspects of agent development, including tool integration, session management, model instructions, and building a web interface.&lt;/p&gt;

&lt;p&gt;Developing AI agents offers organizations an opportunity to transform how employees access information and perform everyday tasks. Solutions like the one we built can reduce the time spent searching for documents, improve access to corporate knowledge, and serve as a starting point for automating more complex processes. However, adoption also requires attention to security, access permissions, information quality, and oversight of generated responses. This exercise helps us understand the foundations of agentic AI and how to begin applying these capabilities to real enterprise scenarios.&lt;/p&gt;

&lt;p&gt;In the &lt;strong&gt;second part of this series&lt;/strong&gt;, we will take the next step: deploying our agent to &lt;strong&gt;Google Cloud Agent Runtime&lt;/strong&gt; and integrating it with &lt;strong&gt;Gemini Enterprise&lt;/strong&gt;, moving from a local application to a solution accessible through an enterprise platform.&lt;/p&gt;

&lt;h2&gt;
  
  
  Resources
&lt;/h2&gt;

&lt;p&gt;To learn more about the technologies used in this exercise, see the following official documentation:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://adk.dev/get-started/python/" rel="noopener noreferrer"&gt;Google Agent Development Kit (ADK)&lt;/a&gt;:&lt;/strong&gt; an introduction to agent development, tools, and execution with Python.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://aistudio.google.com/" rel="noopener noreferrer"&gt;Google AI Studio&lt;/a&gt;:&lt;/strong&gt; a platform for experimenting with Gemini models and obtaining an API key.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://ai.google.dev/gemini-api/docs" rel="noopener noreferrer"&gt;Gemini API&lt;/a&gt;:&lt;/strong&gt; model, SDK, and API configuration documentation.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://developers.google.com/workspace/drive/api/quickstart/python" rel="noopener noreferrer"&gt;Google Drive API&lt;/a&gt;:&lt;/strong&gt; integrating Python applications with documents stored in Google Drive.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://docs.streamlit.io/get-started" rel="noopener noreferrer"&gt;Streamlit&lt;/a&gt;:&lt;/strong&gt; building interactive web applications with Python.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://cloud.google.com/use-cases/retrieval-augmented-generation?hl=es" rel="noopener noreferrer"&gt;Introduction to RAG — Google Cloud&lt;/a&gt;:&lt;/strong&gt; concepts and operation of retrieval-augmented generation.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;&lt;a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/runtime/quickstart-adk" rel="noopener noreferrer"&gt;Google Cloud Agent Runtime&lt;/a&gt;:&lt;/strong&gt; deploying and running Google ADK agents on Google Cloud.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;I hope you find this useful!!!&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Follow us:&lt;/strong&gt;&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;👉&lt;a href="http://wiki-cloud.co/" rel="noopener noreferrer"&gt;Wiki Cloud&lt;/a&gt; | 👉&lt;a href="https://x.com/johnbulla" rel="noopener noreferrer"&gt;X&lt;/a&gt; | 👉&lt;a href="https://www.linkedin.com/in/johnbulla" rel="noopener noreferrer"&gt;LinkedIn&lt;/a&gt; | 👉&lt;a href="https://github.com/johnbulla" rel="noopener noreferrer"&gt;Github&lt;/a&gt; | 👉&lt;a href="https://www.youtube.com/user/johnbulla" rel="noopener noreferrer"&gt;Youtube&lt;/a&gt;&lt;/p&gt;
&lt;/blockquote&gt;

</description>
      <category>ai</category>
      <category>agents</category>
      <category>cloud</category>
      <category>googlecloud</category>
    </item>
    <item>
      <title>Which Model Should You Use? Frontier, Hosted or Local? It Depends.</title>
      <dc:creator>xbill</dc:creator>
      <pubDate>Sat, 14 Nov 2026 22:05:33 +0000</pubDate>
      <link>https://dev.to/gde/which-model-should-you-use-frontier-hosted-or-local-it-depends-2n45</link>
      <guid>https://dev.to/gde/which-model-should-you-use-frontier-hosted-or-local-it-depends-2n45</guid>
      <description>&lt;p&gt;This article provides a roadmap for choosing where to run a model: on your own machine, through a hosted API, on Cloud Run, or on an accelerator you rent. Every figure comes from a measured run in gemma4-dev, which serves Gemma 4 on more than a hundred hardware and engine combinations and now carries five Gemini API models as sibling rigs.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/xbill9/gemma4-dev" rel="noopener noreferrer"&gt;https://github.com/xbill9/gemma4-dev&lt;/a&gt;&lt;/p&gt;




&lt;h4&gt;
  
  
  The New Gemini Models in One Table
&lt;/h4&gt;

&lt;p&gt;Gemini 4 Hydrogen, Carbon and Argon arrived on the Gemini API next to 3.5 Flash-Lite, 3.8 Flash and Gemma 4. On 2026-11-14 all seven ran through the same Gemini API endpoint, started together, with the same GSM8K (1,319 math word problems) and BFCL simple (400 function calls) questions and scoring, with thinking set as low as each model accepts:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;GSM8K&lt;/th&gt;
&lt;th&gt;BFCL simple&lt;/th&gt;
&lt;th&gt;Cost, both tasks&lt;/th&gt;
&lt;th&gt;Output price, per 1M tokens&lt;/th&gt;
&lt;th&gt;GSM8K median per request&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 31B&lt;/td&gt;
&lt;td&gt;0.9735&lt;/td&gt;
&lt;td&gt;🥇 0.9675&lt;/td&gt;
&lt;td&gt;🥇 free tier&lt;/td&gt;
&lt;td&gt;free tier only&lt;/td&gt;
&lt;td&gt;8.96 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 26B&lt;/td&gt;
&lt;td&gt;0.9742&lt;/td&gt;
&lt;td&gt;0.9575&lt;/td&gt;
&lt;td&gt;🥇 free tier&lt;/td&gt;
&lt;td&gt;free tier only&lt;/td&gt;
&lt;td&gt;8.16 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.5 Flash-Lite&lt;/td&gt;
&lt;td&gt;0.9629&lt;/td&gt;
&lt;td&gt;0.9350&lt;/td&gt;
&lt;td&gt;$0.92&lt;/td&gt;
&lt;td&gt;$2.50&lt;/td&gt;
&lt;td&gt;🥇 1.10 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.8 Flash&lt;/td&gt;
&lt;td&gt;0.9788&lt;/td&gt;
&lt;td&gt;0.9400&lt;/td&gt;
&lt;td&gt;$1.81&lt;/td&gt;
&lt;td&gt;$3.75&lt;/td&gt;
&lt;td&gt;3.79 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Hydrogen&lt;/td&gt;
&lt;td&gt;0.9803&lt;/td&gt;
&lt;td&gt;0.9550&lt;/td&gt;
&lt;td&gt;$5.02&lt;/td&gt;
&lt;td&gt;$7.50&lt;/td&gt;
&lt;td&gt;🥈 2.84 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Carbon&lt;/td&gt;
&lt;td&gt;0.9803&lt;/td&gt;
&lt;td&gt;0.9600&lt;/td&gt;
&lt;td&gt;$4.02&lt;/td&gt;
&lt;td&gt;$10.00&lt;/td&gt;
&lt;td&gt;7.34 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Argon&lt;/td&gt;
&lt;td&gt;🥇 0.9841&lt;/td&gt;
&lt;td&gt;🥇 0.9675&lt;/td&gt;
&lt;td&gt;$3.46&lt;/td&gt;
&lt;td&gt;$10.00&lt;/td&gt;
&lt;td&gt;7.63 s&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Hydrogen, Carbon and Argon are ahead of Gemma 4 31B on GSM8K, with the 95% range of the difference above zero, and level with it on BFCL. Output prices include thinking tokens, and thinking decides the bill. On Hydrogen and 3.8 Flash it cannot be turned off: Hydrogen has the lowest Gemini 4 price, thought on every problem at its lowest setting, and cost the most. It is also the fastest Gemini 4 model, about 2.7 times quicker per problem than Argon. The times come from all seven sharing one connection at once. Carbon and Argon double in price on 2026-12-01. The method is in the companion article, &lt;em&gt;Gemini 4 Hydrogen, Carbon and Argon Against Gemma 4&lt;/em&gt;.&lt;/p&gt;




&lt;h4&gt;
  
  
  The Options
&lt;/h4&gt;

&lt;p&gt;Four ways to run a model, each measured in this repo:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Local:&lt;/strong&gt; a GPU or CPU you own. Measured on an RTX 3050 OEM (8 GB desktop card), a GTX 1650 Ti (4 GB laptop card) and an Intel i7-10750H laptop CPU.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hosted API:&lt;/strong&gt; someone else's server, reached with a key. Measured on the Gemini API (the five Gemini models) and AMD Token Lab (Gemma 4 31B, free with the AMD AI Developer Program).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cloud Run:&lt;/strong&gt; Google's serverless containers with one NVIDIA L4, serving Gemma 4 E2B on vLLM.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Your own accelerator:&lt;/strong&gt; a rented machine you start and stop. Measured on a TPU v5e (one chip and four), an EC2 G6 with one L4, and an AMD MI300X on DigitalOcean.&lt;/li&gt;
&lt;/ul&gt;




&lt;h4&gt;
  
  
  Option 1 — Local
&lt;/h4&gt;

&lt;p&gt;The RTX 3050 serves Gemma 4 E2B on six engines. One request at a time without a drafter they run from 61.9 tok/s (LiteRT-LM) to 121.1 tok/s (vLLM); with Google's speculative-decoding drafter vLLM reaches 230.5 tok/s. Under load, with 64 requests at once of 128 tokens in and 512 out, SGLang delivers 1,711.3 tok/s in total and vLLM 1,651.2.&lt;/p&gt;

&lt;p&gt;The same card holds the larger models one request at a time: 12B at 56.4 tok/s with its drafter, 26B A4B at 40.6 tok/s on code with its experts in system RAM, and 31B at 4.0 tok/s with two thirds of it on the CPU. Quality rises with size: GSM8K 0.9014 (E2B), 0.9629 (12B), 0.9735 (31B).&lt;/p&gt;

&lt;p&gt;The 1650 Ti laptop card decodes E2B at 73.75 tok/s for one request and peaks at 164 tok/s through its server at 16 requests. The laptop CPU decodes 16.71 to 18.86 tok/s.&lt;/p&gt;

&lt;p&gt;Setup: llama.cpp is ready 4 s after start, vLLM 48 s. vLLM's first start compiles for about 3.5 minutes. The hardware is already paid for, and nothing is billed per hour.&lt;/p&gt;




&lt;h4&gt;
  
  
  Option 2 — Hosted API
&lt;/h4&gt;

&lt;p&gt;&lt;strong&gt;Gemini API.&lt;/strong&gt; A key and an HTTP call. The Gemini models and Gemma 4 26B and 31B answer the OpenAI chat format at &lt;code&gt;/v1beta/openai/chat/completions&lt;/code&gt;. Estimated from the token counts returned and list prices, a full 1,319-problem GSM8K run cost $0.87 on Flash-Lite, $1.66 on 3.8 Flash, $3.15 on Argon, $3.70 on Carbon and $4.51 on Hydrogen. Gemma 4 is on the free tier only, with paid use not available, and its free-tier rate limit answered three requests in the GSM8K and BFCL runs with HTTP 429 after every retry.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AMD Token Lab.&lt;/strong&gt; Gemma 4 31B on an SGLang router on AMD GPUs, free with the AMD AI Developer Program: 10 points for 30 days, with Gemma 4 31B at 0.035 points per million input tokens and 0.07 per million output. One request at a time decoded at 2.0 to 7.6 tok/s on the shared service, with up to 5 s before the first token. The limit is 128 requests at once across all users; over that, the reply is HTTP 429.&lt;/p&gt;




&lt;h4&gt;
  
  
  Option 3 — Cloud Run
&lt;/h4&gt;

&lt;p&gt;One L4 GPU in us-east4 with 8 vCPU and 32 GiB, Gemma 4 E2B on vLLM. Output rose with concurrency to 188.46 tok/s at 4 requests and stayed there at 8 (189.53), because the service was deployed with &lt;code&gt;--concurrency=4&lt;/code&gt;; more users means more instances. The same L4 on EC2 reached 360.17 tok/s at 8.&lt;/p&gt;

&lt;p&gt;At list price the instance costs $1.4209 an hour, which works out to $7.95 per million output tokens at one request and $2.08 at eight. Cloud Run scales to zero by default, so an idle service costs nothing and the next request waits for a cold GPU start; the startup check waits 180 s before its first look. The weights load from Cloud Storage.&lt;/p&gt;




&lt;h4&gt;
  
  
  Option 4 — Your Own Accelerator
&lt;/h4&gt;

&lt;p&gt;&lt;strong&gt;TPU v5e, one chip.&lt;/strong&gt; Gemma 4 E2B on vLLM: 143.9 tok/s for one request, 1,689.1 tok/s at 64 requests (128 in, 512 out), GSM8K 0.9007 and BFCL 0.920. Flex-start costs $0.60 per chip-hour, about $0.089 per million output tokens at full batching and $1.31 at one request. Capacity came within two to five minutes in &lt;code&gt;us-west4-a&lt;/code&gt;, and the engine took 12.6 to 14.1 minutes to start on most rigs, most of it compiling (27.2 on one).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;TPU v5e, four chips.&lt;/strong&gt; E2B as four one-chip engines reaches 7,788 tok/s at 64 requests and 14,189 at 256. The 12B fits with 122,624 tokens of context cache, against 9,728 on one chip.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;EC2 G6, one L4.&lt;/strong&gt; vLLM at 132.8 to 140.4 tok/s for one request and 3,715.7 tok/s at 64; with the drafter, 4,516.3. A spot g6.2xlarge measured on an older vLLM cost $0.9412 an hour, $0.73 per million output tokens at eight requests.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AMD MI300X.&lt;/strong&gt; 192 GB on one card: E2B at 340.4 tok/s for one request and 10,293.6 tok/s at 64 (128 tokens of context). $1.99 an hour, billed while powered off too: $0.054 per million output tokens at 64 clients and $1.624 for a single stream.&lt;/p&gt;




&lt;h4&gt;
  
  
  🔎 Tip: Price Per Hour Becomes Price Per Token Only Under Load
&lt;/h4&gt;

&lt;p&gt;Every rented option above has two prices per million tokens, one at a single request and one at full batching: Cloud Run $7.95 and $2.08, TPU v5e $1.31 and $0.089, MI300X $1.624 and $0.054. A machine that serves one user at a time costs about what a hosted API charges, or more. A per-token API charges the same at any load.&lt;/p&gt;




&lt;h4&gt;
  
  
  Compare and Contrast
&lt;/h4&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Local 3050&lt;/th&gt;
&lt;th&gt;Gemini API&lt;/th&gt;
&lt;th&gt;Token Lab&lt;/th&gt;
&lt;th&gt;Cloud Run L4&lt;/th&gt;
&lt;th&gt;TPU v5e-1&lt;/th&gt;
&lt;th&gt;MI300X&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Users at once&lt;/td&gt;
&lt;td&gt;64 measured&lt;/td&gt;
&lt;td&gt;8 measured&lt;/td&gt;
&lt;td&gt;128 shared&lt;/td&gt;
&lt;td&gt;4 per instance&lt;/td&gt;
&lt;td&gt;64 measured&lt;/td&gt;
&lt;td&gt;64 measured&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Most output, tok/s&lt;/td&gt;
&lt;td&gt;1,711.3&lt;/td&gt;
&lt;td&gt;not measured&lt;/td&gt;
&lt;td&gt;not measured&lt;/td&gt;
&lt;td&gt;189.53&lt;/td&gt;
&lt;td&gt;1,689.1&lt;/td&gt;
&lt;td&gt;🥇 10,293.6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One request, tok/s&lt;/td&gt;
&lt;td&gt;230.5&lt;/td&gt;
&lt;td&gt;not measured&lt;/td&gt;
&lt;td&gt;2.0–7.6&lt;/td&gt;
&lt;td&gt;49.63&lt;/td&gt;
&lt;td&gt;143.9&lt;/td&gt;
&lt;td&gt;340.4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cost&lt;/td&gt;
&lt;td&gt;🥇 card you own&lt;/td&gt;
&lt;td&gt;per token&lt;/td&gt;
&lt;td&gt;🥇 free&lt;/td&gt;
&lt;td&gt;$1.4209/hr&lt;/td&gt;
&lt;td&gt;$0.60/hr&lt;/td&gt;
&lt;td&gt;$1.99/hr&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Best GSM8K&lt;/td&gt;
&lt;td&gt;0.9735 (31B)&lt;/td&gt;
&lt;td&gt;🥇 0.9841 (Argon)&lt;/td&gt;
&lt;td&gt;not measured&lt;/td&gt;
&lt;td&gt;not measured&lt;/td&gt;
&lt;td&gt;0.9007 (E2B)&lt;/td&gt;
&lt;td&gt;not measured&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ready in&lt;/td&gt;
&lt;td&gt;🥇 4 s&lt;/td&gt;
&lt;td&gt;🥇 a key&lt;/td&gt;
&lt;td&gt;🥇 a key&lt;/td&gt;
&lt;td&gt;minutes, cold start&lt;/td&gt;
&lt;td&gt;12–14 min&lt;/td&gt;
&lt;td&gt;minutes&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h4&gt;
  
  
  The Roadmap
&lt;/h4&gt;

&lt;p&gt;Pick by the axis that matters most, then check the others.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;By number of users.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Users at once&lt;/th&gt;
&lt;th&gt;Start with&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1, yourself&lt;/td&gt;
&lt;td&gt;Local card, or the Gemini or Token Lab free tier&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2–10&lt;/td&gt;
&lt;td&gt;Gemini API, or Cloud Run with more instances&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10–64&lt;/td&gt;
&lt;td&gt;A batching engine on your own card (vLLM, SGLang), a TPU v5e-1, or an L4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hundreds&lt;/td&gt;
&lt;td&gt;TPU v5e-4 as four engines, or an MI300X&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;By cost.&lt;/strong&gt; Free first: your own card, Token Lab, and the Gemini free tier, which carries Gemma 4 26B and 31B, Flash-Lite, 3.8 Flash and Hydrogen. For paid use with light or uneven traffic, pay per token: both tests cost $0.92 on Flash-Lite and $3.46 on Argon. Hydrogen thought on every request and 3.8 Flash on most; Google's docs say reasoning cannot be turned off on Gemini 3 or Gemini 4 models, and the API runs &lt;code&gt;none&lt;/code&gt; as &lt;code&gt;low&lt;/code&gt;. Compare models by cost per answer. From 2026-12-01, when Carbon and Argon go to $4 / $20, this run costs $6.93 on Argon and $5.02 on Hydrogen, by arithmetic from list prices. A rented machine wins only when it is kept busy, which brings TPU v5e to $0.089 and MI300X to $0.054 per million output tokens.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;By speed.&lt;/strong&gt; On a hosted API, Flash-Lite answered a GSM8K problem in 1.10 s and Hydrogen in 2.84 s; Gemma 4 on the Gemini API took 8 to 9 s. For one user, a local card with a drafter (230.5 tok/s on the 3050) or an MI300X (340.4). For many users, the MI300X or four TPU v5e chips. Cloud Run as deployed here stops at 189.53 tok/s per instance.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;By accuracy.&lt;/strong&gt; Gemini 4 Argon leads GSM8K at 0.9841, and Argon and Gemma 4 31B lead BFCL at 0.9675, on short problems with thinking at its lowest setting. For hard, multi-step work Google calls Carbon "our strongest frontier model"; that case was not measured here. Where a model runs did not change its score: Gemma 4 31B answered 1,284 of 1,319 GSM8K problems through the Gemini API and 1,284 on an RTX 3050 with llama.cpp, differing on 8 problems. Model size matters more than where it runs: E2B scored 0.8954 to 0.9030 on GSM8K across six engines on the RTX 3050, the L4 and TPU v5e, and the 31B 0.9735.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;By ease of use.&lt;/strong&gt; A hosted API needs a key. A local card needs a driver and an engine, and llama.cpp is ready in seconds. Cloud Run needs a container and a deploy and then scales on its own. A rented accelerator needs capacity, a 12.6 to 14.1 minute engine start on TPU, and someone to turn it off.&lt;/p&gt;




&lt;h4&gt;
  
  
  So, Which One?
&lt;/h4&gt;

&lt;p&gt;Start hosted with Gemma 4 31B on the Gemini free tier: it tied the best BFCL score and costs nothing. If the task needs the best math scores, move to Gemini 4 Argon. If the task needs Gemma 4 for its open weights, privacy or offline use, run it on your own card, 12B or 31B on 8 GB. Move to Cloud Run when a few users need an always-reachable endpoint without managing a machine. Move to a TPU v5e or an MI300X when traffic is steady enough to keep it busy, because that is where the per-token cost falls below every API.&lt;/p&gt;




&lt;h4&gt;
  
  
  Summary
&lt;/h4&gt;

&lt;p&gt;The goal of this article was to map where each way of running a model fits. The key to the solution was a single repo that measures local cards, hosted APIs, Cloud Run and rented accelerators with the same engines, scoring script and questions. The results were:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;🟢 Gemini 4 Argon has the best GSM8K score measured, 0.9841; Argon and Gemma 4 31B lead BFCL at 0.9675.&lt;/li&gt;
&lt;li&gt;🟢 Gemma 4 31B scored the same 1,284 of 1,319 on GSM8K through the Gemini API and on an 8 GB RTX 3050.&lt;/li&gt;
&lt;li&gt;🟢 Gemma 4 31B is free on the Gemini API and tied Argon on BFCL; Argon cost $3.46 for both tests.&lt;/li&gt;
&lt;li&gt;🟢 A busy MI300X or TPU v5e serves Gemma 4 E2B at $0.054 and $0.089 per million output tokens.&lt;/li&gt;
&lt;li&gt;🟢 AMD Token Lab and the Gemini free tier cost nothing to start.&lt;/li&gt;
&lt;li&gt;⚠️ A rented machine at one request costs $1.31 (TPU v5e) to $7.95 (Cloud Run) per million output tokens.&lt;/li&gt;
&lt;li&gt;⚠️ Cloud Run as deployed caps one instance at 4 requests, 189.53 tok/s.&lt;/li&gt;
&lt;li&gt;❌ Token Lab's shared endpoint decoded one request at 2.0 to 7.6 tok/s.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Scope: figures come from separate runs between 2026-09-03 and 2026-11-14 in gemma4-dev, on different engine versions and days; each is quoted from its run's report, and ratios between runs on different hardware are indicative. Prices are list prices on the date each run recorded them. Accuracy was measured on GSM8K and BFCL simple only, and not on Cloud Run, Token Lab or the MI300X; the throughput figures are Gemma 4 E2B unless a size is named. Gemini API throughput under load was not measured.&lt;/p&gt;

&lt;p&gt;The strategy for choosing where to run Gemma 4 and Gemini was validated with an incremental step by step approach.&lt;/p&gt;




&lt;h4&gt;
  
  
  References
&lt;/h4&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://github.com/xbill9/gemma4-dev" rel="noopener noreferrer"&gt;gemma4-dev on GitHub&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/xbill9/gemma4-dev/tree/main/docs/gemini-vs-gemma/evidence" rel="noopener noreferrer"&gt;Evidence for this article&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aistudio.google.com/docs/pricing" rel="noopener noreferrer"&gt;Gemini API pricing&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://notebooks.amd.com/tokenlab" rel="noopener noreferrer"&gt;AMD Token Lab&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://cloud.google.com/run/docs/configuring/services/gpu" rel="noopener noreferrer"&gt;Cloud Run GPUs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://cloud.google.com/tpu" rel="noopener noreferrer"&gt;Cloud TPU&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/vllm-project/vllm" rel="noopener noreferrer"&gt;vLLM&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/ggml-org/llama.cpp" rel="noopener noreferrer"&gt;llama.cpp&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://huggingface.co/collections/google/gemma-4" rel="noopener noreferrer"&gt;Gemma 4 on Hugging Face&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Hope you enjoyed it!&lt;/p&gt;

</description>
      <category>gemma</category>
      <category>gemini</category>
      <category>googlecloud</category>
      <category>ai</category>
    </item>
    <item>
      <title>Gemini 4 or Gemma 4? It Depends.</title>
      <dc:creator>xbill</dc:creator>
      <pubDate>Sat, 14 Nov 2026 22:04:04 +0000</pubDate>
      <link>https://dev.to/gde/gemini-4-or-gemma-4-it-depends-2o18</link>
      <guid>https://dev.to/gde/gemini-4-or-gemma-4-it-depends-2o18</guid>
      <description>&lt;p&gt;This article provides a step by step guide to comparing the new Gemini 4 models with Gemma 4 on equal terms. Seven models, Gemma 4 26B and 31B, Gemini 3.5 Flash-Lite and 3.8 Flash, and Gemini 4 Hydrogen, Carbon and Argon, run through the same Gemini API endpoint with the same questions, settings and scoring, started at the same moment.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/xbill9/gemma4-dev/tree/main/gemini-api-google-hydrogen4" rel="noopener noreferrer"&gt;https://github.com/xbill9/gemma4-dev/tree/main/gemini-api-google-hydrogen4&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The scores: on 1,319 GSM8K math problems Argon scored 0.9841, Hydrogen and Carbon 0.9803, 3.8 Flash 0.9788, Gemma 4 26B 0.9742, Gemma 4 31B 0.9735 and 3.5 Flash-Lite 0.9629. On 400 BFCL function calls Argon and Gemma 4 31B tied at 0.9675. Gemma 4 ran free; the Gemini runs cost $0.92 to $5.02. Hydrogen answered fastest of the Gemini 4 models, 2.84 s per GSM8K problem against 7.63 s for Argon.&lt;/p&gt;

&lt;p&gt;The surprise is in the cost, and it takes the whole picture to see it. Hydrogen is the cheapest Gemini 4 model per token, $7.50 per million output tokens against $10 for Carbon and Argon, and it cost the most per run, $5.02 against $3.46 for Argon. Its thinking eats the token budget: Google's docs say reasoning cannot be turned off on Gemini 4 models, it ran on all 1,319 GSM8K problems at the lowest setting, and it was 55% of the GSM8K bill. Price per token, tokens per answer and thinking per answer together set what a model costs.&lt;/p&gt;




&lt;h4&gt;
  
  
  What Are the New Models?
&lt;/h4&gt;

&lt;p&gt;Gemini 4 Hydrogen, Carbon and Argon are on the Gemini API next to the 3.x Flash models and Gemma 4. Google's pricing page, saved on 2026-11-14 (paid tier, USD per million tokens; output includes thinking tokens):&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;Input&lt;/th&gt;
&lt;th&gt;Output&lt;/th&gt;
&lt;th&gt;Free tier&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;gemma-4-31b-it&lt;/code&gt;, &lt;code&gt;gemma-4-26b-a4b-it&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;free tier only&lt;/td&gt;
&lt;td&gt;free tier only&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;gemini-3.5-flash-lite&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;$0.30&lt;/td&gt;
&lt;td&gt;$2.50&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;gemini-3.8-flash&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;$0.75&lt;/td&gt;
&lt;td&gt;$3.75&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;gemini-4-hydrogen&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;$1.50&lt;/td&gt;
&lt;td&gt;$7.50&lt;/td&gt;
&lt;td&gt;yes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;gemini-4-carbon&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;$2.00&lt;/td&gt;
&lt;td&gt;$10.00&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;gemini-4-argon&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;$2.00&lt;/td&gt;
&lt;td&gt;$10.00&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Carbon and Argon go to $4 / $20 on 2026-12-01, and 3.8 Flash to $1.50 / $7.50 on 2027-01-01.&lt;/p&gt;




&lt;h4&gt;
  
  
  What Is the Same for Every Model
&lt;/h4&gt;

&lt;p&gt;Every model got:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the same endpoint, &lt;code&gt;/v1beta/openai/chat/completions&lt;/code&gt; on the Gemini API&lt;/li&gt;
&lt;li&gt;the same 1,319 GSM8K and 400 BFCL simple questions, prompts and scoring code&lt;/li&gt;
&lt;li&gt;temperature 0, up to 2,048 tokens per GSM8K answer and 512 per BFCL answer&lt;/li&gt;
&lt;li&gt;eight requests at a time, a 180 s limit per request, up to eight retries&lt;/li&gt;
&lt;li&gt;the same start time: all seven began at 09:11:16 on 2026-11-14&lt;/li&gt;
&lt;li&gt;thinking set as low as each model accepts&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Step 2 shows that setting for each model, and the two models that keep thinking at it.&lt;/p&gt;




&lt;h4&gt;
  
  
  At This Point You Should Have…
&lt;/h4&gt;

&lt;ul&gt;
&lt;li&gt;A Gemini API key from Google AI Studio, saved in &lt;code&gt;~/gemini.key&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Python 3 (the scoring script uses only the standard library)&lt;/li&gt;
&lt;li&gt;A clone of &lt;code&gt;gemma4-dev&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;




&lt;h4&gt;
  
  
  Step 1 — The Endpoint
&lt;/h4&gt;

&lt;p&gt;The Gemini API answers OpenAI chat requests with the key as a Bearer token. Gemma 4 and Gemini take the same request body; only &lt;code&gt;model&lt;/code&gt; changes:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -sS https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
  -H &lt;span class="s2"&gt;"Authorization: Bearer $(cat ~/gemini.key)"&lt;/span&gt; -H &lt;span class="s1"&gt;'Content-Type: application/json'&lt;/span&gt; \
  -d &lt;span class="s1"&gt;'{"model":"gemma-4-31b-it","temperature":0,"max_tokens":2048,"reasoning_effort":"minimal",
       "messages":[{"role":"user","content":"Janet has 16 eggs, eats 3, bakes with 4, sells the rest at $2. How much does she make? End with Answer: &amp;lt;number&amp;gt;"}]}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The reply ends &lt;code&gt;Answer: 18&lt;/code&gt;.&lt;/p&gt;




&lt;h4&gt;
  
  
  Step 2 — Thinking Settings, and the Two Models That Keep Thinking
&lt;/h4&gt;

&lt;p&gt;The OpenAI endpoint sets thinking with &lt;code&gt;reasoning_effort&lt;/code&gt;. &lt;code&gt;levels.sh&lt;/code&gt; sends the question to every model with each value:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;gemma-4-31b-it         minimal  thinking 0  finish stop   Answer: 18
gemma-4-31b-it         none     rejected
gemma-4-31b-it         low      rejected
gemma-4-26b-a4b-it     minimal  thinking 0  finish stop   Answer: 18
gemma-4-26b-a4b-it     none     rejected
gemini-3.5-flash-lite  minimal  thinking 0  finish stop   Answer: 18
gemini-3.5-flash-lite  none     rejected
gemini-3.8-flash       minimal  rejected
gemini-3.8-flash       none     thinking 70  finish stop   Answer: 18
gemini-4-hydrogen      minimal  rejected
gemini-4-hydrogen      none     thinking 81  finish stop   Answer: 18
gemini-4-carbon        minimal  rejected
gemini-4-carbon        none     thinking 0  finish stop   Answer: 18
gemini-4-argon         minimal  rejected
gemini-4-argon         none     thinking 0  finish stop   Answer: 18
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Gemma 4 and Flash-Lite go down to &lt;code&gt;minimal&lt;/code&gt;, and there they think zero tokens. Hydrogen, 3.8 Flash, Carbon and Argon go down to &lt;code&gt;none&lt;/code&gt;; Carbon and Argon think zero tokens there, and Hydrogen and 3.8 Flash keep thinking.&lt;/p&gt;

&lt;p&gt;Google documents this. Its OpenAI compatibility page says "Reasoning cannot be turned off for Gemini 2.5 Pro, Gemini 3, or Gemini 4 models", and its thinking page lists Hydrogen's levels as &lt;code&gt;low&lt;/code&gt;, &lt;code&gt;medium&lt;/code&gt;, &lt;code&gt;high&lt;/code&gt; and &lt;code&gt;xhigh&lt;/code&gt;, with &lt;code&gt;minimal&lt;/code&gt; "Not supported on Gemini 4 models or &lt;code&gt;gemini-3.8-flash&lt;/code&gt;". The same page documents &lt;code&gt;none&lt;/code&gt; for 2.5 models only. On Hydrogen, 3.8 Flash, Carbon and Argon the endpoint accepts &lt;code&gt;none&lt;/code&gt; and treats it as &lt;code&gt;low&lt;/code&gt;. On the first 100 GSM8K problems (&lt;code&gt;levels-sample/&lt;/code&gt;), thinking tokens per problem:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;&lt;code&gt;none&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;low&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;&lt;code&gt;medium&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;not set&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Hydrogen&lt;/td&gt;
&lt;td&gt;239.0&lt;/td&gt;
&lt;td&gt;238.5&lt;/td&gt;
&lt;td&gt;350.6&lt;/td&gt;
&lt;td&gt;311.8&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.8 Flash&lt;/td&gt;
&lt;td&gt;145.3&lt;/td&gt;
&lt;td&gt;139.9&lt;/td&gt;
&lt;td&gt;229.8&lt;/td&gt;
&lt;td&gt;244.6&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Carbon&lt;/td&gt;
&lt;td&gt;28.6&lt;/td&gt;
&lt;td&gt;24.6&lt;/td&gt;
&lt;td&gt;136.6&lt;/td&gt;
&lt;td&gt;125.3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Argon&lt;/td&gt;
&lt;td&gt;2.3&lt;/td&gt;
&lt;td&gt;4.9&lt;/td&gt;
&lt;td&gt;67.7&lt;/td&gt;
&lt;td&gt;74.7&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;So this run's &lt;code&gt;none&lt;/code&gt; is each model's lowest documented level, &lt;code&gt;low&lt;/code&gt;. The native API's other controls give the same result on the test question. &lt;code&gt;thinking-controls.sh&lt;/code&gt; tries each on Hydrogen and reads the API's own counter, &lt;code&gt;thoughtsTokenCount&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;gemini-4-hydrogen  {"thinkingBudget":0}                          answer 88 thoughts 134 total 292 thought-parts 0
gemini-4-hydrogen  {"thinkingLevel":"NONE"}                      rejected: Invalid value at 'generation_config.thinking_config.thinking_level' (type.googleapis.com/g
gemini-4-hydrogen  {"thinkingLevel":"MINIMAL"}                   rejected: Thinking level MINIMAL is not supported for this model. Please retry with other thinking l
gemini-4-hydrogen  {"thinkingLevel":"LOW"}                       answer 70 thoughts 106 total 246 thought-parts 0
gemini-4-hydrogen  {"thinkingBudget":0,"includeThoughts":true}   answer 73 thoughts 79 total 222 thought-parts 1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With &lt;code&gt;thinkingBudget: 0&lt;/code&gt; and &lt;code&gt;includeThoughts: true&lt;/code&gt;, the reply carries the thought itself, beginning "Okay, here's my breakdown of this little egg scenario". 3.8 Flash reports 74 thinking tokens on that question under every control.&lt;/p&gt;

&lt;p&gt;Across the full run, Hydrogen thought on 1,319 of 1,319 GSM8K problems and all 400 BFCL calls. 3.8 Flash thought on 1,293 GSM8K problems and 113 BFCL calls, Carbon on 268 GSM8K problems, Argon on 66, and Gemma 4 and Flash-Lite on none. Every one of those tokens is billed as output. Hydrogen also thought on "Say hi." (&lt;code&gt;more-checks.sh&lt;/code&gt;).&lt;/p&gt;




&lt;h4&gt;
  
  
  🔎 Tip: Thinking Tokens Are Not in &lt;code&gt;completion_tokens&lt;/code&gt;
&lt;/h4&gt;

&lt;p&gt;On this endpoint &lt;code&gt;completion_tokens&lt;/code&gt; counts only the visible answer. Thinking is &lt;code&gt;total_tokens - prompt_tokens - completion_tokens&lt;/code&gt;, and Google bills it as output. The scoring script records it as &lt;code&gt;reasoning_tokens&lt;/code&gt; on every row.&lt;/p&gt;




&lt;h4&gt;
  
  
  Step 3 — Seven Sibling Rigs
&lt;/h4&gt;

&lt;p&gt;gemma4-dev names a rig &lt;code&gt;&amp;lt;platform&amp;gt;-&amp;lt;runtime&amp;gt;-&amp;lt;hardware&amp;gt;-&amp;lt;model&amp;gt;&lt;/code&gt;. On the Gemini API the platform is &lt;code&gt;gemini&lt;/code&gt;, the runtime &lt;code&gt;api&lt;/code&gt; and the hardware &lt;code&gt;google&lt;/code&gt;, since Google publishes neither; the model slot is the Gemma size or the Gemini family:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;gemini-api-google-31b
gemini-api-google-26b
gemini-api-google-flashlite35
gemini-api-google-flash38
gemini-api-google-hydrogen4
gemini-api-google-carbon4
gemini-api-google-argon4
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each &lt;code&gt;tpu.env&lt;/code&gt; names the model and the lowest thinking value it accepts, and the seven &lt;code&gt;run.sh&lt;/code&gt; files are identical:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;MODEL_NAME=gemini-4-hydrogen
LOWEST_REASONING_EFFORT=none
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h4&gt;
  
  
  Step 4 — One Scoring Script
&lt;/h4&gt;

&lt;p&gt;&lt;a href="https://github.com/xbill9/gemma4-dev/tree/main/benchmarks/gen-eval" rel="noopener noreferrer"&gt;&lt;code&gt;benchmarks/gen-eval/gen_eval.py&lt;/code&gt;&lt;/a&gt; is the repo's scoring script for GSM8K and BFCL. It is a plain HTTP client in standard Python, so the same script scores a model on a desktop GPU or behind a hosted API. GSM8K is right when the number after &lt;code&gt;Answer:&lt;/code&gt; matches; BFCL simple is right when the one function call passes BFCL's own checks. Four settings point it at a hosted API:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Setting&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GEN_EVAL_CHAT_URL&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;full chat URL in place of &lt;code&gt;&amp;lt;server&amp;gt;/v1/chat/completions&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GEN_EVAL_API_KEY_FILE&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;sends the file's contents as a Bearer token&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GEN_EVAL_REASONING_EFFORT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;sends &lt;code&gt;reasoning_effort&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;GEN_EVAL_RETRIES&lt;/code&gt;, &lt;code&gt;GEN_EVAL_TIMEOUT_S&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;retries on HTTP 429/5xx and network errors, and a per-request time limit&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h4&gt;
  
  
  Step 5 — Run All Seven Together
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="k"&gt;for&lt;/span&gt; r &lt;span class="k"&gt;in&lt;/span&gt; 31b 26b flashlite35 flash38 hydrogen4 carbon4 argon4&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  gemini-api-google-&lt;span class="nv"&gt;$r&lt;/span&gt;/benchmarks/runs/2026-11-14-accuracy-api/run.sh &lt;span class="o"&gt;&amp;amp;&lt;/span&gt;
&lt;span class="k"&gt;done&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;2026-11-14 09:11:16 BEGIN gemini-4-argon reasoning_effort=none
2026-11-14 09:18:51 END bfcl_simple rc=0 {"task": "bfcl_simple", "max_tokens": 512, "n": 400, "right": 387, "accuracy": 0.9675, "errors": 0, "truncated": 0, "wall_s": 454.8}
2026-11-14 09:48:10 END gsm8k rc=0 {"task": "gsm8k", "max_tokens": 2048, "n": 1319, "right": 1298, "accuracy": 0.9841, "errors": 0, "truncated": 0, "wall_s": 1759.2}
2026-11-14 09:48:10 DONE
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three Gemma 4 requests hit the free tier's rate limit (HTTP 429) after every retry. &lt;code&gt;resend_errors.py&lt;/code&gt; sent those three again with the same settings and replaced only those rows; all three came back right. Every answer in the table below is a model answer.&lt;/p&gt;




&lt;h4&gt;
  
  
  Step 6 — The Results
&lt;/h4&gt;

&lt;p&gt;&lt;code&gt;derived.py&lt;/code&gt; builds the table from the saved replies. The cost is the token counts the API returned times the list price.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;GSM8K&lt;/th&gt;
&lt;th&gt;BFCL simple&lt;/th&gt;
&lt;th&gt;GSM8K problems with thinking, at the lowest setting&lt;/th&gt;
&lt;th&gt;Cost, both tasks&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 31B&lt;/td&gt;
&lt;td&gt;0.9735&lt;/td&gt;
&lt;td&gt;🥇 0.9675&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;🥇 free tier&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 26B&lt;/td&gt;
&lt;td&gt;0.9742&lt;/td&gt;
&lt;td&gt;0.9575&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;🥇 free tier&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.5 Flash-Lite&lt;/td&gt;
&lt;td&gt;0.9629&lt;/td&gt;
&lt;td&gt;0.9350&lt;/td&gt;
&lt;td&gt;0&lt;/td&gt;
&lt;td&gt;$0.92&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.8 Flash&lt;/td&gt;
&lt;td&gt;0.9788&lt;/td&gt;
&lt;td&gt;0.9400&lt;/td&gt;
&lt;td&gt;1,293&lt;/td&gt;
&lt;td&gt;$1.81&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Hydrogen&lt;/td&gt;
&lt;td&gt;🥈 0.9803&lt;/td&gt;
&lt;td&gt;0.9550&lt;/td&gt;
&lt;td&gt;1,319&lt;/td&gt;
&lt;td&gt;$5.02&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Carbon&lt;/td&gt;
&lt;td&gt;🥈 0.9803&lt;/td&gt;
&lt;td&gt;0.9600&lt;/td&gt;
&lt;td&gt;268&lt;/td&gt;
&lt;td&gt;$4.02&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Argon&lt;/td&gt;
&lt;td&gt;🥇 0.9841&lt;/td&gt;
&lt;td&gt;🥇 0.9675&lt;/td&gt;
&lt;td&gt;66&lt;/td&gt;
&lt;td&gt;$3.46&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Against Gemma 4 31B on the same questions, counting the questions each got right that the other missed:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;GSM8K&lt;/th&gt;
&lt;th&gt;BFCL simple&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 26B&lt;/td&gt;
&lt;td&gt;level (+10 / −9)&lt;/td&gt;
&lt;td&gt;level (+5 / −9)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.5 Flash-Lite&lt;/td&gt;
&lt;td&gt;behind (+6 / −20)&lt;/td&gt;
&lt;td&gt;behind (+5 / −18)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.8 Flash&lt;/td&gt;
&lt;td&gt;level (+10 / −3)&lt;/td&gt;
&lt;td&gt;behind (+2 / −13)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Hydrogen&lt;/td&gt;
&lt;td&gt;ahead (+11 / −2)&lt;/td&gt;
&lt;td&gt;level (+5 / −10)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Carbon&lt;/td&gt;
&lt;td&gt;ahead (+14 / −5)&lt;/td&gt;
&lt;td&gt;level (+5 / −8)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Argon&lt;/td&gt;
&lt;td&gt;ahead (+17 / −3)&lt;/td&gt;
&lt;td&gt;level (+7 / −7)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Ahead and behind mean the 95% range of the difference, from 2,000 resamples of the questions, sits entirely above or below zero.&lt;/p&gt;




&lt;h4&gt;
  
  
  Step 7 — Where the Money Goes
&lt;/h4&gt;

&lt;p&gt;By list price Hydrogen is the cheapest Gemini 4 model, $7.50 per million output tokens against $10 for Carbon and Argon. It cost the most because it thought on all 1,319 GSM8K problems at its lowest setting, 248.7 thinking tokens each on average, which made thinking 55% of its GSM8K bill, against 11% for Carbon and 2% for Argon. Argon thought on 66 problems and scored the highest.&lt;/p&gt;

&lt;p&gt;The Gemini 4 models also count more input tokens for the same text: the GSM8K prompts are 160,432 tokens to Hydrogen, Carbon and Argon and 120,902 to Gemma 4 31B, Flash-Lite and 3.8 Flash, a mean of 121.6 against 91.7 per problem.&lt;/p&gt;

&lt;p&gt;Thinking also shares the output limit with the answer. Google's Hydrogen page says &lt;code&gt;max_output_tokens&lt;/code&gt; "caps combined thinking and output tokens". At this run's limits of 2,048 and 512 tokens, thinking used the limit before the answer arrived on 4 GSM8K problems and 2 BFCL calls for 3.8 Flash and on 5 GSM8K problems for Carbon; all 11 scored wrong. Sent again with a 16,384-token limit (&lt;code&gt;cut-rows.py&lt;/code&gt;), 2 of the 4 on 3.8 Flash and 3 of the 5 on Carbon came back right. Hydrogen had no cut answers.&lt;/p&gt;




&lt;h4&gt;
  
  
  Step 8 — Speed
&lt;/h4&gt;

&lt;p&gt;Each reply records how long its request took. All seven models ran at once, eight requests at a time each, over the same connection, so the times are comparable with each other on that morning:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model&lt;/th&gt;
&lt;th&gt;GSM8K median&lt;/th&gt;
&lt;th&gt;GSM8K 90th percentile&lt;/th&gt;
&lt;th&gt;Whole GSM8K run&lt;/th&gt;
&lt;th&gt;BFCL median&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 31B&lt;/td&gt;
&lt;td&gt;8.96 s&lt;/td&gt;
&lt;td&gt;23.93 s&lt;/td&gt;
&lt;td&gt;2,044.1 s&lt;/td&gt;
&lt;td&gt;1.69 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemma 4 26B&lt;/td&gt;
&lt;td&gt;8.16 s&lt;/td&gt;
&lt;td&gt;25.80 s&lt;/td&gt;
&lt;td&gt;2,022.8 s&lt;/td&gt;
&lt;td&gt;1.23 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.5 Flash-Lite&lt;/td&gt;
&lt;td&gt;🥇 1.10 s&lt;/td&gt;
&lt;td&gt;🥇 1.54 s&lt;/td&gt;
&lt;td&gt;🥇 195.8 s&lt;/td&gt;
&lt;td&gt;🥇 0.61 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 3.8 Flash&lt;/td&gt;
&lt;td&gt;3.79 s&lt;/td&gt;
&lt;td&gt;5.43 s&lt;/td&gt;
&lt;td&gt;684.9 s&lt;/td&gt;
&lt;td&gt;1.93 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Hydrogen&lt;/td&gt;
&lt;td&gt;🥈 2.84 s&lt;/td&gt;
&lt;td&gt;🥈 5.39 s&lt;/td&gt;
&lt;td&gt;🥈 620.8 s&lt;/td&gt;
&lt;td&gt;1.95 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Carbon&lt;/td&gt;
&lt;td&gt;7.34 s&lt;/td&gt;
&lt;td&gt;20.04 s&lt;/td&gt;
&lt;td&gt;1,803.7 s&lt;/td&gt;
&lt;td&gt;5.29 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Gemini 4 Argon&lt;/td&gt;
&lt;td&gt;7.63 s&lt;/td&gt;
&lt;td&gt;17.57 s&lt;/td&gt;
&lt;td&gt;1,759.2 s&lt;/td&gt;
&lt;td&gt;6.32 s&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Hydrogen writes about 147.8 tokens per second per request, thinking included, against 26.1 for Argon and 29.7 for Carbon. It finished GSM8K in about a third of Argon's time while thinking on every problem. Flash-Lite was the fastest model overall.&lt;/p&gt;




&lt;h4&gt;
  
  
  Compare and Contrast
&lt;/h4&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Gemma 4 31B&lt;/th&gt;
&lt;th&gt;3.5 Flash-Lite&lt;/th&gt;
&lt;th&gt;3.8 Flash&lt;/th&gt;
&lt;th&gt;Hydrogen&lt;/th&gt;
&lt;th&gt;Carbon&lt;/th&gt;
&lt;th&gt;Argon&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;GSM8K against Gemma 4 31B&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;behind&lt;/td&gt;
&lt;td&gt;level&lt;/td&gt;
&lt;td&gt;ahead&lt;/td&gt;
&lt;td&gt;ahead&lt;/td&gt;
&lt;td&gt;🥇 ahead&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;BFCL against Gemma 4 31B&lt;/td&gt;
&lt;td&gt;🥇&lt;/td&gt;
&lt;td&gt;behind&lt;/td&gt;
&lt;td&gt;behind&lt;/td&gt;
&lt;td&gt;level&lt;/td&gt;
&lt;td&gt;level&lt;/td&gt;
&lt;td&gt;🥇 level&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Thinks at its lowest setting&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;most problems&lt;/td&gt;
&lt;td&gt;every problem&lt;/td&gt;
&lt;td&gt;some problems&lt;/td&gt;
&lt;td&gt;rare&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cost, both tasks&lt;/td&gt;
&lt;td&gt;🥇 free tier&lt;/td&gt;
&lt;td&gt;$0.92&lt;/td&gt;
&lt;td&gt;$1.81&lt;/td&gt;
&lt;td&gt;$5.02&lt;/td&gt;
&lt;td&gt;$4.02&lt;/td&gt;
&lt;td&gt;$3.46&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;GSM8K median per request&lt;/td&gt;
&lt;td&gt;8.96 s&lt;/td&gt;
&lt;td&gt;🥇 1.10 s&lt;/td&gt;
&lt;td&gt;3.79 s&lt;/td&gt;
&lt;td&gt;🥈 2.84 s&lt;/td&gt;
&lt;td&gt;7.34 s&lt;/td&gt;
&lt;td&gt;7.63 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Weights you can download&lt;/td&gt;
&lt;td&gt;🥇 yes&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;td&gt;no&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h4&gt;
  
  
  What the API Makes Easy to Miss
&lt;/h4&gt;

&lt;p&gt;Google documents both facts behind Hydrogen's bill: reasoning cannot be turned off on Gemini 4 models, and output prices include thinking tokens. Four things in the API still make the bill easy to misread:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Off-looking settings are accepted.&lt;/strong&gt; &lt;code&gt;reasoning_effort: "none"&lt;/code&gt; on the OpenAI endpoint and &lt;code&gt;thinkingBudget: 0&lt;/code&gt; on the native API return no error on Hydrogen. &lt;code&gt;none&lt;/code&gt; runs as &lt;code&gt;low&lt;/code&gt;, and nothing in the reply says thinking is still on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Not setting it costs more.&lt;/strong&gt; Hydrogen's default is &lt;code&gt;high&lt;/code&gt;: 311.8 thinking tokens per problem on the 100-problem sample against 239.0 at &lt;code&gt;none&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;completion_tokens&lt;/code&gt; leaves thinking out.&lt;/strong&gt; A client that reads it sees the visible answer only; on Hydrogen thinking was 55% of the GSM8K bill.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The per-token price invites the wrong comparison.&lt;/strong&gt; $7.50 against $10 per million output tokens puts Hydrogen below Carbon and Argon; per run it cost 45% more than Argon, $5.02 against $3.46.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Compare models by cost per answer, measured on your own prompts.&lt;/p&gt;




&lt;h4&gt;
  
  
  So, Which One?
&lt;/h4&gt;

&lt;p&gt;For the best scores on short math problems and single function calls with thinking at its lowest setting, Gemini 4 Argon: highest on GSM8K, tied for highest on BFCL, and the cheapest of the three Gemini 4 models per run because it rarely thinks.&lt;/p&gt;

&lt;p&gt;For hard, multi-step work, Google points to Carbon. Its Hydrogen page calls Carbon "our strongest frontier model", one that "spends more thinking tokens per turn to test hypotheses and verify edge cases on hard architecture, debugging, science, and security audits", and suggests pairing the two: Carbon plans and resolves hard roadblocks, Hydrogen does the code edits, subagent tasks and test runs. This run held Carbon to its lowest thinking setting, where it thought on 268 of 1,319 GSM8K problems, so that case is untested here. Five of its GSM8K answers were cut at the 2,048-token limit; with a 16,384-token limit 3 of them came back right, which still leaves it below Argon.&lt;/p&gt;

&lt;p&gt;Gemini 4 Hydrogen fits four cases:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;On the free tier.&lt;/strong&gt; Hydrogen has one and Carbon and Argon do not. On free quota its thinking costs nothing, and it is the fastest Gemini 4 model, at 0.9803 on GSM8K like Carbon.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;When response time matters more than cost.&lt;/strong&gt; 2.84 s per GSM8K problem against 7.34 s for Carbon and 7.63 s for Argon; 620.8 s for the whole set against 1,759.2 s for Argon.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;From 2026-12-01.&lt;/strong&gt; Carbon and Argon go to $4 / $20. At those prices this run costs $6.93 on Argon and $8.03 on Carbon against $5.02 on Hydrogen, which makes Hydrogen the cheapest Gemini 4 model per run. That is arithmetic from list prices.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;On hard coding and agent work.&lt;/strong&gt; Google's thinking page recommends Hydrogen's default &lt;code&gt;high&lt;/code&gt; level "for most tasks, including complex coding, agentic execution, tool calling". This run measured short math problems and single function calls, so that case is untested here.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For high-volume simple work on a paid tier, Gemini 3.5 Flash-Lite: $0.92 for both tests, no thinking, 1.10 s per problem, at the cost of being behind Gemma 4 31B on both tests.&lt;/p&gt;

&lt;p&gt;For tool calling at no cost, Gemma 4 31B: tied with Argon on BFCL, 0.0106 behind it on GSM8K, free on the Gemini API, and the same weights run on your own hardware.&lt;/p&gt;




&lt;h4&gt;
  
  
  Summary
&lt;/h4&gt;

&lt;p&gt;The goal of this article was to compare the new Gemini 4 models with Gemma 4 on equal terms. The key to the solution was running all seven models through one Gemini API endpoint, started together, with the same questions, scoring script and settings, with thinking set as low as each model accepts. The results were:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;🟢 Gemini 4 Argon scored highest: 0.9841 on GSM8K and 0.9675 on BFCL simple, for $3.46.&lt;/li&gt;
&lt;li&gt;🟢 Gemma 4 31B tied Argon on BFCL at 0.9675 and scored 0.9735 on GSM8K, on the free tier.&lt;/li&gt;
&lt;li&gt;🟢 Hydrogen, Carbon and Argon were ahead of Gemma 4 31B on GSM8K; on BFCL all three were level with it.&lt;/li&gt;
&lt;li&gt;🟢 Gemma 4 26B was level with the 31B on both tests.&lt;/li&gt;
&lt;li&gt;🟢 Hydrogen was the fastest Gemini 4 model, 2.84 s per GSM8K problem against 7.34 s for Carbon and 7.63 s for Argon.&lt;/li&gt;
&lt;li&gt;⚠️ Hydrogen has the lowest Gemini 4 price per token and cost the most per run, $5.02: thinking was 55% of its GSM8K bill.&lt;/li&gt;
&lt;li&gt;⚠️ Thinking cannot be turned off on Gemini 4 Hydrogen or 3.8 Flash, as Google's docs say. At the lowest setting Hydrogen thought on every problem and 3.8 Flash on 1,293 of 1,319, billed as output.&lt;/li&gt;
&lt;li&gt;⚠️ The API accepts &lt;code&gt;none&lt;/code&gt; on Hydrogen without an error and runs it as &lt;code&gt;low&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;⚠️ Thinking shares the output limit: it cut 6 answers on 3.8 Flash and 5 on Carbon at this run's limits.&lt;/li&gt;
&lt;li&gt;🟢 From 2026-12-01 Hydrogen becomes the cheapest Gemini 4 model per run, $5.02 against $6.93 for Argon, by arithmetic from list prices.&lt;/li&gt;
&lt;li&gt;⚠️ Thinking tokens are missing from &lt;code&gt;completion_tokens&lt;/code&gt; on the OpenAI-compatible endpoint.&lt;/li&gt;
&lt;li&gt;⚠️ Carbon and Argon have no free tier and double in price on 2026-12-01.&lt;/li&gt;
&lt;li&gt;❌ Gemini 3.5 Flash-Lite and 3.8 Flash were behind Gemma 4 31B on BFCL.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Scope: one laptop in the US calling the Gemini API on 2026-11-14, one run per model, all seven started together. Thinking was set as low as each model accepts: &lt;code&gt;minimal&lt;/code&gt; for Gemma 4 and Flash-Lite, &lt;code&gt;none&lt;/code&gt; for the rest, which matched &lt;code&gt;low&lt;/code&gt; on a 100-problem sample. The native thinking controls were tried on one question. The scores for 3.8 Flash and Carbon include the 11 answers cut by thinking at the 2,048 and 512 token limits. Three Gemma 4 requests that hit the free tier's rate limit were sent again with the same settings. Costs are token counts times list prices. Run times are from one run with all seven sharing one connection, and will move with load on the service. Hard multi-step tasks and higher thinking levels were not measured, which is the work Google positions Carbon for. Google does not say what hardware or engine serves any of these models.&lt;/p&gt;

&lt;p&gt;The strategy for comparing Gemini and Gemma 4 on equal terms was validated with an incremental step by step approach.&lt;/p&gt;




&lt;h4&gt;
  
  
  References
&lt;/h4&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://github.com/xbill9/gemma4-dev" rel="noopener noreferrer"&gt;gemma4-dev on GitHub&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/xbill9/gemma4-dev/tree/main/gemini-api-google-argon4" rel="noopener noreferrer"&gt;The Gemini API sibling rigs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/xbill9/gemma4-dev/tree/main/docs/gemini-vs-gemma/evidence" rel="noopener noreferrer"&gt;Evidence for this article&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://aistudio.google.com/docs/pricing" rel="noopener noreferrer"&gt;Gemini API pricing&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ai.google.dev/gemini-api/docs/thinking" rel="noopener noreferrer"&gt;Gemini thinking levels&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ai.google.dev/gemini-api/docs/openai" rel="noopener noreferrer"&gt;Gemini API OpenAI compatibility&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ai.google.dev/gemini-api/docs/whats-new-gemini-4-hydrogen" rel="noopener noreferrer"&gt;What's new in Gemini 4 Hydrogen&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/grade-school-math" rel="noopener noreferrer"&gt;GSM8K&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://gorilla.cs.berkeley.edu/leaderboard.html" rel="noopener noreferrer"&gt;Berkeley Function Calling Leaderboard&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://huggingface.co/google/gemma-4-31B-it" rel="noopener noreferrer"&gt;Gemma 4 31B on Hugging Face&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Hope you enjoyed it!&lt;/p&gt;

</description>
      <category>gemini</category>
      <category>gemma</category>
      <category>benchmark</category>
      <category>ai</category>
    </item>
    <item>
      <title>Prepare a WebMCP Review Without Submitting the Request</title>
      <dc:creator>Raju Dandigam</dc:creator>
      <pubDate>Sat, 14 Nov 2026 16:18:00 +0000</pubDate>
      <link>https://dev.to/gde/prepare-a-webmcp-review-without-submitting-the-request-j4n</link>
      <guid>https://dev.to/gde/prepare-a-webmcp-review-without-submitting-the-request-j4n</guid>
      <description>&lt;p&gt;A business-class trip in my demo produced four facts at the same time:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the saved fields were valid;&lt;/li&gt;
&lt;li&gt;the request could be submitted;&lt;/li&gt;
&lt;li&gt;the cabin required review;&lt;/li&gt;
&lt;li&gt;nothing had been submitted.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;An assistant that compresses those facts into “approved” or “blocked” changes the meaning of the application.&lt;/p&gt;

&lt;p&gt;I added &lt;code&gt;prepare_trip_review&lt;/code&gt; to &lt;a href="https://github.com/rajudandigam/trip-workbench" rel="noopener noreferrer"&gt;Trip Workbench&lt;/a&gt; so a WebMCP client can bring the saved request and its findings into the React editor without performing the consequential action. The result explicitly includes &lt;code&gt;submitted: false&lt;/code&gt;, and the trip remains a draft.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make “prepare” a first-class operation
&lt;/h2&gt;

&lt;p&gt;The caller supplies both the open draft identity and the revision it intends to review:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"draftId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;open-draft-id&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"expectedRevision"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The native browser trace used a synthetic SFO–JFK request for one traveler in business class. Its captured result included:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"revision"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"policyVersion"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"demo-policy-v1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"valid"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"canSubmit"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"fieldIssues"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"reviewRequirements"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"code"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"PREMIUM_CABIN"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Premium cabin requires review."&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"submitted"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"draft"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This response does not approve a premium cabin, reserve travel, or claim that a human reviewer acted. It reports the demo policy for one saved revision.&lt;/p&gt;

&lt;p&gt;That distinction is easier to maintain when review preparation has its own verb. A generic &lt;code&gt;validate&lt;/code&gt; call can return data, but &lt;code&gt;prepare_trip_review&lt;/code&gt; also places the result where the person can inspect it beside the form.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bind the review to saved state
&lt;/h2&gt;

&lt;p&gt;The WebMCP adapter parses the arguments and delegates to the same coordinator that owns the editor. That coordinator knows about conditions the server snapshot cannot see:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;unsaved form edits;&lt;/li&gt;
&lt;li&gt;a save in flight;&lt;/li&gt;
&lt;li&gt;an earlier mutation with an unknown outcome;&lt;/li&gt;
&lt;li&gt;the current session and editor generation;&lt;/li&gt;
&lt;li&gt;the exact saved revision visible when preparation began.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Preparation refuses to run when any of those conditions would make the result ambiguous. It also refuses a different draft, a stale revision, or a request that is no longer a draft.&lt;/p&gt;

&lt;p&gt;The client stores the result with an explicit binding:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;PreparedReview&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;ValidationResult&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;preparedAtRevision&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;submitted&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Local edits and confirmed mutations clear the panel. The review is not durable truth about the trip; it is a view derived from a particular revision and policy version.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;saved revision 2
       |
       v
validate policy v1 ----&amp;gt; prepared panel
       |                       |
       | edit/save/reopen      | invalidated
       +-----------------------X
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Verify tool, page, and database
&lt;/h2&gt;

&lt;p&gt;The recorded run discovered &lt;code&gt;prepare_trip_review&lt;/code&gt; through native WebMCP, executed it, waited for the React panel, and independently queried persisted state.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;tool&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;webmcp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;tools&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;entry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"prepare_trip_review"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;tool&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Review tool was not discovered"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;tool&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;execute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;draftId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;expectedRevision&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;savedRevision&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;signal&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;AbortSignal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;6_000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;waitForSelector&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'[data-testid="prepared-review"]'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;visible&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The observed surfaces agreed:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Surface&lt;/th&gt;
&lt;th&gt;Observation&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Tool&lt;/td&gt;
&lt;td&gt;revision 2, &lt;code&gt;PREMIUM_CABIN&lt;/code&gt;, &lt;code&gt;canSubmit: true&lt;/code&gt;, &lt;code&gt;submitted: false&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Page&lt;/td&gt;
&lt;td&gt;same revision and finding; still a draft&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Database&lt;/td&gt;
&lt;td&gt;revision 2, status &lt;code&gt;draft&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Submissions&lt;/td&gt;
&lt;td&gt;zero rows&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A second check typed an unsaved purpose before preparation. The tool returned &lt;code&gt;USER_EDIT_IN_PROGRESS&lt;/code&gt;, protecting the difference between saved data and what the user currently sees.&lt;/p&gt;

&lt;h2&gt;
  
  
  Recheck after every await
&lt;/h2&gt;

&lt;p&gt;The first implementation checked the context before calling validation. Controlled race tests showed why that is insufficient: an update could start while validation was waiting, or a user could leave and reopen the same draft before the old response returned.&lt;/p&gt;

&lt;p&gt;The reliability pass at &lt;a href="https://github.com/rajudandigam/trip-workbench/commit/0691767b8d3cecaaf4c71a53006d10f1ed7a8f27" rel="noopener noreferrer"&gt;&lt;code&gt;0691767&lt;/code&gt;&lt;/a&gt; now verifies the session generation, editor generation, active operation, pending outcome, draft identity, revision, and dirty state &lt;strong&gt;after&lt;/strong&gt; validation resolves. Stale results are refused instead of populating a new panel.&lt;/p&gt;

&lt;p&gt;The important pattern is not specific to travel:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;sessionAtStart&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;sessionGeneration&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;editorAtStart&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;editorGeneration&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;validate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;savedRevision&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sessionAtStart&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="n"&gt;sessionGeneration&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;contextMismatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;editorAtStart&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="n"&gt;editorGeneration&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;contextMismatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;saving&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pendingOutcome&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;refuseStaleResult&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;savedDraft&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;revision&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="n"&gt;savedRevision&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;dirty&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;revisionConflict&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nf"&gt;publishPreparedReview&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Any asynchronous result intended for a visible workflow needs a freshness rule. A matching object ID is not enough when the person can leave and reopen that same object.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep submission separate
&lt;/h2&gt;

&lt;p&gt;The prepared panel points to the existing review screen. Manual submission sends the reviewed revision and policy version, and the server checks them again.&lt;/p&gt;

&lt;p&gt;There is deliberately no submit operation in this five-tool interface. That limits this WebMCP surface; it does not prove that a broader browser agent cannot click an ordinary submit button. For real consequential actions, the &lt;a href="https://webmachinelearning.github.io/webmcp/" rel="noopener noreferrer"&gt;current WebMCP specification&lt;/a&gt; and &lt;a href="https://developer.chrome.com/docs/ai/webmcp/secure-tools" rel="noopener noreferrer"&gt;Chrome security guidance&lt;/a&gt; also define &lt;code&gt;consequentialHint&lt;/code&gt; as a signal for actions such as booking travel or transferring money. A signal supports safer client behavior, but server authorization and confirmation rules remain mandatory.&lt;/p&gt;

&lt;p&gt;The most useful result of preparation is a controlled pause: the saved request is visible, the finding is tied to a revision, and the person still owns the next consequential action.&lt;/p&gt;

</description>
      <category>react</category>
      <category>typescript</category>
      <category>ai</category>
      <category>webmcp</category>
    </item>
    <item>
      <title>Securing AI Agents on Google Cloud: An SRE and Platform Engineer’s View</title>
      <dc:creator>Karthigayan Devan</dc:creator>
      <pubDate>Sat, 14 Nov 2026 15:16:47 +0000</pubDate>
      <link>https://dev.to/gde/securing-ai-agents-on-google-cloud-an-sre-and-platform-engineers-view-69d</link>
      <guid>https://dev.to/gde/securing-ai-agents-on-google-cloud-an-sre-and-platform-engineers-view-69d</guid>
      <description>&lt;p&gt;Google Cloud recently published a 28-page ebook called &lt;strong&gt;Secure AI innovation: Securing the agentic enterprise on Google Cloud&lt;/strong&gt;. Six chapters, a lot of product names, and one big message: AI agents are now part of your production estate, so secure them like it.&lt;/p&gt;

&lt;h2&gt;
  
  
  TL;DR
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;The core idea is right. Treat AI agents as a new kind of workload with their own identity, their own guardrails, and their own monitoring.&lt;/li&gt;
&lt;li&gt;The 4-stage model (Architect, Inventory, Intercept, Defend) is a useful mental map. I would add a fifth stage: &lt;strong&gt;Operate and Retire&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Many numbers come from Google, Google Cloud Next talks, and Wiz (which is now part of Google). Good signals, but read them as directional.&lt;/li&gt;
&lt;li&gt;The hardest part isn't buying the tools. It's making the secure path the &lt;strong&gt;fastest&lt;/strong&gt; path for developers. That is a platform engineering problem, not a security product problem.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The ebook at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Chapter&lt;/th&gt;
&lt;th&gt;Big idea&lt;/th&gt;
&lt;th&gt;My one-line take&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1. Securing the baseline&lt;/td&gt;
&lt;td&gt;Every agent gets its own identity&lt;/td&gt;
&lt;td&gt;Yes, and keep the audit trail alive after the identity dies&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2. Governing the AI supply chain&lt;/td&gt;
&lt;td&gt;Shadow AI and risky third-party skills&lt;/td&gt;
&lt;td&gt;Shadow AI is a symptom of a slow paved road&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3. Enforcing the guardrails&lt;/td&gt;
&lt;td&gt;Access checks plus intent checks at runtime&lt;/td&gt;
&lt;td&gt;Measure the latency yourself and decide fail-open vs fail-closed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4. Fighting AI threats with AI&lt;/td&gt;
&lt;td&gt;Find, prove, and fix vulnerabilities automatically&lt;/td&gt;
&lt;td&gt;Fix generation is cheap. Review capacity is the real bottleneck&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5. Digital sovereignty&lt;/td&gt;
&lt;td&gt;Key control and three sovereign cloud options&lt;/td&gt;
&lt;td&gt;Each option changes your operating model, not just your compliance story&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;6. Velocity vs governance&lt;/td&gt;
&lt;td&gt;A 4-stage agent security lifecycle&lt;/td&gt;
&lt;td&gt;Good map, missing the "operate" and "evaluate" parts&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Now let's go chapter by chapter.&lt;/p&gt;

&lt;h2&gt;
  
  
  Chapter 1: Securing the baseline
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What the ebook says, in short:&lt;/strong&gt; Shared service accounts and long-lived keys were never built for autonomous agents. Each agent should get a dedicated identity that lives only as long as its task, get extra privilege only when needed (Privileged Access Manager), and be fenced in by a Principal Access Boundary. Under that sits the Enterprise Foundations Blueprint: infrastructure as code, Cloud Build pipelines, SLSA Level 3 provenance, Binary Authorization, Shared VPC, and VPC Service Controls.&lt;/p&gt;

&lt;p&gt;One stat that stuck with me: non-human identities already outnumber humans by a huge margin in cloud environments (the ebook says 82x). Agents will push that number higher, fast.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🛠️ SRE view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;A unique identity per agent is not only a security win. It's an observability win. During an incident, the first question is always "who did this?" With shared service accounts, the honest answer is often "something, somewhere." With per-agent identity, you can actually answer it.&lt;/p&gt;

&lt;p&gt;But there is a catch with identities tied to the task lifecycle. If the identity disappears when the task ends, make sure the evidence does not. Export audit logs to a log sink with retention that matches your compliance needs. Your postmortem might happen three weeks after the agent is gone.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🏗️ Platform engineering view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Nobody should hand-craft agent identities. Bake it into the golden path. When a team scaffolds a new agent from your template, it should come with its own identity, a narrow role set, a boundary policy, and labels for owner, environment, and cost center. Those labels pay off twice: once for security, once for FinOps when someone asks why the AI bill doubled.&lt;/p&gt;

&lt;p&gt;On VPC Service Controls: it is powerful, and it is also famous for breaking things on day one. Roll it out in dry-run mode first, watch what would have been blocked, then enforce.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;💻 Builder view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The hardest question is not "how do I give an agent an identity?" It's "what permissions does this agent actually need?" Agents are not deterministic. The tools they call can change from one prompt to the next. My approach: start narrow in dev, watch the denied calls, widen permissions on purpose, and treat every permission change like a code change that goes through a PR.&lt;/p&gt;

&lt;p&gt;I also liked the warranty claim example, where a customer-facing agent talks to backend data agents using real identities instead of shared keys. It's boring and practical, which is exactly what this space needs more of.&lt;/p&gt;

&lt;h2&gt;
  
  
  Chapter 2: Governing the AI supply chain
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What the ebook says, in short:&lt;/strong&gt; Under deadline pressure, developers plug in third-party agent skills without review. The ebook claims more than 15% of skills in public marketplaces are malicious, and 68% of organizations run self-hosted models buried inside third-party software without knowing it. The answer is a central hub: Agent Registry, Wiz AI-BOM for discovery, ADK session isolation, Agent Gateway, managed MCP servers, an auth manager that keeps tokens away from the agent, and a security dashboard. Best Buy shares how they isolate high-risk agents on Cloud Run with their own containers and add a human approval step before risky API calls.&lt;/p&gt;

&lt;p&gt;A quick naming note for readers: the ebook says "Gemini acts as the control plane." Many people will picture the chat app. From what I have seen, read it as the Gemini Enterprise agent platform side of Google Cloud, where things like the registry live.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🛠️ SRE view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Every third-party skill or MCP server is a dependency that can change behavior without you ever deploying anything. That's a reliability risk as much as a security risk. Pin versions. Route skill upgrades through the same change process as any other production change. An unpinned skill is config drift you can't see.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🏗️ Platform engineering view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Shadow AI is a symptom, not the disease. Developers go around IT when the official path is slower than their deadline. We saw this with containers, with npm packages, with Terraform modules. AI skills are just the next round.&lt;/p&gt;

&lt;p&gt;The fix is an internal catalog that is &lt;strong&gt;easier&lt;/strong&gt; to use than the public marketplace: pre-approved skills, one-command onboarding, and a fast review SLA for new requests. If approval takes three weeks, people will find another way. Every time.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;💻 Builder view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The most underrated line in the whole ebook is from Best Buy: keep deploy-time permissions separate from runtime permissions. The pipeline that deploys your agent should never share an identity with the running agent. We learned this lesson years ago with CI service accounts. Let's not learn it again.&lt;/p&gt;

&lt;p&gt;On human-in-the-loop approvals: I'm a fan, with one warning. If a person approves 200 requests a day, they stop reading them. Gate on risk, not on everything. Track how long approvals take and how often people reject. A rejection rate of zero usually means the gate is theater, or it's in the wrong place.&lt;/p&gt;

&lt;h2&gt;
  
  
  Chapter 3: Enforcing the guardrails
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What the ebook says, in short:&lt;/strong&gt; Runtime protection has two layers. First, access control at the Agent Gateway, so agents only reach systems they are approved for. Second, intent control, where filters look at what a prompt is really trying to do. Model Armor screens prompts for injection and jailbreak attempts and redacts sensitive data. Agents also validate inputs with strict rules, like checking that a serial number is only letters and numbers before it ever touches BigQuery.&lt;/p&gt;

&lt;p&gt;One quote from Abhishek A. Hemrajani of Google Cloud Security sums it up well: "Agents are the new insider threats." I agree. An agent doesn't need bad intent to drop a table. It just needs to be confused.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🛠️ SRE view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Every inline check is another hop in the request path. The ebook says Model Armor adds no latency. Maybe it's small, but I would never take that on faith. Measure p95 and p99 in your own setup and include it in your latency SLO.&lt;/p&gt;

&lt;p&gt;More important: decide your failure mode &lt;strong&gt;before&lt;/strong&gt; the incident. If the gateway or the screening service is slow or down, do agents fail open or fail closed? That's a business decision, not a technical one. Write it down and get someone to sign off on it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🏗️ Platform engineering view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Put guardrails in shared infrastructure, not in each agent's code. Ten teams writing ten prompt filters means ten different bugs. Central policy at the gateway, with team-level config for what's allowed.&lt;/p&gt;

&lt;p&gt;And from a FinOps angle: screening every prompt and response is not free. Budget for it per agent, and watch it, especially for chatty agents.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;💻 Builder view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The serial number example is my favorite part of this chapter because it's old-school engineering. Input validation. Parameterized queries. LLM guardrails don't replace basic hygiene. Never let a model build a raw SQL string from user text. A smart filter in front is great, but a strict schema behind it is what saves you.&lt;/p&gt;

&lt;h2&gt;
  
  
  Chapter 4: Fighting AI threats with AI defense
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What the ebook says, in short:&lt;/strong&gt; Attackers move at machine speed. The ebook cites an estimated mean time to exploit of negative seven days, meaning exploits often show up before the patch does. The answer is a find-and-fix loop: Wiz maps risks across your stack, CodeMender proves a vulnerability is real by trying to exploit it in a sandbox, and then generates a tested fix that shows up as a pull request for a human to approve. Wiz Red Agent tests from the outside, Wiz Blue Agent adds runtime context during incidents, and behavior analytics watch for agents acting out of pattern. The ebook also shares a story of one agent making 42,000 cloud API calls and 300 sensitive IAM changes in a single hour.&lt;/p&gt;

&lt;p&gt;An honest note while reading: Wiz is now part of Google, so when the ebook calls Wiz the recommended standard for multi-cloud, that is Google recommending Google. It doesn't make it wrong. Just read it with that in mind.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🛠️ SRE view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;42,000 calls in an hour is about 12 calls per second, nonstop. Detecting that at machine speed is good. But my first question is: &lt;strong&gt;why did nothing stop it?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Classic SRE tools apply directly to agents:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Quotas and rate limits per agent identity&lt;/li&gt;
&lt;li&gt;Circuit breakers when error rates or call volumes spike&lt;/li&gt;
&lt;li&gt;A real kill switch that someone on call can use in seconds&lt;/li&gt;
&lt;li&gt;An alert on &lt;strong&gt;any&lt;/strong&gt; IAM change made by an agent. That should be a rare event, not a dashboard metric.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Prevention through limits is cheaper than detection after the fact.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🏗️ Platform engineering view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Automatic patch PRs sound amazing until 40 of them land on a Monday. Fix generation is cheap. Human review is the bottleneck. Route them with CODEOWNERS, batch related fixes, and track merge rate, revert rate, and time to merge. If the revert rate starts climbing, slow the machine down.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;💻 Builder view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Exploit verification in a sandbox is the feature I'm most excited about in this whole ebook. False positives destroy trust in security scanners. Teams learn to ignore them. Proving a vulnerability is actually exploitable changes the conversation from "your scanner is noisy" to "here's the proof, here's the fix."&lt;/p&gt;

&lt;h2&gt;
  
  
  Chapter 5: Achieving digital sovereignty
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What the ebook says, in short:&lt;/strong&gt; Regulated industries need control over where data lives and who can touch it. Customers own their keys through Cloud KMS, Key Access Justifications add an approval step before Google can decrypt, and Secret Manager keeps credentials out of agent code. There are three sovereign options: a data boundary in the public cloud through Assured Workloads, dedicated regional clouds run by local operators, and fully air-gapped Google Distributed Cloud. Google also points to its Leader position in the Forrester Wave for sovereign cloud platforms.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🛠️ SRE view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Each sovereign option changes your operating model, not just your compliance checklist. Air-gapped means no pulling the latest model on a whim, no SaaS observability tools, and patching on your schedule with your own people. Plan for update lag and for on-call depth.&lt;/p&gt;

&lt;p&gt;Also: owning your keys means you can lose your keys. Locking yourself out of your own data is an outage you caused. Test key rotation and break-glass access the same way you test disaster recovery.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;🏗️ Platform engineering view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The biggest promise here is a consistent experience across all three options. That's the part I'd verify hardest. Do the same Terraform modules work? The same pipelines? The same agent templates? Wherever they differ, document it clearly in your platform docs so teams don't find out in production.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;💻 Builder view&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;I still see API keys sitting in agent code, and sometimes inside system prompts. Remember that agents read their own context, and that context often ends up in logs. A secret in a prompt is a secret in your logs. Pull secrets at runtime, never hardcode them, never put them in prompts.&lt;/p&gt;

&lt;p&gt;One caveat: strong statements like "Google cannot decrypt without approval" depend on how your keys are set up. Check exactly which configuration gives you that guarantee before you repeat it to your auditors.&lt;/p&gt;

&lt;h2&gt;
  
  
  Chapter 6: Bridging AI velocity and governance
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;What the ebook says, in short:&lt;/strong&gt; It wraps everything into a 4-stage lifecycle. &lt;strong&gt;Architect&lt;/strong&gt; (identity and perimeters), &lt;strong&gt;Inventory&lt;/strong&gt; (discovery, registry, provenance, human approvals), &lt;strong&gt;Intercept&lt;/strong&gt; (gateway control and prompt screening), and &lt;strong&gt;Defend&lt;/strong&gt; (threat detection, behavior monitoring, and automatic fixes). Sovereignty and key control run alongside all four.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;My take:&lt;/strong&gt; This is a good map, and I'll probably use it in conversations with leadership. But from an SRE and platform view, two stages are missing.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Operate and Retire.&lt;/strong&gt; Who is on call for an agent? Where is the runbook for "agent is doing something weird"? How do you shut down one agent without taking down the others? And when an agent is no longer needed, who revokes its identity, removes its skills, and deletes its connections? Agents rarely die cleanly. A forgotten agent that still has permissions is tomorrow's breach.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Evaluate.&lt;/strong&gt; Test agent behavior before production, not just the code. Run red-team prompts in CI. Run regression evals whenever the model version changes. A model upgrade is a deployment. Treat it like one.&lt;/p&gt;

&lt;p&gt;And one more thing none of the four stages mention: &lt;strong&gt;cost&lt;/strong&gt;. Every layer here (screening, telemetry, behavior analytics, sandboxed scans) adds spend. Security that nobody can afford gets turned off quietly.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where I'd push back overall
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The numbers.&lt;/strong&gt; Many stats come from vendor reports and conference talks. They are useful signals, but go to the primary sources before you put them in a board deck.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The product density.&lt;/strong&gt; Smaller teams can feel lost here. You don't need every product on day one. Unique identities, no static keys, input validation, rate limits, and good logs will get you far.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;New and preview features.&lt;/strong&gt; Some of these capabilities are very new. Check what's generally available before you build a production roadmap on it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Absolute language.&lt;/strong&gt; Words like "total governance" and "never" make me nervous. Security is never total. It's layers, tradeoffs, and good habits.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  My Monday morning checklist
&lt;/h2&gt;

&lt;p&gt;If I were starting from this ebook tomorrow, here's my order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;List every agent running today, including the "just an experiment" ones.&lt;/li&gt;
&lt;li&gt;Find any agent using a shared service account or a static key. Fix those first.&lt;/li&gt;
&lt;li&gt;Add per-agent quotas and a kill switch someone on call can actually use.&lt;/li&gt;
&lt;li&gt;Put a central gateway and prompt screening in front of agents, and measure the latency it adds.&lt;/li&gt;
&lt;li&gt;Pin third-party skills and MCP servers, and route upgrades through change management.&lt;/li&gt;
&lt;li&gt;Decide fail-open vs fail-closed for each guardrail, and write it down.&lt;/li&gt;
&lt;li&gt;Label every agent resource with owner, environment, and cost center.&lt;/li&gt;
&lt;li&gt;Write one runbook for "an agent is misbehaving" and run a drill.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Final thought
&lt;/h2&gt;

&lt;p&gt;The ebook says security is the enabler, not the blocker. I agree, with one condition: it's only true if the platform team makes the secure path the easy path. Tools give you the controls. Golden paths, templates, and fast reviews are what get developers to actually use them.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Over to you:&lt;/strong&gt; what is the hardest part of securing agents in your org right now? Identity, shadow AI, guardrails, or just knowing which agents exist? Drop it in the comments. I read every one.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sources&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Ebook landing page: &lt;a href="https://cloud.google.com/security/resources/secure-ai-innovation" rel="noopener noreferrer"&gt;https://cloud.google.com/security/resources/secure-ai-innovation&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Ebook PDF: &lt;a href="https://services.google.com/fh/files/misc/secure_ai_innovation_securing_the_agentic_enterprise_on_google_cloud.pdf" rel="noopener noreferrer"&gt;https://services.google.com/fh/files/misc/secure_ai_innovation_securing_the_agentic_enterprise_on_google_cloud.pdf&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;All opinions are my own, based on my experience in SRE, platform engineering, and building with AI agents.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>discuss</category>
      <category>security</category>
      <category>googlecloud</category>
      <category>ai</category>
    </item>
  </channel>
</rss>
