deepagents-serve 0.1.0__py3-none-any.whl

deepagents_serve/__init__.py

@@ -0,0 +1,5 @@
+"""deepagents-serve: universal agent server for LangGraph graphs."""
+
+from deepagents_serve.app import DeepAgentsServeApp
+
+__all__ = ["DeepAgentsServeApp"]

deepagents_serve/adapter/__init__.py

@@ -0,0 +1 @@
+"""Adapters that encode :data:`~deepagents_serve.events.AgentEvent` values into protocol-specific SSE streams."""

deepagents_serve/adapter/vercel.py

@@ -0,0 +1,81 @@
+"""Encode :data:`~deepagents_serve.events.AgentEvent` values as Vercel AI Data Protocol SSE frames."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import TYPE_CHECKING
+
+from deepagents_serve import events
+from deepagents_serve.adapter import vercel_protocol as protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from deepagents_serve.events import AgentEvent
+
+
+class VercelAIProtocolAdapter:
+    """Stateful adapter that converts :class:`~deepagents_serve.events.AgentEvent` values into Vercel AI Data Protocol SSE frames.
+
+    Tracks open text/reasoning/tool-input blocks so that ``*-start`` and ``*-end``
+    frames are emitted correctly around delta streams.
+    """
+
+    def __init__(self) -> None:
+        """Initialise with no active blocks."""
+        self._active_text_id: str | None = None
+        self._active_reasoning_id: str | None = None
+        self._active_tool_input_id: str | None = None
+
+    def encode(self, agent_event: AgentEvent) -> Iterator[str]:
+        """Encode a single :class:`~deepagents_serve.events.AgentEvent` as one or more SSE data lines."""
+        for part in self._to_parts(agent_event):
+            yield f"data: {json.dumps(dataclasses.asdict(part))}\n\n"
+
+    def flush(self) -> Iterator[str]:
+        """Close any open text/reasoning blocks after the stream ends."""
+        for part in self._flush_parts():
+            yield f"data: {json.dumps(dataclasses.asdict(part))}\n\n"
+
+    def _to_parts(self, agent_event: AgentEvent) -> Iterator[protocol.StreamPart]:  # noqa: C901
+        match agent_event:
+            case events.TextDelta(id=id, content=content):
+                if id != self._active_text_id:
+                    if self._active_text_id is not None:
+                        yield protocol.TextEnd(id=self._active_text_id)
+                    yield protocol.TextStart(id=id)
+                    self._active_text_id = id
+                yield protocol.TextDelta(id=id, delta=content)
+
+            case events.ReasoningDelta(id=id, content=content):
+                if id != self._active_reasoning_id:
+                    if self._active_reasoning_id is not None:
+                        yield protocol.ReasoningEnd(id=self._active_reasoning_id)
+                    yield protocol.ReasoningStart(id=id)
+                    self._active_reasoning_id = id
+                yield protocol.ReasoningDelta(id=id, delta=content)
+
+            case events.ToolInputDelta(id=id, name=name, args_delta=args_delta):
+                if id != self._active_tool_input_id:
+                    yield protocol.ToolInputStart(toolCallId=id, toolName=name)
+                    self._active_tool_input_id = id
+                yield protocol.ToolInputDelta(toolCallId=id, inputTextDelta=args_delta)
+
+            case events.ToolOutputAvailable(id=id, output=output):
+                yield protocol.ToolOutputAvailable(toolCallId=id, output=output)
+
+            case events.Error(text=text):
+                yield protocol.ErrorPart(errorText=text)
+
+            case events.Abort(reason=reason):
+                yield protocol.AbortPart(reason=reason)
+
+    def _flush_parts(self) -> Iterator[protocol.StreamPart]:
+        if self._active_text_id is not None:
+            yield protocol.TextEnd(id=self._active_text_id)
+            self._active_text_id = None
+        if self._active_reasoning_id is not None:
+            yield protocol.ReasoningEnd(id=self._active_reasoning_id)
+            self._active_reasoning_id = None
+        self._active_tool_input_id = None

deepagents_serve/adapter/vercel_protocol.py

@@ -0,0 +1,193 @@
+"""Vercel AI Data Protocol stream-part dataclasses.
+
+Field names are intentionally camelCase to match the JSON field names defined by the
+`Vercel AI Data Protocol <https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol>`_.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class MessageStart:
+    """Signals the start of a new AI message."""
+
+    messageId: str
+    type: str = field(default="start", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class TextStart:
+    """Signals the start of a text content block."""
+
+    id: str
+    type: str = field(default="text-start", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class TextDelta:
+    """A text content fragment."""
+
+    id: str
+    delta: str
+    type: str = field(default="text-delta", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class TextEnd:
+    """Signals the end of a text content block."""
+
+    id: str
+    type: str = field(default="text-end", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningStart:
+    """Signals the start of a reasoning/thinking block."""
+
+    id: str
+    type: str = field(default="reasoning-start", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningDelta:
+    """A reasoning/thinking content fragment."""
+
+    id: str
+    delta: str
+    type: str = field(default="reasoning-delta", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningEnd:
+    """Signals the end of a reasoning/thinking block."""
+
+    id: str
+    type: str = field(default="reasoning-end", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class SourceUrl:
+    """A source URL citation."""
+
+    sourceId: str
+    url: str
+    type: str = field(default="source-url", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class SourceDocument:
+    """A source document citation."""
+
+    sourceId: str
+    mediaType: str
+    title: str
+    type: str = field(default="source-document", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class FilePart:
+    """A file attachment part."""
+
+    url: str
+    mediaType: str
+    type: str = field(default="file", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorPart:
+    """A non-fatal error part."""
+
+    errorText: str
+    type: str = field(default="error", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInputStart:
+    """Signals the start of a tool-call input stream."""
+
+    toolCallId: str
+    toolName: str
+    type: str = field(default="tool-input-start", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInputDelta:
+    """A streamed fragment of a tool-call input JSON string."""
+
+    toolCallId: str
+    inputTextDelta: str
+    type: str = field(default="tool-input-delta", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInputAvailable:
+    """The complete, parsed input for a tool call."""
+
+    toolCallId: str
+    toolName: str
+    input: Any
+    type: str = field(default="tool-input-available", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolOutputAvailable:
+    """The output of a completed tool call."""
+
+    toolCallId: str
+    output: Any
+    type: str = field(default="tool-output-available", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class StartStep:
+    """Signals the start of an agent reasoning step."""
+
+    type: str = field(default="start-step", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class FinishStep:
+    """Signals the end of an agent reasoning step."""
+
+    type: str = field(default="finish-step", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class FinishMessage:
+    """Signals that the full AI message is complete."""
+
+    type: str = field(default="finish", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class AbortPart:
+    """Signals that the stream was aborted."""
+
+    reason: str | None = None
+    type: str = field(default="abort", init=False)
+
+
+StreamPart = (
+    MessageStart
+    | TextStart
+    | TextDelta
+    | TextEnd
+    | ReasoningStart
+    | ReasoningDelta
+    | ReasoningEnd
+    | SourceUrl
+    | SourceDocument
+    | FilePart
+    | ErrorPart
+    | ToolInputStart
+    | ToolInputDelta
+    | ToolInputAvailable
+    | ToolOutputAvailable
+    | StartStep
+    | FinishStep
+    | FinishMessage
+    | AbortPart
+)

deepagents_serve/app.py

@@ -0,0 +1,33 @@
+"""DeepAgentsServeApp — wraps a LangGraph graph and exposes it via Starlette."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from starlette.applications import Starlette
+
+from deepagents_serve.route.health import router as health_router
+from deepagents_serve.route.vercel import router as vercel_router
+
+
+class DeepAgentsServeApp:
+    """Builds a Starlette ASGI application from any compiled LangGraph graph.
+
+    Args:
+        graph: A compiled LangGraph graph (or any object with an ``astream`` method).
+    """
+
+    def __init__(self, graph: Any) -> None:
+        """Initialise with a compiled LangGraph graph."""
+        self._graph = graph
+
+    def build(self) -> Starlette:
+        """Assemble and return the Starlette ASGI application."""
+        app = Starlette(
+            routes=[
+                *health_router.routes,
+                *vercel_router.routes,
+            ]
+        )
+        app.state.graph = self._graph
+        return app

deepagents_serve/events.py

@@ -0,0 +1,53 @@
+"""Canonical agent event types emitted by the normaliser."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class TextDelta:
+    """A streamed text content fragment from an AI message."""
+
+    id: str
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningDelta:
+    """A streamed reasoning/thinking fragment from an AI message."""
+
+    id: str
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolInputDelta:
+    """A streamed partial argument string for a tool call."""
+
+    id: str
+    name: str
+    args_delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolOutputAvailable:
+    """The complete output of a finished tool call."""
+
+    id: str
+    output: str
+
+
+@dataclass(frozen=True, slots=True)
+class Error:
+    """A non-fatal error event from the agent."""
+
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class Abort:
+    """Signals that the agent stream was aborted."""
+
+    reason: str | None = None
+
+
+AgentEvent = TextDelta | ReasoningDelta | ToolInputDelta | ToolOutputAvailable | Error | Abort

deepagents_serve/normaliser.py

@@ -0,0 +1,54 @@
+"""Normalise LangGraph ``stream_mode='messages'`` output into :data:`AgentEvent` values."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.messages import AIMessage, AIMessageChunk, ToolMessage
+
+from deepagents_serve.events import (
+    AgentEvent,
+    TextDelta,
+    ToolInputDelta,
+    ToolOutputAvailable,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator
+
+
+async def normalize(stream: AsyncIterator[Any]) -> AsyncIterator[AgentEvent]:
+    """Yield :class:`AgentEvent` values from a LangGraph messages stream."""
+    async for message, _metadata in stream:
+        for agent_event in _parse_message(message):
+            yield agent_event
+
+
+def _parse_message(message: Any) -> Iterator[AgentEvent]:
+    if isinstance(message, (AIMessage, AIMessageChunk)):
+        yield from _parse_ai_message(message)
+    elif isinstance(message, ToolMessage):
+        yield ToolOutputAvailable(id=message.tool_call_id, output=str(message.content))
+
+
+def _parse_ai_message(message: AIMessage | AIMessageChunk) -> Iterator[AgentEvent]:
+    msg_id = message.id or "msg"
+    content = message.content
+
+    if isinstance(content, str):
+        if content:
+            yield TextDelta(id=msg_id, content=content)
+    elif isinstance(content, list):
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "text" and block.get("text"):
+                yield TextDelta(id=msg_id, content=block["text"])
+
+    for tool_call in getattr(message, "tool_call_chunks", []):
+        if tool_call.get("args"):
+            yield ToolInputDelta(
+                id=tool_call["id"] or msg_id,
+                name=tool_call.get("name", ""),
+                args_delta=tool_call["args"],
+            )

deepagents_serve/route/__init__.py

@@ -0,0 +1 @@
+"""Starlette route definitions for the deepagents-serve endpoints."""

deepagents_serve/route/health.py

@@ -0,0 +1,24 @@
+"""Health and readiness check endpoints."""
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route, Router
+
+
+async def _health(_request: Request) -> JSONResponse:
+    return JSONResponse({"status": "ok"})
+
+
+async def _ready(request: Request) -> JSONResponse:
+    graph = request.app.state.graph
+    if graph is None:
+        return JSONResponse({"status": "not ready"}, status_code=503)
+    return JSONResponse({"status": "ready"})
+
+
+router = Router(
+    routes=[
+        Route("/health", _health, methods=["GET"]),
+        Route("/ready", _ready, methods=["GET"]),
+    ]
+)

deepagents_serve/route/vercel.py

@@ -0,0 +1,49 @@
+"""Vercel AI Data Protocol streaming chat endpoint."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from starlette.responses import StreamingResponse
+from starlette.routing import Route, Router
+
+from deepagents_serve.adapter.vercel import VercelAIProtocolAdapter
+from deepagents_serve.normaliser import normalize
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from starlette.requests import Request
+
+# TODO: formalise request schema with a dataclass/Pydantic model
+# Expected shape: {"messages": [{"role": "user"|"assistant", "content": str}]}
+
+
+async def _chat_stream(request: Request) -> StreamingResponse:
+    body = await request.json()
+    messages = body.get("messages", [])
+    graph = request.app.state.graph
+
+    async def event_generator() -> AsyncIterator[str]:
+        adapter = VercelAIProtocolAdapter()
+        stream = graph.astream({"messages": messages}, stream_mode="messages")
+
+        async for agent_event in normalize(stream):
+            for chunk in adapter.encode(agent_event):
+                yield chunk
+
+        for chunk in adapter.flush():
+            yield chunk
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+router = Router(
+    routes=[
+        Route("/chat/stream", _chat_stream, methods=["POST"]),
+    ]
+)

deepagents_serve-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: deepagents_serve
+Version: 0.1.0
+Summary: Universal agent server. Wraps any LangGraph graph and exposes it over standard agent protocols — Vercel AI SDK, Claude Code, TUIs, and more.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/FengJi2021/deepagents-serve
+Project-URL: Repository, https://github.com/FengJi2021/deepagents-serve
+Project-URL: Issues, https://github.com/FengJi2021/deepagents-serve/issues
+Keywords: agents,ai,llm,langgraph,langchain,agent-server,vercel-ai,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: starlette>=0.46.0
+Requires-Dist: uvicorn>=0.34.0
+Requires-Dist: langgraph>=0.4.0
+Requires-Dist: langchain-core>=0.3.0
+
+# deepagents-serve
+
+Universal agent server. Wraps any LangGraph graph and exposes it over standard agent protocols — Vercel AI SDK, Claude Code, TUIs, and more.
+
+## Quick start
+
+```python
+from deepagents_serve import DeepAgentsServeApp
+from deepagents import create_deep_agent
+import uvicorn
+
+agent = create_deep_agent(
+    model="anthropic:claude-opus-4-8",
+    skills=["myskillsregistry/skills"],
+    system_prompt="You are a helpful assistant."
+)
+
+app = DeepAgentsServeApp(agent)
+
+uvicorn.run(app.build(), host="0.0.0.0", port=8000)
+```
+
+---
+
+## Endpoint design
+
+### `POST /chat/stream`
+
+Stateless. One request, one SSE stream, done. No session state is kept between calls.
+
+**Request**
+
+```json
+{
+  "messages": [
+    {"role": "user", "content": "List the files in the working directory."}
+  ]
+}
+```
+
+**Response** — `Content-Type: text/event-stream`
+
+Uses the [Vercel AI Data Protocol](https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol). Each line is `data: <json>`:
+
+```text
+data: {"type": "text-start", "id": "msg_01"}
+data: {"type": "text-delta", "id": "msg_01", "delta": "Here are the files:\n"}
+data: {"type": "text-end", "id": "msg_01"}
+
+data: {"type": "tool-input-start", "toolCallId": "tc_01", "toolName": "bash"}
+data: {"type": "tool-input-delta", "toolCallId": "tc_01", "inputTextDelta": "{\"command\":\"ls\"}"}
+data: {"type": "tool-output-available", "toolCallId": "tc_01", "output": "README.md\nsrc/"}
+
+data: {"type": "reasoning-start", "id": "r_01"}
+data: {"type": "reasoning-delta", "id": "r_01", "delta": "I should list the files..."}
+data: {"type": "reasoning-end", "id": "r_01"}
+
+data: {"type": "error", "errorText": "something went wrong"}
+data: {"type": "abort", "reason": "user cancelled"}
+data: {"type": "finish"}
+```
+
+---
+
+## Signal diagram
+
+```text
+Client (Vercel SDK / Claude Code / TUI)
+  │
+  │  POST /chat/stream
+  │  {"messages": [{"role": "user", "content": "..."}]}
+  ▼
+┌──────────────────┐
+│  Input Parser    │  extract last user message from messages array
+└────────┬─────────┘
+         │ {"role": "user", "content": "..."}
+         ▼
+┌──────────────────┐
+│  LangGraph Graph │  graph.astream({"messages": [...]}, stream_mode=["messages"])
+└────────┬─────────┘
+         │ (stream_part, metadata) chunks
+         ▼
+┌──────────────────┐
+│  Normaliser      │  LangGraph messages → canonical AgentEvent
+│                  │
+│  AIMessage       │→  TextDelta | ReasoningDelta
+│  ToolCall        │→  ToolInputDelta
+│  ToolMessage     │→  ToolOutputAvailable
+│  Error           │→  Error | Abort
+└────────┬─────────┘
+         │ AgentEvent
+         ▼
+┌──────────────────┐
+│  Vercel Adapter  │  AgentEvent → Vercel SSE stream parts
+└────────┬─────────┘
+         │ text/event-stream
+         ▼
+Client
+```
+
+---
+
+## Roadmap
+
+**Near-term**
+
+- [ ] Input parsing — read request body, extract messages
+- [ ] Complete normaliser — tool calls, tool results, reasoning deltas from LangGraph
+- [ ] Request validation — reject malformed payloads at the boundary
+
+**Protocol compatibility**
+
+- [ ] Claude Managed Agents endpoints — `/v1/sessions`, `/v1/sessions/{id}/events`, `/v1/sessions/{id}/events/stream`
+- [ ] Claude Managed Agents SSE encoding — `agent.message`, `agent.tool_use`, `session.status_idle` event types
+- [ ] Agent metadata endpoint — `GET /v1/agents/default`
+
+**Statefulness**
+
+- [ ] Session layer — LangGraph `thread_id` checkpointing, `session_id` → `thread_id` mapping
+- [ ] Multi-turn conversations — persist conversation history across requests
+- [ ] Interrupt support — `user.interrupt` event stops graph mid-execution
+
+**Deployment**
+
+- [ ] kagent packaging — Kubernetes-compatible worker pattern
+
+**Eval**
+
+- [ ] Event history capture — persist full turn events with timestamps and token counts
+- [ ] Session replay — re-run a captured session for regression testing
+
+**Skills**
+
+- [ ] Skill registry compatibility — discover and invoke skills from a registry
+- [ ] Finetune on skills — export session history as structured training data

deepagents_serve-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+deepagents_serve/__init__.py,sha256=A3vL6So1kMaK8eEdge5-gm4bTrWHwGPP3Pk4rRm0Mvo,156
+deepagents_serve/app.py,sha256=fFYqbgTk4c8OH1XOX4WvVmizkYwUKaUmFvkoYd8oKOs,970
+deepagents_serve/events.py,sha256=olZlMvgnasEfCjNpTHm5TDBW7DF0_PSSFLxGabrybgw,1069
+deepagents_serve/normaliser.py,sha256=MYuDrqLXE58JKas9MflnV0ntfioJnS7ElsyHAAJp7K4,1824
+deepagents_serve/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deepagents_serve/adapter/__init__.py,sha256=Y5ZhfkOQ1ivKNrwA4y4Zm6QuxnB7ZepV5Ns_sMFvUJg,114
+deepagents_serve/adapter/vercel.py,sha256=zJzrStfqFhVJ3HN31gxYxmOXG5526TBXEd7bL0e01Hk,3558
+deepagents_serve/adapter/vercel_protocol.py,sha256=f9TnJbAJ64we0WuKR77aZoTggV2FnPJvw5iXqradkWU,4287
+deepagents_serve/route/__init__.py,sha256=T9nPIr6_9bL0b35SsxZR2UXqz2bSYiApxFmimcLAxwM,70
+deepagents_serve/route/health.py,sha256=LOulB2C9giIcpDJkfmq3ErbN848hb5XUj9PvLHKptUg,640
+deepagents_serve/route/vercel.py,sha256=DnqdTptUT3vHL2ZXYsxYJaXONHRyVJE7xj-58pKysOw,1424
+deepagents_serve-0.1.0.dist-info/METADATA,sha256=F0MQ69r8A9gCGxxMztRESZvbplnXOvtpx0OggdIFv6w,5622
+deepagents_serve-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deepagents_serve-0.1.0.dist-info/top_level.txt,sha256=BAx7uyQaeFCbDLF0dQWN49ml4NBHjaKv8L5Q6yL9FAs,17
+deepagents_serve-0.1.0.dist-info/RECORD,,

deepagents_serve-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepagents_serve-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepagents_serve