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 或业务逻辑。

安装

python -m pip install agentbase-agentops-langchain

配置

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

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：

agentops.flush(timeout_millis=10_000)

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

内容采集

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

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 接入。