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.
Clean roomReconstruction of patterns I own. No Blackstraw code, data, prompts or clients.
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
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
- 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
Show the numbers as a table
| Step | Actor | Tool | Scope | Sim latency (ms) | What happened |
|---|---|---|---|---|---|
| No steps yet. | |||||
| # | Step | Agent | Tool | Scope | Sim latency (ms) | Args digest (SHA-256) |
|---|---|---|---|---|---|---|
| No MCP calls yet. | ||||||
| Revision | Status | Last writer | Approved writes committed | Checkpoint (step) |
|---|---|---|---|---|
| 12 | open | seed | 0 | 0 |