Metadata-Version: 2.4
Name: ylg-open-trace-agent-sdk
Version: 0.1.0
Summary: OpenTelemetry-based trace SDK for Dockerized Python Agents.
Author: wangxiao
Keywords: agent,opentelemetry,sdk,trace,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api<2.0.0,>=1.28.0
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.28.0
Description-Content-Type: text/markdown

# 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`。

## 安装

```bash
uv add ylg-open-trace-agent-sdk
```

## 最小用法

```python
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，可以复用它：

```python
trace = TraceClient.from_env(use_global_provider=True)
```

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

## 环境变量

```text
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
```

## 测试

普通单测：

```bash
uv run pytest
```

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

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