The question you cannot answer after an incident
Something dropped a table in your Cloud SQL instance last night, and the only actor with access was an AI agent. You open its logs. They tell you the agent "completed a maintenance task." That is not session recording. That is a summary the agent wrote about itself, and it is worthless for forensics. Session recording for AI agents on GCP means the exact commands that crossed the wire, attributed to an identity, stored where the agent cannot touch them.
If you run agents against GCP-hosted databases, clusters, or BigQuery, you need that record before the incident, not after. Here is how to capture it.
Why agent logs are not a record
An agent's own output is a narrative it controls. It can omit a step, mislabel an action, or be tampered with if the agent is compromised. A real record has three properties the agent's logs lack:
- It captures the actual protocol traffic, the queries and commands, not a description of them.
- It ties every command to the identity that issued it, so nothing is anonymous.
- It lives outside the process being recorded, so the actor cannot rewrite its own history.
That third property is the architectural one. The record has to sit outside the agent. If it lives inside the process the agent runs, a bad actor or a buggy agent edits the evidence and the truth in the same breath.
Where the recording boundary belongs
The natural place to capture a session is the point every command already passes through: the connection between the agent and the GCP-hosted resource. If you record there, you capture command-level detail by construction, and you capture it independent of whatever the agent chooses to report.
hoop.dev is an open-source Layer 7 access gateway that sits at exactly that point. It proxies the agent's connection to the GCP-hosted target through a network-resident agent, and records each session at the command level as the traffic passes. The agent never sees the recording and cannot reach it.
Setting up session recording with hoop.dev
- Stand up the hoop.dev gateway and register the GCP-hosted connection: a BigQuery dataset, a Cloud SQL Postgres or MySQL instance, or a GKE-hosted service.
- Enable GCP IAM federation on the connection so each session resolves to a per-user short-lived OAuth credential. Now the recording attaches to a real identity, not a shared key everyone hides behind.
- Route the AI agent's access through the gateway. Every query the agent runs is now proxied, and the proxy is where recording happens.
- Verify: run a SELECT and an UPDATE through the agent, then open the session record. You should see both statements verbatim, the identity, timestamps, and the result handling, with no dependence on the agent's own logging.
For database connections that parse the native wire protocol, the recording is command-level. You see the statements, not a vague "session opened" line.
Reading a recording during an incident
When you go back to the table-drop, the session recording answers the questions the agent's logs could not. Which identity opened the session. What exact statement ran. When. Whether it was inside an approved scope. You replay the session instead of reconstructing a story from fragments.
Pitfalls to avoid
- Recording without identity is half a record. Federate identity so each session names an actor.
- Masking and recording are separate controls. Inline data masking redacts sensitive values from results; recording captures the commands. Decide which you need on which connection.
- Recording coverage varies by connector. Native database protocols record at the command level; confirm the behavior for your specific GCP-hosted target in the docs.
FAQ
Does session recording capture the data returned, or just the commands?
It captures the session at the protocol level, including commands. Where you do not want raw values stored or shown, configure inline masking on the connection so sensitive fields are redacted in the result stream.
Can the AI agent disable or edit its own recordings?
No. The recording is captured at the gateway, outside the agent. The agent has no path to the stored record.
What does the recording attribute actions to?
The authenticated identity on the session. With GCP IAM federation, that is a per-user short-lived OAuth credential, so each action maps to a real principal.
To capture session recording for AI agents on GCP, run the gateway yourself: the source is at github.com/hoophq/hoop. Start with the getting started guide and see hoop.dev/learn for the access model.
