feat: universal Studio adapter architecture for any agent framework

- Add StudioAdapter ABC with capabilities, graph, streaming, state, and history methods
- Add LangGraphAdapter with full graph topology, SSE streaming, checkpointer, and breakpoints
- Add GenericAdapter with trace-based SSE, synthetic graphs, and in-memory state/history
- Add @studio_graph, @studio_state, @studio_stream decorators for incremental opt-in
- Add adapter factory (resolve_adapter) with automatic framework detection
- Refactor router.py and run_tracker.py to delegate all framework-specific logic to adapters
- Update studio __init__.py with new public API exports
- Rewrite docs/guide/studio.md with full adapter documentation and decorator examples

Author: piotrlaczkowski

docs/guide/studio.md

@@ -1,58 +1,167 @@
 # Agentomatic Studio 🎨
 
-Agentomatic provides a built-in visual development environment specifically designed to help you debug, inspect, and trace the execution of your agents in real-time. It completely removes the guesswork from debugging multi-agent graphs and provides native support for features like Time-Travel and Conditional Breakpoints.
+Agentomatic provides a built-in visual development environment specifically designed to help you debug, inspect, and trace the execution of your agents in real-time. It works with **any agent framework** — LangGraph, LangChain, CrewAI, AutoGen, or raw Python — via a universal adapter system.
 
 ## Quick Start
 
-You don't need to configure a separate repository or run separate containers. The studio is bundled directly into the `agentomatic` pip package.
-
-To install the optional studio dependencies and launch the server:
+The studio is bundled directly into the `agentomatic` pip package. No separate setup required.
 
 ```bash
 pip install "agentomatic[studio]"
 agentomatic run --studio
 ```
 
-The unified platform will start serving both your API endpoints at `http://localhost:8000` and the Studio UI at `http://localhost:8000/studio/ui/`.
+The unified platform starts serving your API endpoints at `http://localhost:8000` and the Studio UI at `http://localhost:8000/studio/ui/`.
+
+---
+
+## Framework Support
+
+Agentomatic Studio uses a **universal adapter system** to provide the best possible debugging experience for every agent:
+
+| Capability | LangGraph | LangChain / Custom | With Decorators |
+|---|:---:|:---:|:---:|
+| Graph Topology | ✅ Real graph | ✅ Synthetic linear | ✅ Custom graph |
+| SSE Node Streaming | ✅ `astream_events` | ✅ Trace-based | ✅ Custom stream |
+| Time-Travel History | ✅ Checkpointer | ✅ In-memory traces | ✅ In-memory traces |
+| State Inspection | ✅ Checkpointer | ✅ Last I/O capture | ✅ Custom provider |
+| State Mutation | ✅ `aupdate_state` | ⚠️ In-memory only | ⚠️ In-memory only |
+| Breakpoints | ✅ `interrupt_before` | ❌ | ❌ |
+| HITL Support | ✅ Native | ❌ | ❌ |
 
 ---
 
 ## Key Features
 
 ### 1. Live Node Streaming
-When you execute an agent query via the chat interface, the **Graph View** maps directly to your agent's underlying LangGraph topology. As the execution progresses, nodes will visually pulse and light up. 
 
-- Server-Sent Events (SSE) stream the node transitions directly from the backend `astream_events` API.
-- You can follow complex conditional edges and loops perfectly.
+When you execute an agent query, the **Graph View** maps directly to your agent's topology. As the execution progresses, nodes pulse and light up in real-time.
+
+- **LangGraph agents**: Server-Sent Events stream node transitions directly from `astream_events`.
+- **Other agents**: The generic adapter wraps execution with trace events that capture timing, input/output payloads, and exceptions.
 
 ### 2. Time-Travel Debugging
-Debugging deeply nested loops or non-deterministic agent flows can be difficult. Agentomatic natively records every step using the checkpointer.
 
-- **History View**: Inside the Debug Console, the **Time Travel** tab lists all past checkpoints for the active thread.
-- **Replay**: Click **"Replay from here"** on any historical snapshot to branch your thread. The execution will perfectly resume from that prior state, allowing you to try a different input or test a different edge path.
+Agentomatic records every execution step for historical replay.
+
+- **History View**: The **Time Travel** tab lists all past checkpoints (LangGraph) or execution traces (other frameworks).
+- **Replay**: Click **"Replay from here"** on any snapshot to branch your thread and resume from that state.
 
 ### 3. Conditional Breakpoints
-You can freeze execution right before an agent performs a critical action (like calling an external API or making a final decision).
 
-- **Setting Breakpoints**: Right-click any node in the Graph View and select **"Add Breakpoint"**.
-- **Execution**: When the graph reaches that node, it will pause. The node will pulse, and the backend checkpointer will suspend the thread.
-- **Resuming**: You can either resume execution, or edit the state before continuing.
+Freeze execution before a critical node (LangGraph only).
+
+- **Setting Breakpoints**: Right-click any node in the Graph View → **"Add Breakpoint"**.
+- **Execution**: The graph pauses before the target node. The node pulses, and the thread is suspended.
+- **Resuming**: Resume execution or edit the state before continuing.
 
 ### 4. Live State Editing
-While the graph is suspended (either due to a breakpoint or a `Human-in-the-loop` interrupt), you can manually mutate the internal LangGraph state payload.
 
-- **State View**: In the Debug Console, navigate to the **State** tab to see your `StateGraph` variables in real-time.
-- **Editing**: Click **"Edit State"**, modify the JSON directly, and click **"Save"**.
-- **Backend Mutate**: The studio fires an update command which natively triggers `graph.aupdate_state(config, values)`. When you resume execution, the agent will use your injected state!
+During a breakpoint pause or HITL interrupt, you can mutate the graph state.
+
+- **State View**: Navigate to the **State** tab in the Debug Console.
+- **Editing**: Click **"Edit State"**, modify the JSON, and click **"Save"**.
+- **LangGraph**: Changes are persisted via `graph.aupdate_state()`.
+- **Other frameworks**: Changes are stored in the in-memory trace store.
+
+---
+
+## Studio Decorators
+
+For non-LangGraph agents, you can incrementally opt-in to richer Studio capabilities using decorators. These let you provide custom graph topologies, state providers, and stream functions.
+
+### `@studio_graph`
+
+Register a custom graph topology for your agent:
+
+```python
+from agentomatic.studio import studio_graph
+
+@studio_graph
+def my_topology():
+    return {
+        "nodes": [
+            {"id": "__start__", "name": "Start", "type": "start"},
+            {"id": "fetch_data", "name": "Fetch Data", "type": "tool"},
+            {"id": "process", "name": "Process", "type": "agent"},
+            {"id": "validate", "name": "Validate", "type": "condition"},
+            {"id": "__end__", "name": "End", "type": "end"},
+        ],
+        "edges": [
+            {"source": "__start__", "target": "fetch_data"},
+            {"source": "fetch_data", "target": "process"},
+            {"source": "process", "target": "validate"},
+            {"source": "validate", "target": "__end__", "condition": "valid"},
+            {"source": "validate", "target": "process", "condition": "retry"},
+        ]
+    }
+```
+
+### `@studio_state`
+
+Register a custom state provider:
+
+```python
+from agentomatic.studio import studio_state
+
+@studio_state
+async def get_my_state(thread_id: str) -> dict:
+    """Return the current state for a thread."""
+    return await my_database.get_thread_state(thread_id)
+```
+
+### `@studio_stream`
+
+Register a custom SSE event stream:
+
+```python
+from agentomatic.studio import studio_stream
+from agentomatic.studio.models import StudioRunEvent
+
+@studio_stream
+async def my_streamer(state, config, breakpoints):
+    yield StudioRunEvent(event="node_start", run_id="", timestamp="...", node="my_node")
+    result = await my_agent.process(state)
+    yield StudioRunEvent(event="node_end", run_id="", timestamp="...", node="my_node", data={"output": result})
+```
 
 ---
 
-## How It Works Under The Hood
+## Architecture
 
-The Agentomatic Studio is built on React and communicates via standard Agentomatic APIs mounted under the `/studio/` router.
+The Studio uses a layered adapter architecture:
 
-- **Topology Extraction**: `GET /studio/agents/{name}/graph` extracts your node mapping via `graph.get_graph().to_json()`.
-- **SSE Tracking**: `POST /studio/agents/{name}/runs/stream` wraps your execution config with any active breakpoints (`interrupt_before_nodes`). It streams all `on_chat_model_stream`, `on_tool_start`, and custom node events back to the UI.
-- **State Patching**: `POST /studio/agents/{name}/threads/{tid}/state` patches the checkpoint database dynamically.
+```
+┌──────────────────────────────────────────────────────┐
+│                    Studio Router                      │
+│            (FastAPI endpoints at /studio/)             │
+└──────────────────┬───────────────────────────────────┘
+                   │ resolve_adapter(agent)
+    ┌──────────────┼──────────────────┐
+    │              │                  │
+    ▼              ▼                  ▼
+┌────────┐   ┌──────────┐   ┌──────────────┐
+│LangGraph│   │ Generic  │   │   Custom     │
+│Adapter  │   │ Adapter  │   │   Adapter    │
+│ (full)  │   │ (traces) │   │(user-defined)│
+└────────┘   └──────────┘   └──────────────┘
+```
 
-There is no "mock" data — the studio gives you 100% accurate insights into how your code operates in production.
+- **Studio Router**: Framework-agnostic FastAPI endpoints.
+- **Adapter Factory**: Automatically selects the best adapter based on the agent's configuration.
+- **LangGraphAdapter**: Full-featured — uses `CompiledGraph` APIs natively.
+- **GenericAdapter**: Trace-based — wraps `node_fn()` with timing and I/O capture.
+- **Custom Adapter**: User-registered via decorators or direct assignment.
+
+### API Endpoints
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/studio/info` | GET | Platform metadata and capabilities |
+| `/studio/agents` | GET | List agents with capabilities |
+| `/studio/agents/{name}/graph` | GET | Graph topology (real or synthetic) |
+| `/studio/agents/{name}/schemas` | GET | Input/output JSON schemas |
+| `/studio/agents/{name}/runs/stream` | POST | SSE-streamed execution |
+| `/studio/agents/{name}/threads/{tid}/state` | GET | Thread state snapshot |
+| `/studio/agents/{name}/threads/{tid}/state` | POST | Update thread state |
+| `/studio/agents/{name}/threads/{tid}/history` | GET | Checkpoint/trace history |

src/agentomatic/studio/__init__.py

@@ -1,22 +1,37 @@
-"""Agentomatic Studio — Debug & inspection API for frontend tooling.
+"""Agentomatic Studio — Universal Debug & Inspection API.
 
 Provides REST + SSE endpoints for graph visualization, agent execution
-tracing, state inspection, and checkpoint browsing.
+tracing, state inspection, and checkpoint browsing. Works with **any**
+agent framework via the adapter system.
 
 Usage::
 
-    from agentomatic.studio import GraphInspector, RunTracker
+    from agentomatic.studio import StudioAdapter, studio_graph, studio_state
     from agentomatic.studio.router import create_studio_router
+    from agentomatic.studio.adapters import resolve_adapter
 
     router = create_studio_router(registry=registry, store=store)
 """
 
 from __future__ import annotations
 
+from agentomatic.studio.adapter import StudioAdapter
+from agentomatic.studio.decorators import (
+    register_studio_hooks,
+    studio_graph,
+    studio_state,
+    studio_stream,
+)
 from agentomatic.studio.graph_inspector import GraphInspector
 from agentomatic.studio.run_tracker import RunTracker
 
 __all__ = [
     "GraphInspector",
     "RunTracker",
+    "StudioAdapter",
+    "register_studio_hooks",
+    "studio_graph",
+    "studio_state",
+    "studio_stream",
 ]
+

src/agentomatic/studio/adapter.py

@@ -0,0 +1,161 @@
+"""Universal adapter protocol for Agentomatic Studio.
+
+Any agent framework can implement this protocol to unlock the full
+Studio debugging experience. See :class:`LangGraphAdapter` for the
+reference implementation and :class:`GenericAdapter` for the fallback.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agentomatic.studio.models import (
+        StudioCheckpoint,
+        StudioGraphTopology,
+        StudioRunEvent,
+        StudioStateSnapshot,
+    )
+
+
+class StudioAdapter(ABC):
+    """Abstract base class defining the universal Studio interface.
+
+    Every adapter must implement these methods. Methods that are not
+    supported by the underlying framework should return sensible
+    defaults (empty lists, ``None``, etc.) rather than raising.
+
+    Attributes:
+        agent_name: The machine name of the agent this adapter wraps.
+    """
+
+    def __init__(self, agent_name: str) -> None:
+        self.agent_name = agent_name
+
+    # ------------------------------------------------------------------
+    # Capabilities
+    # ------------------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> list[str]:
+        """Return the list of Studio capabilities this adapter supports.
+
+        Possible values: ``'graph'``, ``'streaming'``, ``'checkpoints'``,
+        ``'state'``, ``'breakpoints'``, ``'hitl'``, ``'traces'``.
+        """
+        ...
+
+    @property
+    def supports_graph(self) -> bool:
+        """Whether this adapter can provide a real execution graph."""
+        return "graph" in self.capabilities
+
+    @property
+    def supports_checkpoints(self) -> bool:
+        """Whether this adapter supports checkpoint-based time-travel."""
+        return "checkpoints" in self.capabilities
+
+    @property
+    def supports_state_mutation(self) -> bool:
+        """Whether this adapter supports live state editing."""
+        return "state" in self.capabilities
+
+    @property
+    def supports_breakpoints(self) -> bool:
+        """Whether this adapter supports conditional breakpoints."""
+        return "breakpoints" in self.capabilities
+
+    # ------------------------------------------------------------------
+    # Graph topology
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def get_graph(self) -> StudioGraphTopology:
+        """Return the agent's execution graph topology.
+
+        Returns:
+            A :class:`StudioGraphTopology` describing the nodes and edges.
+            For adapters that don't support real graphs, return a synthetic
+            linear topology.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Execution streaming
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def stream_execution(
+        self,
+        state: dict[str, Any],
+        config: dict[str, Any] | None = None,
+        breakpoints: list[str] | None = None,
+        checkpoint_id: str | None = None,
+    ) -> AsyncGenerator[StudioRunEvent, None]:
+        """Execute the agent and yield events as they occur.
+
+        Args:
+            state: Initial state dict to pass to the agent.
+            config: Optional execution configuration (e.g. thread_id).
+            breakpoints: Optional list of node names to pause before.
+            checkpoint_id: Optional checkpoint to resume from.
+
+        Yields:
+            :class:`StudioRunEvent` instances for each notable step.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # State inspection
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def get_state(self, thread_id: str) -> StudioStateSnapshot | None:
+        """Retrieve the latest state for a thread.
+
+        Args:
+            thread_id: The conversation thread identifier.
+
+        Returns:
+            A :class:`StudioStateSnapshot`, or ``None`` if state
+            inspection is not supported.
+        """
+        ...
+
+    @abstractmethod
+    async def update_state(
+        self,
+        thread_id: str,
+        updates: dict[str, Any],
+    ) -> StudioStateSnapshot | None:
+        """Apply a partial state update to a thread.
+
+        Args:
+            thread_id: The conversation thread identifier.
+            updates: Key-value pairs to merge into the current state.
+
+        Returns:
+            The updated :class:`StudioStateSnapshot`, or ``None`` if
+            state mutation is not supported.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Checkpoint history
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def get_history(self, thread_id: str) -> list[StudioCheckpoint]:
+        """Return the checkpoint history for a thread.
+
+        Args:
+            thread_id: The conversation thread identifier.
+
+        Returns:
+            A list of :class:`StudioCheckpoint` objects, newest first.
+            Returns an empty list if checkpoints are not supported.
+        """
+        ...