ylg-open-trace-agent-sdk 0.1.0

OpenTelemetry-based trace SDK for Dockerized Python Agents.

YLG Open Trace Agent SDK

YLG Open Trace Agent SDK 是面向独立 Docker Python Agent 的运行链路 SDK。

SDK 以 OpenTelemetry 为 tracing 底座，对外提供 Agent 业务语义 API，并把 span/event 映射到 Agent 平台的 /api/v2/traces/ingest。

安装

uv add ylg-open-trace-agent-sdk

最小用法

from ylg_open_trace_agent_sdk import TraceClient, TraceContext

trace = TraceClient.from_env()

context = TraceContext(
    trace_id="trace-001",
    request_id="request-001",
    run_id="run-001",
    agent_id="road_advice_agent",
    agent_version="v1",
    tenant_id="tenant-a",
    product_id="road-decision",
    scene_code="maintenance-advice",
)

with trace.agent_run(context, name="road_advice_agent"):
    with trace.tool("condition_api", input={"section_id": "G42-K121"}, attributes={"tool_type": "datastore"}) as span:
        result = {"row_count": 3}
        span.set_output(result)
    with trace.llm(
        "final_answer",
        attributes={"provider_name": "openai", "request_model": "gpt-5.2"},
    ) as span:
        span.set_token_usage(input_tokens=120, output_tokens=48)
        span.set_output({"answer": "ok"})

trace.flush(timeout_ms=300)

与 OpenTelemetry 的关系

SDK 不重复实现 tracing runtime。span 生命周期、父子关系、async context 传播由 OpenTelemetry 负责；SDK 只增加两层能力：

• 写入 Agent 平台需要的 agent.* 业务字段，用于 run_id、tenant_id、scene_code 等平台维度落表。
• 对 Tool、RAG、LLM、workflow 写入 OpenTelemetry GenAI semantic convention 的 gen_ai.* attributes，并转换为平台 /api/v2/traces/ingest payload。

如果 Agno 或其他框架已经初始化了全局 OpenTelemetry provider，可以复用它：

trace = TraceClient.from_env(use_global_provider=True)

这样 SDK 的 PlatformTraceProcessor 会挂到已有 OTel pipeline 上，减少重复 instrumentation。

环境变量

OPEN_TRACE_AGENT_ENDPOINT=http://127.0.0.1:8000/api/v2/traces/ingest
OPEN_TRACE_AGENT_SERVICE_NAME=road_advice_agent
OPEN_TRACE_AGENT_FLUSH_INTERVAL_MS=1000
OPEN_TRACE_AGENT_MAX_QUEUE_SIZE=1000

测试

普通单测：

uv run pytest

真实平台 smoke 需要先启动 Agent 平台 API，并让它连接 PostgreSQL 测试库：

OPEN_TRACE_AGENT_LIVE_BASE_URL=http://127.0.0.1:8000/api/v2 uv run pytest tests/test_live_platform_smoke.py -q