Metadata-Version: 2.4
Name: agentbase-agentops-langchain
Version: 0.1.0
Summary: Automatic LangChain Agent observability for AgentBase AgentOps
Author: AgentBase Team
License-Expression: Apache-2.0
Keywords: agentops,appbase,langchain,observability,opentelemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain<2.0,>=1.0
Requires-Dist: opentelemetry-api<2.0,>=1.28
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.28
Requires-Dist: opentelemetry-sdk<2.0,>=1.28
Requires-Dist: packaging>=23
Provides-Extra: examples
Requires-Dist: langchain-openai<2.0,>=1.0; extra == "examples"
Provides-Extra: nemo
Requires-Dist: langchain-openai<2.0,>=1.0; extra == "nemo"
Requires-Dist: nemo-relay[langchain]<0.9,>=0.8.1; extra == "nemo"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Dynamic: license-file

# AgentBase AgentOps LangChain

`agentbase-agentops-langchain` 为用户现有的 LangChain Agent 增加 AppBase AgentOps
可观测能力。挂载一次 `AgentOpsMiddleware` 后，SDK 自动采集 Agent、Chain、LLM、Tool
和 Retriever 生命周期，并通过 OTLP/HTTP 发送到 AppBase AgentOps。

SDK 不创建或替换模型，不代理模型请求，也不改变应用现有的模型 Provider、模型凭据、
Prompt、Tool 或业务逻辑。

## 安装

```bash
python -m pip install agentbase-agentops-langchain
```

## 配置

```bash
export AGENTBASE_AGENTOPS_ENDPOINT="https://<appbase-host>"
export AGENTBASE_PROJECT_ID="<project-id>"
export AGENTBASE_API_KEY="<project-api-key>"
```

Project API Key 至少需要 `observability.ingest.write` 权限。SDK 会自动将 AppBase host 或
`/v1` base URL 补齐为完整 OTLP Trace endpoint。

## 接入现有 Agent

```python
from agentbase_agentops_langchain import AgentOpsMiddleware
from langchain.agents import create_agent


agentops = AgentOpsMiddleware()

agent = create_agent(
    model=model,
    tools=tools,
    middleware=[agentops],
)

result = agent.invoke(
    inputs,
    config={
        "metadata": {
            "session_id": conversation_id,
            "user_id": authenticated_user_id,
        },
        "tags": [environment, agent_name, agent_version],
    },
)
```

如果应用已经配置其他 LangChain middleware，请将 `AgentOpsMiddleware` 追加到原列表，
不要覆盖现有 middleware。后续 `invoke`、`ainvoke`、`stream`、`astream`、`batch`
和 `abatch` 调用不需要手工传入 AgentOps callback。

## 短生命周期进程

CLI、Job 和测试脚本应在退出前主动 flush：

```python
agentops.flush(timeout_millis=10_000)
```

`flush()` 表示同步尝试导出本地队列，不代表 AppBase 服务端已经完成持久化。需要确认接入
成功时，应通过 Console 或 Trace API 等待完整的 Agent、Generation 和 Tool 观测树。

## 内容采集

默认 `AGENTBASE_AGENTOPS_CAPTURE_CONTENT=false`，不会上传 Prompt、Response、Tool 参数
或 Retriever 文档正文。只有显式开启后才采集正文：

```bash
export AGENTBASE_AGENTOPS_CAPTURE_CONTENT=true
```

生产环境开启前应确认内容符合数据安全和脱敏要求。

## NeMo Relay

已经使用 NVIDIA NeMo Relay 的应用不应再挂载 `AgentOpsMiddleware`。保留
`NemoRelayMiddleware`、`NemoRelayCallbackHandler` 和 Relay scope，将 Relay 的
OTLP/HTTP Trace endpoint 与鉴权 header 指向 AppBase AgentOps。

Session/User 关联需要同时满足：

- `plugins.toml` 配置 `promote_metadata_prefixes = ["langfuse."]`；
- Relay scope metadata 传入 `langfuse.session.id` 和 `langfuse.user.id`。

本页提供可直接完成安装和接入的最小配置。完整的配置、验证、隐私边界和排障说明，
请以 AppBase 官方客户文档为准。

## 兼容范围

- Python `>=3.10`
- LangChain `>=1.0,<2.0`
- OTLP/HTTP Trace

当前不提供 OTLP/gRPC、Metrics 或 OpenTelemetry Logs 接入。
