My agent lives on AGY agents

FleetScope — Watch your agents work

I built FleetScope because I kept running into the same problem while working with AI agents: the agent was doing a lot of work, but I could not clearly see what had actually happened.

A multi-agent workflow might call several tools, delegate tasks, wait for responses, fail halfway through, and eventually produce one final answer. From the outside, that can look impressive. But when something goes wrong, the experience usually becomes a wall of JSONL, terminal output, and timestamps.

Which agent actually ran?

Which tool call is still waiting?

Did the workflow finish successfully, or did it simply stop producing logs?

And if I want to understand the same run again, do I really need to call the model one more time?

FleetScope is my attempt to solve that problem.

It is a read-only Session Observer for multi-agent workflows. A producer such as Gemini and Google ADK writes an append-only session log. FleetScope reads that log and turns it into a graph of agents, tools, results, failures, and terminal states.

The important design decision is that FleetScope does not take control of the agent. It does not start an agent, approve an action, retry a tool, or mutate the workflow. The producer owns execution. FleetScope owns observation and explanation.

The demo workflow

The demo is a small Google Cloud launch-readiness workflow built with Google ADK.

The root workflow contains four visible tasks:

cloud_run_probe checks the configured Cloud Run service using a read-only services.get call.
storage_probe checks the configured Cloud Storage bucket using a read-only buckets.get call.
budget_guard verifies the model-call limit, timeout, number of cloud reads, and zero workflow writes.
launch_reviewer combines the reports and produces a final READY or NOT_READY decision.

The workflow is intentionally bounded. It has a fixed six-call model budget and a maximum runtime of 180 seconds. The goal is not to create an unrestricted autonomous system. The goal is to make one real multi-step workflow understandable from beginning to end.

In recorded mode, FleetScope can run without a model, API key, cloud service, or network connection. When the live path is explicitly enabled, the producer uses Google ADK with Vertex AI and a Gemini model, then writes the observed events to JSONL as they arrive.

How I built it

The producer is written in Python and uses the pinned google-adk==2.8.0 runtime. It creates a fixed SequentialAgent workflow and records the real ADK event stream.

The viewer is built around a deterministic projection core. The same event data can be opened through:

a native CLI viewer;
an Astro/WASM browser viewer;
a headless inspect command.

This means the browser and the CLI are not creating separate interpretations of the workflow. They are looking at the same normalized session model.

FleetScope provides four synchronized views:

an agent rail showing which agents exist;
a parent/child graph showing the workflow topology;
an event inspector for messages, tools, results, and errors;
a timeline for live follow and replay.

A growing JSONL file can be followed while the workflow is running. Once the producer stops, the same file becomes a replayable session. I can pause, seek, step through events, change playback speed, and return to the live edge without starting the workflow again.

What I learned

The biggest thing I learned is that observability must not invent state.

Silence is not success. If a tool call has no response, FleetScope shows it as waiting. If there is no explicit terminal event, FleetScope does not quietly label the workflow as complete just because the last visible event looked positive.

I also learned that configured values and observed values are different things. A configuration may say that the system intends to use a particular Gemini model, but that is not proof that the provider actually executed that model. FleetScope keeps the configured model separate from the provider-owned model version observed in the event stream.

Another important lesson was that security is not only about adding an authentication screen. It is also about controlling the shape of the data that enters the viewer. Hidden reasoning parts are removed. Secret-shaped fields are redacted. Cloud responses are reduced to the small set of readiness facts the demo actually needs.

Finally, I learned that live mode and replay should not be two completely different products. They are the same ordered event timeline. The only difference is whether the right edge is still moving.

The hardest parts

The most difficult part was working with asynchronous ADK events. A model call, tool call, tool result, agent transition, and terminal event do not always arrive in the simple order that a human expects. I had to make the event translation deterministic while still preserving the producer's original evidence.

Incremental JSONL was another challenge. A live viewer may read a file while it is still being written, so partial lines, duplicate events, missing terminal events, and out-of-order timestamps all need safe handling.

I also had to be careful not to record everything twice. ADK exposes callbacks and event streams, but using both carelessly can create duplicate tool calls and misleading timelines. FleetScope uses the runtime event stream as the primary evidence source and keeps the projection layer provider-neutral.

The final challenge was scope. It was tempting to turn FleetScope into a full agent control plane with approvals, retries, identity, memory, and enterprise orchestration. But that would have made the product larger and less trustworthy. I chose to focus on one clear promise: