agobs 1.0__tar.gz

agobs-1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: agobs
+Version: 1.0
+Summary: AgentObserve: local-first diagnostics & observability for AI agents. Answers 'Why did my agent behave this way?' with one line and a single SQLite file.
+Author-email: Tharanika <sudhatharanika@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Tharanika-R-Git/AgentLens
+Keywords: agent,observability,tracing,diagnostics,llm,tools,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.23
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.1; extra == "langgraph"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2; extra == "autogen"
+Provides-Extra: pydanticai
+Requires-Dist: pydantic-ai>=0.0.1; extra == "pydanticai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.0.1; extra == "openai-agents"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=0.1; extra == "fastmcp"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1; extra == "all"
+Requires-Dist: langgraph>=0.1; extra == "all"
+Requires-Dist: llama-index-core>=0.10; extra == "all"
+Requires-Dist: crewai>=0.1; extra == "all"
+Requires-Dist: pyautogen>=0.2; extra == "all"
+Requires-Dist: mcp>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# AgentLens
+
+**Local-first diagnostics & observability for AI agents.** One line to integrate,
+a single SQLite file, a built-in dashboard. AgentLens answers the question other
+tools don't:
+
+> **Why did my agent behave this way?**
+
+Not a prompt tracker. Not a token dashboard. A diagnostics platform for *agent
+behavior* — tool usage, memory access, workflow paths, decisions, failures,
+retries, latency, and cost.
+
+```bash
+pip install pyagentlens               # core: store + dashboard + manual API + auto-patch
+pip install "pyagentlens[langchain]"  # framework adapters as extras (langgraph, crewai, …)
+pip install "pyagentlens[all]"        # every adapter
+```
+
+> Package name on PyPI is `pyagentlens`; the import name is `agentlens`.
+
+```python
+from agentlens import monitor
+monitor.start()          # auto-patches installed LLM SDKs — that's it
+```
+
+> **Full docs:** see [`Guide.md`](./Guide.md) — in-depth reference for humans *and* AI
+> coding agents (when-to-use-what tables, every API signature, per-framework
+> snippets, troubleshooting, and an agent cheat sheet).
+
+```bash
+agentlens ui             # dashboard at http://127.0.0.1:7180
+```
+
+No server to deploy. No cloud. No external services. Data lives in a hidden
+`./.agentlens/agentlens.db` (SQLite, WAL).
+
+---
+
+## Three ways to instrument (mix freely)
+
+### 1. Zero-config auto-patch
+`monitor.start()` detects and patches whatever is installed — **OpenAI,
+Anthropic, Google Gemini, Groq, LiteLLM** — so every LLM call becomes an `llm`
+span with tokens and cost, with no code changes.
+
+### 2. Manual (framework-agnostic, always available)
+```python
+import agentlens
+agentlens.init(project="research-bot")
+
+with agentlens.trace_session("chat"):
+    with agentlens.trace_agent("planner", role="lead"):
+        agentlens.log_decision(options=["search", "answer"], chosen="search", reason="needs fresh info")
+        agentlens.log_memory("read", "user_prefs", hit=True)
+        agentlens.log_tool("web_search", args={"q": "ai news"}, result=[...], retry_count=1)
+        agentlens.log_llm(model="gpt-4o", input_tokens=1200, output_tokens=400)
+```
+A tool/LLM logged with an `error=` (or a `trace_*` block that raises) is
+automatically recorded as a failure.
+
+### 3. Framework adapters
+| Framework | Import | Maturity |
+|---|---|---|
+| LangChain | `agentlens.adapters.langchain.AgentLensCallbackHandler` | full |
+| LangGraph | `agentlens.adapters.langgraph.AgentLensCallbackHandler` | full (LangChain callbacks) |
+| LlamaIndex | `agentlens.adapters.llamaindex.AgentLensLlamaHandler` | full |
+| CrewAI | `agentlens.adapters.crewai` (`step_callback`, `instrument_tools`) | best-effort |
+| AutoGen | `agentlens.adapters.autogen.instrument_agent` | best-effort |
+| PydanticAI | `agentlens.adapters.pydanticai.instrument_agent` | best-effort |
+| OpenAI Agents SDK | `agentlens.adapters.openai_agents.install` | best-effort |
+| Strands Agents | `agentlens.adapters.strands.callback_handler` | best-effort |
+| Anthropic Agent SDK | `agentlens.adapters.anthropic_agents.traced_async_tool` | tool-level |
+| MCP | `agentlens.adapters.mcp.instrument_server` / `traced_tool` | tool-level |
+| FastMCP | `agentlens.adapters.fastmcp.instrument_server` | tool-level |
+
+Plus a universal `agentlens.adapters.wrap_tool(fn)` / `@traced_tool()` that works
+with any framework or none.
+
+---
+
+## The dashboard
+
+- **Overview** — runs, success/failure rate, cost, p50/p95 latency.
+- **Runs → Run detail** — the **workflow execution graph** (span tree: session →
+  workflow → agent → tool/memory/llm/decision), click any node to inspect.
+- **Agent Explorer** — runs, failures, latency, and attributed cost per agent.
+- **Tool Explorer** — most used / slowest / most failed tools, retries.
+- **Memory Explorer** — reads/writes/updates/deletes and read hit-rate.
+- **Failure Explorer** — exceptions, messages, retries, jump to the failing run.
+- **Cost Explorer** — token usage, cost by day, by model, most expensive agents.
+
+---
+
+## Try it now (no keys needed)
+
+```bash
+pip install -e .
+python examples/demo_agent.py
+agentlens ui
+```
+
+## Design
+
+Local-first, zero-config, framework-agnostic, async-safe. Observability code
+never crashes your app (emit failures are swallowed). One `Span` model covers
+every event; kind-specific data lives in `attributes`. Cost is computed from an
+editable price book (`agentlens/server/pricing.py`).
+
+CLI: `agentlens ui [--port 7180] [--host] [--backend-store-uri PATH]`,
+`agentlens providers`, `agentlens version`. Override the port with
+`AGENTLENS_PORT`.
+
+**Single process** writes straight to local SQLite. For **multiple
+processes/workers** sharing one dashboard, run `agentlens ui` once and point each
+worker at it: `agentlens.init(project=..., tracking_uri="http://127.0.0.1:7180")`.
+
+See [`Guide.md`](./Guide.md) for the complete reference.

agobs-1.0/README.md

@@ -0,0 +1,117 @@
+# AgentLens
+
+**Local-first diagnostics & observability for AI agents.** One line to integrate,
+a single SQLite file, a built-in dashboard. AgentLens answers the question other
+tools don't:
+
+> **Why did my agent behave this way?**
+
+Not a prompt tracker. Not a token dashboard. A diagnostics platform for *agent
+behavior* — tool usage, memory access, workflow paths, decisions, failures,
+retries, latency, and cost.
+
+```bash
+pip install pyagentlens               # core: store + dashboard + manual API + auto-patch
+pip install "pyagentlens[langchain]"  # framework adapters as extras (langgraph, crewai, …)
+pip install "pyagentlens[all]"        # every adapter
+```
+
+> Package name on PyPI is `pyagentlens`; the import name is `agentlens`.
+
+```python
+from agentlens import monitor
+monitor.start()          # auto-patches installed LLM SDKs — that's it
+```
+
+> **Full docs:** see [`Guide.md`](./Guide.md) — in-depth reference for humans *and* AI
+> coding agents (when-to-use-what tables, every API signature, per-framework
+> snippets, troubleshooting, and an agent cheat sheet).
+
+```bash
+agentlens ui             # dashboard at http://127.0.0.1:7180
+```
+
+No server to deploy. No cloud. No external services. Data lives in a hidden
+`./.agentlens/agentlens.db` (SQLite, WAL).
+
+---
+
+## Three ways to instrument (mix freely)
+
+### 1. Zero-config auto-patch
+`monitor.start()` detects and patches whatever is installed — **OpenAI,
+Anthropic, Google Gemini, Groq, LiteLLM** — so every LLM call becomes an `llm`
+span with tokens and cost, with no code changes.
+
+### 2. Manual (framework-agnostic, always available)
+```python
+import agentlens
+agentlens.init(project="research-bot")
+
+with agentlens.trace_session("chat"):
+    with agentlens.trace_agent("planner", role="lead"):
+        agentlens.log_decision(options=["search", "answer"], chosen="search", reason="needs fresh info")
+        agentlens.log_memory("read", "user_prefs", hit=True)
+        agentlens.log_tool("web_search", args={"q": "ai news"}, result=[...], retry_count=1)
+        agentlens.log_llm(model="gpt-4o", input_tokens=1200, output_tokens=400)
+```
+A tool/LLM logged with an `error=` (or a `trace_*` block that raises) is
+automatically recorded as a failure.
+
+### 3. Framework adapters
+| Framework | Import | Maturity |
+|---|---|---|
+| LangChain | `agentlens.adapters.langchain.AgentLensCallbackHandler` | full |
+| LangGraph | `agentlens.adapters.langgraph.AgentLensCallbackHandler` | full (LangChain callbacks) |
+| LlamaIndex | `agentlens.adapters.llamaindex.AgentLensLlamaHandler` | full |
+| CrewAI | `agentlens.adapters.crewai` (`step_callback`, `instrument_tools`) | best-effort |
+| AutoGen | `agentlens.adapters.autogen.instrument_agent` | best-effort |
+| PydanticAI | `agentlens.adapters.pydanticai.instrument_agent` | best-effort |
+| OpenAI Agents SDK | `agentlens.adapters.openai_agents.install` | best-effort |
+| Strands Agents | `agentlens.adapters.strands.callback_handler` | best-effort |
+| Anthropic Agent SDK | `agentlens.adapters.anthropic_agents.traced_async_tool` | tool-level |
+| MCP | `agentlens.adapters.mcp.instrument_server` / `traced_tool` | tool-level |
+| FastMCP | `agentlens.adapters.fastmcp.instrument_server` | tool-level |
+
+Plus a universal `agentlens.adapters.wrap_tool(fn)` / `@traced_tool()` that works
+with any framework or none.
+
+---
+
+## The dashboard
+
+- **Overview** — runs, success/failure rate, cost, p50/p95 latency.
+- **Runs → Run detail** — the **workflow execution graph** (span tree: session →
+  workflow → agent → tool/memory/llm/decision), click any node to inspect.
+- **Agent Explorer** — runs, failures, latency, and attributed cost per agent.
+- **Tool Explorer** — most used / slowest / most failed tools, retries.
+- **Memory Explorer** — reads/writes/updates/deletes and read hit-rate.
+- **Failure Explorer** — exceptions, messages, retries, jump to the failing run.
+- **Cost Explorer** — token usage, cost by day, by model, most expensive agents.
+
+---
+
+## Try it now (no keys needed)
+
+```bash
+pip install -e .
+python examples/demo_agent.py
+agentlens ui
+```
+
+## Design
+
+Local-first, zero-config, framework-agnostic, async-safe. Observability code
+never crashes your app (emit failures are swallowed). One `Span` model covers
+every event; kind-specific data lives in `attributes`. Cost is computed from an
+editable price book (`agentlens/server/pricing.py`).
+
+CLI: `agentlens ui [--port 7180] [--host] [--backend-store-uri PATH]`,
+`agentlens providers`, `agentlens version`. Override the port with
+`AGENTLENS_PORT`.
+
+**Single process** writes straight to local SQLite. For **multiple
+processes/workers** sharing one dashboard, run `agentlens ui` once and point each
+worker at it: `agentlens.init(project=..., tracking_uri="http://127.0.0.1:7180")`.
+
+See [`Guide.md`](./Guide.md) for the complete reference.

agobs-1.0/agentlens/__init__.py

@@ -0,0 +1,48 @@
+"""AgentLens — local-first diagnostics & observability for AI agents.
+
+Answers one question: *"Why did my agent behave this way?"*
+
+Zero-config quickstart::
+
+    from agentlens import monitor
+    monitor.start()                      # auto-patches installed LLM SDKs
+    # ... run your agent ...
+
+Manual instrumentation (framework-agnostic)::
+
+    import agentlens
+    agentlens.init(project="research-bot")
+    with agentlens.trace_agent("planner"):
+        agentlens.log_tool("web_search", args={"q": "..."}, result=[...], retry_count=1)
+        agentlens.log_memory("read", "user_prefs", hit=True)
+        agentlens.log_llm(model="gpt-4o", input_tokens=1200, output_tokens=400)
+
+Then ``agentlens ui`` to explore the dashboard (default http://127.0.0.1:7180).
+"""
+from . import monitor
+from .client import flush, get_client, init
+from .events import Span, SpanKind
+from .tracing import (
+    current_session_id,
+    current_trace_id,
+    log_decision,
+    log_error,
+    log_llm,
+    log_memory,
+    log_retrieval,
+    log_tool,
+    trace,
+    trace_agent,
+    trace_session,
+    trace_workflow,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "init", "flush", "get_client", "monitor",
+    "trace", "trace_session", "trace_workflow", "trace_agent",
+    "current_trace_id", "current_session_id",
+    "log_llm", "log_tool", "log_memory", "log_decision", "log_retrieval", "log_error",
+    "Span", "SpanKind", "__version__",
+]

agobs-1.0/agentlens/_diag.py

@@ -0,0 +1,32 @@
+"""Diagnostics for the framework adapters and auto-patchers.
+
+Adapters hook into framework internals (callback signatures, method names) that
+move between versions. When they drift the failure is silent — a span just stops
+being captured. These helpers turn that silence into a visible
+``AgentLensWarning`` so version drift is noticed instead of producing empty
+dashboards.
+"""
+from __future__ import annotations
+
+import warnings
+from typing import Iterable
+
+
+class AgentLensWarning(UserWarning):
+    """Emitted when an adapter/patcher can't hook something it expected to."""
+
+
+def warn(message: str) -> None:
+    warnings.warn(f"[agentlens] {message}", AgentLensWarning, stacklevel=3)
+
+
+def require_methods(obj: object, methods: Iterable[str], what: str) -> None:
+    """Warn if ``obj`` is missing every one of ``methods`` (so the wrapper would
+    silently capture nothing). ``methods`` is treated as "at least one must
+    exist"."""
+    present = [m for m in methods if callable(getattr(obj, m, None))]
+    if not present:
+        warn(
+            f"{what}: {type(obj).__name__} has none of {list(methods)} — "
+            f"that will not be captured (framework version drift?)"
+        )

agobs-1.0/agentlens/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Framework adapters.
+
+Auto-patching (``monitor.start()``) covers the raw LLM SDKs. Agent frameworks
+expose their own callback/hook systems that carry far richer structure (agent
+boundaries, tool calls, decisions), so each framework gets a dedicated adapter
+here. Every adapter is import-time safe: importing this package never requires
+any framework to be installed.
+
+Common, framework-agnostic helpers live in ``common`` (``wrap_tool``,
+``traced_tool``) and work everywhere.
+"""
+from __future__ import annotations
+
+from .common import traced_tool, wrap_tool
+
+__all__ = ["traced_tool", "wrap_tool"]

agobs-1.0/agentlens/adapters/anthropic_agents.py

@@ -0,0 +1,52 @@
+"""Anthropic Agent SDK (``claude-agent-sdk``) adapter.
+
+The Claude Agent SDK runs tools you define and streams messages. The most
+reliable, version-stable instrumentation point is the tools themselves: wrap
+each tool callable so its invocation logs a tool span (args, result, errors).
+Raw Claude API calls the SDK makes are additionally captured by
+``monitor.start()`` auto-patching the underlying ``anthropic`` client.
+
+Example::
+
+    from agentlens.adapters.anthropic_agents import traced_tool
+
+    @traced_tool("get_weather")
+    async def get_weather(args): ...
+"""
+from __future__ import annotations
+
+import functools
+import time
+from typing import Any, Callable, Optional
+
+from .common import traced_tool, wrap_tool
+
+instrument_tool = wrap_tool
+
+
+def traced_async_tool(name: Optional[str] = None):
+    """Async variant of :func:`traced_tool` for ``async def`` tool handlers."""
+    def deco(fn: Callable) -> Callable:
+        tool_name = name or getattr(fn, "__name__", "tool")
+
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            from ..tracing import log_tool
+
+            t0 = time.time()
+            try:
+                result = await fn(*args, **kwargs)
+            except Exception as e:
+                log_tool(tool_name, args={"args": args, "kwargs": kwargs}, error=e,
+                         duration_ms=(time.time() - t0) * 1000.0)
+                raise
+            log_tool(tool_name, args={"args": args, "kwargs": kwargs}, result=result,
+                     duration_ms=(time.time() - t0) * 1000.0)
+            return result
+
+        return wrapper
+
+    return deco
+
+
+__all__ = ["traced_tool", "traced_async_tool", "wrap_tool", "instrument_tool"]

agobs-1.0/agentlens/adapters/autogen.py

@@ -0,0 +1,61 @@
+"""AutoGen (AG2 / pyautogen) adapter.
+
+AutoGen conversable agents support registered reply/hook functions. This adapter
+instruments an agent so each generated reply logs an agent span, and provides a
+tool wrapper for function-calling tools.
+
+Example::
+
+    from agentlens.adapters.autogen import instrument_agent
+    instrument_agent(assistant)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .. import client as _client
+from ..events import Span, SpanKind, jsonable
+from .common import wrap_tool
+
+instrument_tool = wrap_tool
+
+
+def instrument_agent(agent: Any) -> Any:
+    """Hook an AutoGen agent so its replies log agent spans. Uses
+    ``register_hook('process_message_before_send')`` when available, else wraps
+    ``generate_reply``."""
+    name = getattr(agent, "name", None) or type(agent).__name__
+
+    def _log(content: Any) -> None:
+        try:
+            ev = Span(project=_client.get_project(), kind=SpanKind.AGENT.value, name=name,
+                      attributes={"agent_name": name, "output": jsonable(content)})
+            _client.get_client().log_event(ev.finish().model_dump())
+        except Exception:
+            pass
+
+    if hasattr(agent, "register_hook"):
+        def hook(sender=None, message=None, recipient=None, silent=None, **kw):
+            _log(message)
+            return message
+        try:
+            agent.register_hook("process_message_before_send", hook)
+            return agent
+        except Exception:
+            pass
+
+    # fallback: wrap generate_reply
+    original = getattr(agent, "generate_reply", None)
+    if callable(original):
+        import functools
+
+        @functools.wraps(original)
+        def wrapper(*a, **k):
+            reply = original(*a, **k)
+            _log(reply)
+            return reply
+        try:
+            agent.generate_reply = wrapper
+        except Exception:
+            pass
+    return agent

agobs-1.0/agentlens/adapters/common.py

@@ -0,0 +1,46 @@
+"""Framework-agnostic instrumentation helpers.
+
+These work with any agent framework (or none): wrap a plain callable as a tool
+so each invocation logs a ``tool`` span — including its arguments, result,
+duration, and any exception (which automatically feeds the Failure Explorer).
+"""
+from __future__ import annotations
+
+import functools
+import time
+from typing import Any, Callable, Optional
+
+
+def wrap_tool(fn: Callable, name: Optional[str] = None) -> Callable:
+    """Return a wrapped callable that logs a ``tool`` span per call. Re-raises
+    the original exception after recording it, so behavior is unchanged."""
+    tool_name = name or getattr(fn, "__name__", None) or "tool"
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        from ..tracing import log_tool
+
+        t0 = time.time()
+        try:
+            result = fn(*args, **kwargs)
+        except Exception as e:
+            log_tool(tool_name, args={"args": args, "kwargs": kwargs}, error=e,
+                     duration_ms=(time.time() - t0) * 1000.0)
+            raise
+        log_tool(tool_name, args={"args": args, "kwargs": kwargs}, result=result,
+                 duration_ms=(time.time() - t0) * 1000.0)
+        return result
+
+    return wrapper
+
+
+def traced_tool(name: Optional[str] = None):
+    """Decorator form of :func:`wrap_tool`.
+
+        @traced_tool()
+        def web_search(q): ...
+    """
+    def deco(fn: Callable) -> Callable:
+        return wrap_tool(fn, name)
+
+    return deco

agobs-1.0/agentlens/adapters/crewai.py

@@ -0,0 +1,66 @@
+"""CrewAI adapter.
+
+CrewAI agents/crews accept ``step_callback`` and ``task_callback`` hooks, and
+their tools are plain callables. This adapter provides:
+
+  * ``step_callback`` / ``task_callback`` — pass to ``Agent(...)`` / ``Crew(...)``
+    to log agent-step and task spans,
+  * ``instrument_tools(tools)`` — wrap a list of tools so each invocation logs a
+    tool span (uses the framework-agnostic ``wrap_tool``).
+
+Example::
+
+    from agentlens.adapters.crewai import step_callback, instrument_tools
+    agent = Agent(..., tools=instrument_tools(tools), step_callback=step_callback)
+"""
+from __future__ import annotations
+
+from typing import Any, List
+
+from ..events import SpanKind, jsonable
+from ..tracing import _log
+from .common import wrap_tool
+
+
+def step_callback(step: Any) -> None:
+    """Log a CrewAI agent step as an agent span (best-effort field extraction).
+
+    Uses the contextvar-aware logger so the span nests under whatever trace is
+    active — wrap the crew kickoff in ``agentlens.trace_workflow(...)`` to keep a
+    crew's steps in one run instead of scattering them into top-level rows."""
+    try:
+        _log(SpanKind.AGENT.value, "crewai.step",
+             {"agent_name": getattr(step, "agent", None) and str(getattr(step, "agent")),
+              "output": jsonable(getattr(step, "output", None) or step)})
+    except Exception:
+        pass
+
+
+def task_callback(task_output: Any) -> None:
+    """Log a CrewAI task result as a workflow span (nested under the active trace)."""
+    try:
+        _log(SpanKind.WORKFLOW.value, "crewai.task",
+             {"output": jsonable(getattr(task_output, "raw", None) or task_output)})
+    except Exception:
+        pass
+
+
+def instrument_tools(tools: List[Any]) -> List[Any]:
+    """Wrap each tool's underlying callable so calls log tool spans. Works for
+    CrewAI ``BaseTool`` instances (wraps ``_run``/``run``) and plain functions."""
+    out = []
+    for t in tools or []:
+        for attr in ("_run", "run", "func"):
+            fn = getattr(t, attr, None)
+            if callable(fn):
+                name = getattr(t, "name", None) or getattr(fn, "__name__", "tool")
+                try:
+                    setattr(t, attr, wrap_tool(fn, name))
+                except Exception:
+                    pass
+                break
+        else:
+            if callable(t):
+                t = wrap_tool(t)
+        out.append(t)
+    return out

agobs-1.0/agentlens/adapters/fastmcp.py

@@ -0,0 +1,56 @@
+"""FastMCP adapter.
+
+FastMCP keeps registered tools in a tool manager; this adapter wraps each tool's
+underlying function so calls log tool spans. Call ``instrument_server(mcp)``
+after your tools are registered.
+
+Example::
+
+    from fastmcp import FastMCP
+    from agentlens.adapters.fastmcp import instrument_server
+
+    mcp = FastMCP("demo")
+
+    @mcp.tool()
+    def add(a: int, b: int) -> int: return a + b
+
+    instrument_server(mcp)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .anthropic_agents import traced_async_tool
+from .common import traced_tool, wrap_tool
+
+instrument_tool = wrap_tool
+
+
+def instrument_server(mcp: Any) -> Any:
+    """Wrap each registered FastMCP tool's function with a tool-span logger."""
+    manager = getattr(mcp, "_tool_manager", None) or getattr(mcp, "tool_manager", None)
+    tools = None
+    if manager is not None:
+        tools = getattr(manager, "_tools", None) or getattr(manager, "tools", None)
+    tools = tools if tools is not None else getattr(mcp, "_tools", None)
+
+    items = []
+    if isinstance(tools, dict):
+        items = list(tools.items())
+    elif isinstance(tools, (list, tuple)):
+        items = [(getattr(t, "name", i), t) for i, t in enumerate(tools)]
+
+    for key, tool in items:
+        for attr in ("fn", "func", "handler", "callback"):
+            fn = getattr(tool, attr, None)
+            if callable(fn) and not getattr(fn, "__agentlens_patched__", False):
+                name = getattr(tool, "name", None) or str(key)
+                try:
+                    setattr(tool, attr, wrap_tool(fn, name))
+                except Exception:
+                    pass
+                break
+    return mcp
+
+
+__all__ = ["traced_tool", "traced_async_tool", "wrap_tool", "instrument_tool", "instrument_server"]