Breakpoints for AI Agents
The first open-source, framework-agnostic visual debugger with live intervention for multi-agent systems.
Quick Start • Why Sutures • Features • Architecture • Adapters • Protocol Spec
Created by Anup Karanjkar · 12+ years building digital products
Scalpel cuts into your codebase. Sutures traces how everything connects.
From the creator of Scalpel — Surgical AI for your codebase.
Every multi-agent framework gives you logs after the fact. None let you see, pause, and fix a running swarm in real-time.
❌ Agent stuck in a loop? → Parse 2000 lines of JSON
❌ Hallucination cascading across agents? → Restart the entire run
❌ Cost exploding unexpectedly? → Find out after $50 is burned
❌ Which agent broke the chain? → Manual log archaeology
89% of organizations have implemented agent observability, but 65% still cite monitoring as their #1 challenge (PwC 2026, Gartner). Academic research (CHI 2025, Microsoft) proved developers want breakpoints for agents — but no productized tool exists.
Until now.
from sutures_langgraph import SuturesTracer
tracer = SuturesTracer(endpoint="ws://localhost:9470/v1/events")
result = app.invoke(input_data, config={"callbacks": [tracer]})import { createSutures } from '@sutures/core';
const sutures = createSutures();
await sutures.connect();
sutures.agentSpawned('researcher', { name: 'Researcher', role: 'research', model: 'claude-sonnet-4-20250514', tools: ['web_search'] });# Pause when cost exceeds $0.50
tracer.set_breakpoint(node="*", condition="on_cost", max_usd=0.50)
# Pause on any tool call to "web_search"
tracer.set_breakpoint(node="researcher", condition="on_tool", tool_name="web_search")
# Pause on every turn of the critic agent
tracer.set_breakpoint(node="critic", condition="always")| Capability | Langfuse | LangSmith | AgentOps | AgentPrism | AutoGen Studio | Sutures |
|---|---|---|---|---|---|---|
| Open source | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |
| Framework-agnostic | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ |
| Live visual topology | ❌ | ❌ | Partial | ❌ | Partial | ✅ |
| Breakpoints (pause/inject/resume) | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Live intervention | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| OTEL-native | ✅ | Partial | ❌ | ✅ | ❌ | ✅ |
| Standalone tool | SaaS | SaaS | SaaS | Library | Locked | ✅ |
Sutures is the only tool that gives you gdb for AI agents.
Set conditional breakpoints on any agent. Pause execution when:
- A specific agent runs (
on_turn) - A tool is called (
on_tool) - Cost exceeds threshold (
on_cost) - An error occurs (
on_error) - Any handoff happens (
on_handoff)
When paused at a breakpoint:
- Inspect full agent state, messages, and memory
- Inject modified messages or tool results
- Change the model mid-run
- Resume and watch the effect
Real-time force-directed graph showing:
- Agent nodes with state indicators (thinking/acting/idle/paused/error)
- Handoff edges with active animation
- Click any agent to inspect context window and tool calls
Scrubber-based replay of every agent step:
- Fork from any point to test alternative paths
- Compare original vs. modified execution
- Export as shareable HTML report
Per-agent, per-model token and dollar tracking:
- Running cumulative cost with automatic alerts
- Model-specific pricing for 6+ providers
- Cost-per-turn breakdown
Works alongside your existing observability stack:
- Export to Langfuse, LangSmith, Arize, Datadog, Grafana
- Standard GenAI semantic conventions
- Zero vendor lock-in
┌─────────────────────────────────────────────────┐
│ Your Multi-Agent System │
│ (LangGraph, CrewAI, OpenAI Agents, AutoGen) │
└───────────────┬─────────────────────────────────┘
│ Adapter (3 lines of code)
▼
┌─────────────────────────────────────────────────┐
│ Sutures Collector (WebSocket) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Event │ │Checkpoint│ │ Breakpoint │ │
│ │ Buffer │ │ Store │ │ Engine │ │
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│ └──────────────┴───────────────┘ │
└───────────────┬─────────────────────────────────┘
│ AgentEvent Protocol (v1.0)
▼
┌─────────────────────────────────────────────────┐
│ Sutures Dashboard (UI) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Topology │ │ Timeline │ │ Breakpoint │ │
│ │ Canvas │ │ Scrubber │ │ Console │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Cost │ │ Agent │ │
│ │Inspector │ │Inspector │ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────┘
│ Optional: OTEL export
▼
Langfuse / LangSmith / Arize / Datadog
Sutures defines an open protocol — 26 event types across 6 categories:
| Category | Events | Purpose |
|---|---|---|
| Lifecycle | agent.spawned, .idle, .completed, .failed, .paused, .resumed |
Track agent state |
| Reasoning | turn.thinking, .thought, .acting, .observed, .completed, .failed |
Trace LLM inference + tool calls |
| Collaboration | handoff.initiated, .accepted, .rejected, .completed |
Map agent-to-agent communication |
| Memory | memory.write, .read, checkpoint.created |
Track shared state |
| Intervention | breakpoint.set, .hit, .inject, .release |
Enable live debugging |
| Cost | cost.tokens, .api_call |
Track spend |
Full spec: AGENT_EVENT_PROTOCOL.md
| Adapter | Framework | Status | Install |
|---|---|---|---|
sutures-langgraph |
LangGraph | ✅ Alpha | pip install sutures-langgraph |
@sutures/core |
Generic (any framework) | ✅ Alpha | npm install @sutures/core |
@sutures/adapter-crewai |
CrewAI | 🔜 Next | — |
@sutures/adapter-openai |
OpenAI Agents SDK | 🔜 Planned | — |
@sutures/adapter-autogen |
AutoGen/AG2 | 🔜 Planned | — |
Every adapter implements a simple interface:
interface SuturesAdapter {
init(config: SuturesConfig): Promise<void>;
instrument(): void;
checkpoint(agentId: string): Promise<CheckpointData>;
restore(checkpointId: string): Promise<void>;
inject(agentId: string, injection: BreakpointInjectData): Promise<void>;
resume(agentId: string): Promise<void>;
shutdown(): Promise<void>;
}sutures/
├── AGENT_EVENT_PROTOCOL.md # Open protocol specification
├── packages/
│ ├── core/ # @sutures/core (TypeScript)
│ │ ├── types.ts # All type definitions
│ │ ├── client.ts # WebSocket client + event emitter
│ │ ├── otel-mapper.ts # OTEL span mapper
│ │ └── index.ts # Barrel exports
│ ├── adapter-langgraph/ # Python adapter for LangGraph
│ │ └── sutures_langgraph.py
│ ├── adapter-generic/ # Generic adapter (coming)
│ └── collector/ # WebSocket collector server (coming)
└── apps/
└── dashboard/ # React Flow visual debugger (coming)
- AgentEvent Protocol v1.0 specification
- Core TypeScript types + WebSocket client
- OTEL span mapper (GenAI semantic conventions)
- LangGraph Python adapter with breakpoint engine
- WebSocket collector server
- React Flow live topology canvas
- Execution timeline with fork/replay
- Breakpoint intervention console
- CrewAI adapter
- OpenAI Agents SDK adapter
-
npx sutureszero-config launcher - Shareable HTML trace export
- Docker one-liner deployment
- Scalpel — Surgical AI for your codebase (by the same author)
- AgentPrism — React components for trace visualization (complementary)
- AGDebugger — Academic research on interactive multi-agent debugging (CHI 2025)
- DoVer — Intervention-driven auto debugging for multi-agent systems
We welcome contributions! See CONTRIBUTING.md for guidelines.
Key areas where help is needed:
- 🎨 Dashboard UI — React Flow canvas, timeline, breakpoint console
- 🔌 Adapters — CrewAI, OpenAI Agents SDK, AutoGen, Google ADK
- 📖 Documentation — Tutorials, integration guides
- 🧪 Testing — Protocol conformance tests, adapter tests
Apache 2.0 — see LICENSE
Created by Anup Karanjkar · anupkaranjkar.com