Skip to content

Sketchbook / case study · see it on its sheet

Production agents at Blackstraw.ai

A supervisor, specialist agents, scoped tools, durable state, and a human before every write.

Dates
Aug 2025–now
Team
team at Blackstraw.ai
My part
Persistence layer, AG-UI adapter, run cancellation, MCP audit trail, tests (contributor to the orchestration system)
Stack
Python · LangGraph · A2A · MCP · PostgreSQL · SSE · GCP
Verified
3 specialist agents behind the supervisor28+ tests I wrote
Result
in production

Context

At Blackstraw.ai I work on production multi-agent systems. I joined as SDE I in August 2025 and was promoted to SDE II in July 2026. This page describes the patterns I own. It contains no company code, data, prompts or client details.

The shape

A supervisor routes work to specialist agents. Specialists act only through scoped tools: they can read, and they can propose a write. A human approves anything that writes. Everything streams to the client.

What I built

  • Durable agent state. Optimistic concurrency with revision-based conflict detection, keyset pagination for large lists, and full-text search. A stale write is rejected by revision rather than hidden by a lock.
  • Two drivers, one data layer. A checkpointing library and the cloud database connector needed different drivers. I diagnosed the constraint and built a second async data path so IAM-based authentication kept working.
  • An audit trail with no secrets in it. Every tool call is logged with its latency and a SHA-256 digest of its arguments; the raw arguments are never stored.
  • One way to stop. A user's cancel and a dropped stream end in the same shutdown path, so nothing is left half-running.
  • A protocol adapter. A second front end can drive the same agents through the AG-UI protocol with zero backend changes.
  • Conversation sync. A client-side store that merges conversations created offline, debounces persistence and recovers from revision conflicts.
  • Tests. I wrote 28+ tests for cross-user authorization, stale-write rejection and pagination edge cases.

Decisions

  • Human approval before any write. Agents propose; people dispose.
  • Revisions instead of locks. Conflicts are detected and resolved, not prevented by blocking.
  • Digests, not arguments. The audit trail can prove what was called without becoming a store of sensitive inputs.
Production multi-agent patternA client streams to a supervisor, which routes to three specialist agents. Specialists act only through scoped MCP tools. Any write goes through human approval before reaching durable state. Every tool call is recorded in an audit trail with its latency and a digest of its arguments. Cancelling and a dropped stream share one shutdown path.Any clientUI · SSE streamSupervisorroutes the workSpecialist ASpecialist BSpecialist CScoped MCP toolsread · propose-writeHuman approvalbefore any writeDurable staterevisions · keyset · FTSAudit traillatency · sha256(args)One shutdown pathclient cancel = stream drop
The pattern, not the product. Green = adjustable parts · vermilion = where a human decides.
Run Desk

Clean roomReconstruction of patterns I own. No Blackstraw code, data, prompts or clients.

Architecture: you, over SSE, to a supervisor that routes to 3 specialists. Specialists call scoped MCP tools. Reads go straight to the store; a propose-write stops at the approval gate, and only an approved proposal is written to the store. Record #42 is at rev 12.SSEpropose-writeapproved onlyreadyou · browsersupervisorroutes · holds no toolsA · readerreadB · analystreadC · editorread · proposeMCP server · scoped toolsevery call → audit row (digest)approval gate · younothing passes without youstore · record #42rev 12 · openlast writer: seed

Supervisor → 3 specialists → scoped tools. The supervisor and specialists are a team system I contributed to; the durable state with revisions, run cancellation and the MCP audit trail are my parts, checked by 28+ tests I wrote for authorization, stale writes and pagination.

1 · Give the supervisor a task

IDLEidle · give the supervisor a taskcheckpoint · step 0

2 · Approval gate

No write pending. Specialists hold no write scope: every propose-write stops here.

3 · Two ways to stop, one handler

stops the run, drops any proposal not yet written, keeps the checkpoint

4 · Another writer

No locks. A pending write carries the revision it read; the store writes only if that revision still holds, else the run re-reads and proposes again.

Run trace

  1. Nothing yet. Pick a task above.

5 · MCP audit log

Each call keeps tool, scope, latency and a SHA-256 of its arguments. Raw arguments are never stored.

No MCP calls yet. Every specialist tool call lands here.

6 · Check a digest

Start a run, then pick an audit row: you can edit the arguments it was made from and watch the digest stop matching.

idle · give the supervisor a task

Reconstruction: patterns from my production work, rebuilt from scratch with simulated timings
Show the numbers as a table
Run trace · idle · give the supervisor a task
StepActorToolScopeSim latency (ms)What happened
No steps yet.
MCP audit log (arguments are not stored)
#StepAgentToolScopeSim latency (ms)Args digest (SHA-256)
No MCP calls yet.
Record #42 (durable, survives runs)
RevisionStatusLast writerApproved writes committedCheckpoint (step)
12openseed00