Metadata-Version: 2.5
Name: metano-agent-sdk
Version: 0.7.1
Summary: Instrument your own AI agents (LangChain, CrewAI, OpenAI Agents SDK, or plain Python) for Metano: session telemetry and runtime guardrails.
Project-URL: Homepage, https://metano.ai
Author: Metano AI
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,crewai,guardrails,langchain,llm,mcp,observability,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: a2a
Requires-Dist: a2a-sdk[http-server]<2,>=1.1.2; extra == 'a2a'
Provides-Extra: crewai
Requires-Dist: crewai<2,>=1.14; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: a2a-sdk[http-server]<2,>=1.1.2; extra == 'dev'
Requires-Dist: langchain-core>=0.3; extra == 'dev'
Requires-Dist: langchain>=1.0; extra == 'dev'
Requires-Dist: mypy==1.13.0; extra == 'dev'
Requires-Dist: pytest==8.3.4; extra == 'dev'
Requires-Dist: ruff==0.8.4; extra == 'dev'
Requires-Dist: wrapt>=1.16; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: langchain-agents
Requires-Dist: langchain>=1.0; extra == 'langchain-agents'
Provides-Extra: mcp
Requires-Dist: wrapt>=1.16; extra == 'mcp'
Provides-Extra: openai-agents
Requires-Dist: openai-agents<1,>=0.2; extra == 'openai-agents'
Description-Content-Type: text/markdown

# metano-agent-sdk

Instrument a Python AI agent for [Metano](https://metano.ai). The SDK reports
session traces, model calls, tool calls and your MCP server inventory, and it
enforces guardrail policy at runtime.

It works with LangChain, CrewAI and the OpenAI Agents SDK through adapters
that instrument automatically, and with any other framework, or none at all,
through the core API.

- **Python ≥ 3.10**. The core has **no dependencies**; framework adapters are
  optional extras.
- **Apache-2.0**
- Telemetry is **fail-open**: the SDK never raises into, blocks, or delays your
  agent. If Metano is unreachable, events are dropped and your agent keeps
  running.
- Prompt, response, and tool bodies are **not** sent in full by default. You get
  a short excerpt plus a hash. Opt in with `capture_content=True`.

## Install

```sh
pip install metano-agent-sdk
```

Add the extra for your framework:

| Extra | Installs | For |
| --- | --- | --- |
| `langchain` | `langchain-core` | recording LangChain and LangGraph runs |
| `langchain-agents` | `langchain` 1.x | the guardrail middleware for `create_agent` |
| `crewai` | `crewai` 1.x | recording and guarding CrewAI crews and flows |
| `openai-agents` | `openai-agents` | recording and guarding the OpenAI Agents SDK |
| `a2a` | `a2a-sdk` | carrying session context across agent-to-agent calls |
| `mcp` | `wrapt` | recording calls made with the official `mcp` client |

```sh
pip install 'metano-agent-sdk[langchain]'
```

## Configure

Create an API key on the **API Keys** page of the Metano portal (requires the
Admin role), then set it in your agent's environment:

```sh
export METANO_API_KEY=mo_...
```

That is all a production agent needs. The key names the deployment that issued
it, so the SDK works out where to send telemetry on its own.

## Quick start

```python
import metano_agent_sdk as metano

metano.init(agent_name="refund-bot")  # API key from $METANO_API_KEY

with metano.session() as s:
    s.prompt("How many refunds are pending?")

    with s.llm_call(model="claude-sonnet-5", provider="anthropic") as call:
        answer = my_llm(...)                         # your real LLM client
        call.usage(tokens_in=18, tokens_out=120)     # feeds cost and token rollups

    with s.tool_call("warehouse.query", kind="mcp", server="warehouse",
                     tool_input={"sql": "select ..."}) as tool:
        tool.output(my_query(...))                   # your real tool call

metano.shutdown()  # flush buffered telemetry before a short-lived process exits
```

The agent then appears under **AI Agents** in the portal, marked as an SDK
agent, with each session on its timeline.

### Always call `shutdown()`

Telemetry is batched and sent from a background thread so it never slows your
agent down. A short-lived process that exits without `metano.shutdown()` (or
`await metano.ashutdown()`) can lose the events still in its buffer.

## Frameworks

Pass your framework to `init()` and run your agent unchanged:

```python
metano.init(agent_name="research-bot", framework="langchain")
agent.invoke(inputs)            # recorded automatically
```

```python
metano.init(agent_name="research-bot", framework="crewai")
crew.kickoff(inputs={...})      # recorded and guarded automatically
```

```python
metano.init(agent_name="research-bot", framework="openai-agents")
agent = Agent(...)              # construct agents AFTER init()
await Runner.run(agent, "...")
```

For enforcement in a LangChain `create_agent` agent, add the middleware
(`langchain-agents` extra):

```python
from langchain.agents import create_agent
from metano_agent_sdk.langchain_middleware import MetanoGuardrailMiddleware

agent = create_agent(model=..., tools=[...], middleware=[MetanoGuardrailMiddleware()])
```

To record tool calls made through the official `mcp` client (`mcp` extra):

```python
from metano_agent_sdk.mcp import enable_mcp_capture

enable_mcp_capture()
```

## Environment variables

| Variable | Purpose |
| --- | --- |
| `METANO_API_KEY` | Your Metano API key. Required. |
| `METANO_INGEST_URL` | Override where telemetry is sent. |
| `METANO_GATEWAY_URL` | Override the LLM gateway address. |
| `METANO_MCP_GATEWAY_URL` | Override the MCP gateway address. |

Each override is optional; an explicit argument to `init()` wins over the
environment.

## Documentation

Full setup guides for each framework, guardrails and the LLM and MCP gateways
are in the Metano documentation, linked from the portal's **API Keys** page.

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
