> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体追踪 SDK

> 安装、配置 JavaScript 或 Python SDK，并为仪表盘和智能体追踪组织追踪。

在 **Business 个人菜单 → 开发者**创建**智能体追踪 API 密钥**，然后在应用中选择**连接 SDK**。智能体追踪密钥与 Merchant API 密钥、智能体钱包密钥相互独立。

## 安装与初始化

<Tabs>
  <Tab title="JavaScript">
    ```bash theme={null}
    npm install @anyway-sh/node-server-sdk
    export ANYWAY_API_KEY="<Agent Traces API key>"
    ```

    ```typescript theme={null}
    import { initialize } from "@anyway-sh/node-server-sdk";

    initialize({
      appName: "support-app",
      apiKey: process.env.ANYWAY_API_KEY,
      baseUrl: "https://collector.anyway.sh",
    });
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install anyway-sdk
    export ANYWAY_API_KEY="<Agent Traces API key>"
    ```

    ```python theme={null}
    import os
    from anyway.sdk import Traceloop

    Traceloop.init(
        app_name="support-app",
        api_key=os.environ["ANYWAY_API_KEY"],
        api_endpoint="https://collector.anyway.sh",
    )
    ```
  </Tab>
</Tabs>

HTTPS 收集器使用 OTLP/HTTP。Python SDK 会把不带 `http://` 或 `https://` 的自定义地址视为 gRPC。

## 环境配置

| 变量                        | 含义                                      |
| ------------------------- | --------------------------------------- |
| `ANYWAY_API_KEY`          | 智能体追踪 API 密钥                            |
| `ANYWAY_BASE_URL`         | 收集器地址；默认为 `https://collector.anyway.sh` |
| `ANYWAY_HEADERS`          | 使用自定义鉴权时的可选导出器请求头                       |
| `ANYWAY_TRACE_CONTENT`    | 控制 JavaScript 的提示词和补全内容捕获               |
| `TRACELOOP_TRACE_CONTENT` | 控制 Python 的提示词和补全内容捕获                   |

请优先使用 `apiKey` / `api_key`，不要自行构造 `Authorization` 请求头。确需自定义请求头时，按 `Authorization: Bearer <key>` 发送收集器密钥。

## JavaScript 追踪

使用函数包装器建立明确的追踪层级：

```typescript theme={null}
import {
  withWorkflow,
  withAgent,
  withTask,
  withTool,
} from "@anyway-sh/node-server-sdk";

await withWorkflow(
  {
    name: "support-reply",
    associationProperties: {
      userId: "usr_opaque",
      sessionId: "session_opaque",
    },
  },
  async () =>
    withAgent({ name: "support-agent" }, async () =>
      withTask({ name: "draft" }, async () =>
        withTool({ name: "knowledge-search" }, async () => {
          // 在这里调用工具。
        }),
      ),
    ),
);
```

也支持 TypeScript 类装饰器：

```typescript theme={null}
import { workflow, task } from "@anyway-sh/node-server-sdk";

class SupportFlow {
  @workflow({ name: "reply" })
  async reply() {
    return this.draft();
  }

  @task({ name: "draft" })
  async draft() {
    return "response";
  }
}
```

### ESM 与 Next.js

基于 `require` 的自动插桩无法观察普通 ESM `import`。请显式传入已导入的服务商模块：

```typescript theme={null}
import { initialize } from "@anyway-sh/node-server-sdk";
import OpenAI from "openai";

initialize({
  appName: "next-app",
  apiKey: process.env.ANYWAY_API_KEY,
  instrumentModules: { openAI: OpenAI },
});
```

`instrumentModules` 支持当前 SDK 暴露的服务商，包括 OpenAI、Anthropic、Cohere、Bedrock、Google Vertex AI、Pinecone、Together、LangChain、LlamaIndex、ChromaDB、Qdrant 和 MCP。

## Python 追踪

装饰器同时支持同步和异步函数：

```python theme={null}
from anyway.sdk.decorators import workflow, task

@workflow(name="support_reply")
async def reply():
    return await draft()

@task(name="draft")
async def draft():
    # 在这里调用模型或工具。
    return "response"
```

请把装饰器放在具有明确业务名称的应用边界。服务商插桩会记录嵌套模型调用、令牌用量，以及受支持的工具或流式处理行为。

## 配置参考

| 能力           | JavaScript              | Python                  |
| ------------ | ----------------------- | ----------------------- |
| 应用名称         | `appName`               | `app_name`              |
| API 密钥       | `apiKey`                | `api_key`               |
| 收集器          | `baseUrl`               | `api_endpoint`          |
| 禁用批处理        | `disableBatch`          | `disable_batch`         |
| 自定义导出器       | `exporter`              | `exporter`              |
| 自定义 Span 处理器 | `processor`             | `processor`             |
| 内容追踪         | `traceContent`          | 环境变量或插桩配置               |
| 自定义定价        | `pricingJsonPath`       | `pricing_json_path`     |
| 禁用定价         | `pricingEnabled: false` | `pricing_enabled=False` |

两个 SDK 都可以使用自定义 OpenTelemetry 导出器和处理器。JavaScript 还支持会话追踪、关联属性、显式服务商模块、批处理控制和自定义模型定价。Python 还接受采样器、资源属性、插桩允许/阻止集合和 Span 后处理。

## 自定义导出器

如果组织已经运行 OpenTelemetry 管道，可以传入自己的导出器代替 Anyway 收集器导出器。此时鉴权和投递遵循该导出器与收集器的配置；只有最终到达 Anyway 收集器的 Span 才会显示在仪表盘。

## 数据安全

* 把智能体追踪 API 密钥保存在环境变量或密钥存储中。
* 上线前决定是否允许捕获提示词和补全内容。
* 不要记录付款凭证、智能体钱包密钥、身份文件或提现资料。
* 在关联属性中使用稳定的假名 ID，不要使用客户邮箱或法定身份。
* 在值进入 SDK 属性或模型/工具 Span 前完成脱敏。

<Warning>
  在自定义 Span 中关闭提示词捕获，并不会自动移除第三方服务商插桩记录的参数。请先使用非敏感数据检查实际上报的追踪载荷，再开启生产上报。
</Warning>