agentkit-sdk-python 0.7.2__py3-none-any.whl → 0.7.4__py3-none-any.whl

agentkit/frameworks/langgraph.py

@@ -0,0 +1,349 @@
+"""LangGraph adapter for AgentKit apps."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+import inspect
+import json
+from typing import Any
+
+try:
+    from langchain_core.messages import HumanMessage
+except ImportError as exc:  # pragma: no cover - depends on optional packages.
+    raise ImportError(
+        "LangGraph bridge requires langgraph/langchain-core. "
+        "Install langgraph or use the requirements generated by agentkit migrate."
+    ) from exc
+
+from google.adk.agents.base_agent import BaseAgent
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.events import Event, EventActions
+from google.genai import types
+from pydantic import PrivateAttr
+
+try:
+    from langgraph.types import Command
+except ImportError:  # pragma: no cover - older optional langgraph versions.
+    Command = None  # type: ignore[assignment]
+
+from agentkit.frameworks._common import (
+    UnsupportedFrameworkAgentError,
+    adk_event,
+    chunk_delta,
+    chunk_to_text,
+    user_text,
+)
+
+
+LANGGRAPH_PENDING_INTERRUPT_STATE_KEY = "agentkit:langgraph:pending_interrupt"
+
+
+def _method_kwargs(method: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    try:
+        signature = inspect.signature(method)
+    except (TypeError, ValueError):
+        return kwargs
+
+    parameters = signature.parameters
+    accepts_kwargs = any(param.kind == inspect.Parameter.VAR_KEYWORD for param in parameters.values())
+    return {key: value for key, value in kwargs.items() if accepts_kwargs or key in parameters}
+
+
+def _jsonable(value: Any) -> Any:
+    try:
+        json.dumps(value, ensure_ascii=False)
+        return value
+    except Exception:
+        return str(value)
+
+
+def _interrupt_payload(data: Any) -> Any | None:
+    if not isinstance(data, dict) or "__interrupt__" not in data:
+        return None
+    interrupts = data.get("__interrupt__")
+    if not isinstance(interrupts, (list, tuple)) or not interrupts:
+        return interrupts
+    values: list[dict[str, Any]] = []
+    for interrupt in interrupts:
+        values.append(
+            {
+                "id": getattr(interrupt, "id", None),
+                "value": _jsonable(getattr(interrupt, "value", interrupt)),
+            }
+        )
+    return values
+
+
+def _resume_value(text_input: str) -> Any:
+    stripped = text_input.strip()
+    if stripped.startswith(("{", "[")):
+        try:
+            return json.loads(stripped)
+        except json.JSONDecodeError:
+            return text_input
+    return text_input
+
+
+class LangGraphAgentkitBridge(BaseAgent):
+    """Adapt a compiled LangGraph graph to AgentKit's ADK runtime boundary."""
+
+    _graph: Any = PrivateAttr()
+    _input_key: str | None = PrivateAttr(default=None)
+
+    def __init__(
+        self,
+        graph: Any,
+        *,
+        name: str = "langgraph_agent",
+        description: str = "LangGraph agent adapted for AgentKit runtime",
+        input_key: str | None = None,
+    ) -> None:
+        super().__init__(name=name, description=description)
+        self._graph = graph
+        self._input_key = input_key
+
+    def _input_payload(self, text_input: str) -> dict[str, Any]:
+        if self._input_key:
+            return {self._input_key: text_input}
+        return {"messages": [HumanMessage(content=text_input)]}
+
+    def _graph_config(self, ctx: InvocationContext) -> dict[str, Any] | None:
+        session = getattr(ctx, "session", None)
+        session_id = getattr(session, "id", None)
+        if not session_id:
+            return None
+        return {"configurable": {"thread_id": session_id}}
+
+    def _pending_interrupt(self, ctx: InvocationContext) -> Any | None:
+        session = getattr(ctx, "session", None)
+        state = getattr(session, "state", None)
+        if not isinstance(state, dict):
+            return None
+        pending = state.get(LANGGRAPH_PENDING_INTERRUPT_STATE_KEY)
+        if not pending:
+            return None
+        if isinstance(pending, dict) and pending.get("agent") not in {None, self.name}:
+            return None
+        return pending
+
+    def _run_payload(self, ctx: InvocationContext) -> Any:
+        text_input = user_text(ctx)
+        if self._pending_interrupt(ctx) is None:
+            return self._input_payload(text_input)
+        if Command is None:
+            raise UnsupportedFrameworkAgentError(
+                "LangGraph HITL resume requires langgraph.types.Command. "
+                "Upgrade langgraph or start a new AgentKit session."
+            )
+        return Command(resume=_resume_value(text_input))
+
+    def _interrupt_state_delta(self, ctx: InvocationContext, config: dict[str, Any] | None, interrupt: Any) -> dict[str, Any]:
+        session = getattr(ctx, "session", None)
+        session_id = getattr(session, "id", None)
+        if not session_id:
+            return {}
+        return {
+            LANGGRAPH_PENDING_INTERRUPT_STATE_KEY: {
+                "agent": self.name,
+                "thread_id": config.get("configurable", {}).get("thread_id") if config else session_id,
+                "interrupts": interrupt,
+            }
+        }
+
+    def _final_event(self, ctx: InvocationContext, text: str, *, clear_pending_interrupt: bool) -> Event:
+        event_kwargs: dict[str, Any] = {}
+        if clear_pending_interrupt:
+            event_kwargs["actions"] = EventActions(state_delta={LANGGRAPH_PENDING_INTERRUPT_STATE_KEY: None})
+        return Event(
+            invocation_id=ctx.invocation_id,
+            author=self.name,
+            branch=ctx.branch,
+            partial=False,
+            content=types.Content(role="model", parts=[types.Part(text=text)]),
+            **event_kwargs,
+        )
+
+    def _clear_pending_interrupt_event(self, ctx: InvocationContext) -> Event:
+        return Event(
+            invocation_id=ctx.invocation_id,
+            author=self.name,
+            branch=ctx.branch,
+            actions=EventActions(state_delta={LANGGRAPH_PENDING_INTERRUPT_STATE_KEY: None}),
+        )
+
+    async def _call_once(self, payload: Any, config: dict[str, Any] | None) -> Any:
+        ainvoke = getattr(self._graph, "ainvoke", None)
+        if callable(ainvoke):
+            return await ainvoke(payload, **_method_kwargs(ainvoke, {"config": config}))
+
+        invoke = getattr(self._graph, "invoke", None)
+        if callable(invoke):
+            return invoke(payload, **_method_kwargs(invoke, {"config": config}))
+
+        raise UnsupportedFrameworkAgentError(
+            "LangGraph entry must be a compiled graph-like object exposing "
+            "astream, stream, ainvoke, or invoke."
+        )
+
+    def _sync_stream(self, payload: Any, config: dict[str, Any] | None):
+        stream_fn = getattr(self._graph, "stream", None)
+        if not callable(stream_fn):
+            return None
+        try:
+            return stream_fn(
+                payload,
+                **_method_kwargs(
+                    stream_fn,
+                    {
+                        "config": config,
+                        "stream_mode": ["messages", "updates"],
+                        "version": "v2",
+                    },
+                ),
+            )
+        except TypeError:
+            try:
+                return stream_fn(
+                    payload,
+                    **_method_kwargs(
+                        stream_fn,
+                        {
+                            "config": config,
+                            "stream_mode": ["messages", "updates"],
+                        },
+                    ),
+                )
+            except TypeError:
+                return stream_fn(payload, **_method_kwargs(stream_fn, {"config": config}))
+
+    async def _stream_graph(self, payload: Any, config: dict[str, Any] | None, *, prefer_sync: bool = False):
+        if prefer_sync:
+            stream = self._sync_stream(payload, config)
+            if stream is not None:
+                for item in stream:
+                    yield item
+                return
+
+        astream = getattr(self._graph, "astream", None)
+        if callable(astream):
+            try:
+                stream = astream(
+                    payload,
+                    **_method_kwargs(
+                        astream,
+                        {
+                            "config": config,
+                            "stream_mode": ["messages", "updates"],
+                            "version": "v2",
+                        },
+                    ),
+                )
+            except TypeError:
+                try:
+                    stream = astream(
+                        payload,
+                        **_method_kwargs(
+                            astream,
+                            {
+                                "config": config,
+                                "stream_mode": ["messages", "updates"],
+                            },
+                        ),
+                    )
+                except TypeError:
+                    stream = astream(payload, **_method_kwargs(astream, {"config": config}))
+            async for item in stream:
+                yield item
+            return
+
+        stream = self._sync_stream(payload, config)
+        if stream is not None:
+            for item in stream:
+                yield item
+
+    async def _run_async_impl(
+        self,
+        ctx: InvocationContext,
+    ) -> AsyncGenerator[Event, None]:
+        config = self._graph_config(ctx)
+        resume_pending = self._pending_interrupt(ctx) is not None
+        payload = self._run_payload(ctx)
+        accumulated_text = ""
+        has_output = False
+        last_update: Any = None
+        pending_update_text = ""
+        saw_messages = False
+        streamed = False
+
+        async for item in self._stream_graph(payload, config, prefer_sync=resume_pending):
+            streamed = True
+            mode = ""
+            data = item
+            if isinstance(item, tuple) and len(item) == 2 and isinstance(item[0], str):
+                mode, data = item
+            elif isinstance(item, dict) and isinstance(item.get("type"), str):
+                mode = item["type"]
+                data = item.get("data")
+
+            if mode == "messages":
+                message = data[0] if isinstance(data, tuple) and data else data
+                text = chunk_to_text(message)
+                if not text:
+                    continue
+                delta = chunk_delta(accumulated_text, text)
+                if not delta:
+                    continue
+                saw_messages = True
+                accumulated_text += delta
+                has_output = True
+                yield adk_event(ctx, self.name, delta, partial=True)
+                continue
+
+            if mode == "updates":
+                interrupt = _interrupt_payload(data)
+                if interrupt is not None:
+                    state_delta = self._interrupt_state_delta(ctx, config, interrupt)
+                    event_kwargs: dict[str, Any] = {}
+                    if state_delta:
+                        event_kwargs["actions"] = EventActions(state_delta=state_delta)
+                    yield Event(
+                        invocation_id=ctx.invocation_id,
+                        author=self.name,
+                        branch=ctx.branch,
+                        interrupted=True,
+                        error_code="LANGGRAPH_INTERRUPT",
+                        error_message="LangGraph execution interrupted and requires resume input.",
+                        custom_metadata={"langgraph_interrupt": interrupt},
+                        **event_kwargs,
+                    )
+                    return
+                last_update = data
+                if saw_messages:
+                    continue
+                text = chunk_to_text(data)
+                if text:
+                    pending_update_text = text
+                continue
+
+            text = chunk_to_text(data)
+            if text:
+                delta = chunk_delta(accumulated_text, text)
+                if delta:
+                    accumulated_text += delta
+                    has_output = True
+                    yield adk_event(ctx, self.name, delta, partial=True)
+
+        if streamed:
+            if saw_messages or has_output:
+                final_text = accumulated_text
+            else:
+                final_text = pending_update_text or chunk_to_text(last_update)
+                if final_text:
+                    yield adk_event(ctx, self.name, final_text, partial=True)
+        else:
+            final_text = chunk_to_text(await self._call_once(payload, config))
+
+        if final_text:
+            yield self._final_event(ctx, final_text, clear_pending_interrupt=resume_pending)
+        elif resume_pending:
+            yield self._clear_pending_interrupt_event(ctx)

agentkit/frameworks/serving/__init__.py

@@ -0,0 +1,6 @@
+"""Serving compatibility helpers for migrated framework agents."""
+
+from agentkit.frameworks.serving.fastapi_mount import mount_legacy_fastapi_app
+from agentkit.frameworks.serving.langserve import attach_langserve_compat_routes
+
+__all__ = ["attach_langserve_compat_routes", "mount_legacy_fastapi_app"]

agentkit/frameworks/serving/fastapi_mount.py

@@ -0,0 +1,65 @@
+"""Helpers for mounting an existing FastAPI app beside AgentKit routes."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_prefix(prefix: str) -> str:
+    if not prefix:
+        raise ValueError("legacy FastAPI mount prefix must not be empty.")
+    if not prefix.startswith("/"):
+        raise ValueError("legacy FastAPI mount prefix must start with '/'.")
+    if prefix != "/" and prefix.endswith("/"):
+        return prefix.rstrip("/")
+    return prefix
+
+
+def mount_legacy_fastapi_app(
+    app: FastAPI,
+    legacy_app: Any,
+    *,
+    prefix: str = "/legacy",
+    allow_root: bool = False,
+) -> None:
+    """Mount a user-owned FastAPI app without rewriting its routes."""
+
+    normalized_prefix = _normalize_prefix(prefix)
+    if normalized_prefix == "/" and not allow_root:
+        raise ValueError(
+            "mounting a legacy FastAPI app at '/' can shadow AgentKit routes; "
+            "pass allow_root=True only when you intentionally want that behavior."
+        )
+    if not isinstance(legacy_app, FastAPI):
+        raise TypeError("legacy_app must be a fastapi.FastAPI instance.")
+
+    logger.info("Mounting legacy FastAPI app at %s", normalized_prefix)
+    app.mount(normalized_prefix, legacy_app)
+    _promote_mount(app, normalized_prefix)
+
+
+def _promote_mount(app: FastAPI, path: str) -> None:
+    routes = app.router.routes
+    route_index = next(
+        (
+            index
+            for index, route in enumerate(routes)
+            if getattr(route, "path", None) == ("" if path == "/" else path)
+        ),
+        None,
+    )
+    if route_index is None:
+        return
+
+    route = routes.pop(route_index)
+    insert_at = len(routes)
+    for index, existing in enumerate(routes):
+        if getattr(existing, "path", None) in {"", "/"}:
+            insert_at = index
+            break
+    routes.insert(insert_at, route)