Pi框架

前提条件

• Python 环境版本 >= 3.9
• Node.js 版本 >= 20.6（TS探针在启动时使用了一个较新的顶层await语法，该语法要求Node.js 20.6或更高版本。）
• Pi 框架（pi-agent-core或pi-coding-agent）已配置开启事件输出，事件schema版本为1.0。
• TS探针运行在Pi应用进程内但不修改业务代码。Python采集器是一个独立进程，需要和Pi应用共享同一个文件系统，并且能读写事件输出目录。默认目录是.pi/events。
• 采集器用一个checkpoint文件记录读取进度，支持断点续传，程重启后不会重复上报已经读过的内容。AOM后端只接受Gauge类型指标，Gauge表示某个时间点的瞬时值，采集器已经统一按这个类型上报。
• 不要在同一个Pi应用进程里同时启用pi_agent_core和pi_coding_agent两套TS探针，否则会产生重复事件。auto模式下，Coding Extension会自动让Core探针停止写入。

建议先启动Python采集器，再启动Pi应用，这样事件一产生就能被及时处理。

• 在AgentArts观测界面查看数据不收费。
• 但数据上报会产生费用：
  • 调用链上报到APM（应用性能管理服务），费用明细请参考APM计费说明。
  • 指标上报到AOM（应用运维管理服务），费用明细请参考AOM计费说明。

• AOM和APM都是按需计费，并有一定量的免费额度，超出后按实际使用量收费。

框架介绍

Pi框架是智能体开发框架，包含pi-agent-core与pi-coding-agent两种实现，提供了Agent编排、多轮对话（turn）、执行步骤（step）、大模型调用（LLM）、工具调用（Tool）等能力，并支持会话（session）级别的状态管理。Pi框架在运行时会将其内部执行过程以结构化事件的形式写入JSONL文件，供下游采集器消费。

pi_collector是Python探针提供的旁路采集组件。所谓“旁路”，是指它不参与Pi应用的业务逻辑，只是在一旁读取事件文件。它通过tail方式持续读取Pi框架输出的事件文件，依据事件的operation_id与parent_operation_id重建出完整的OpenTelemetrySpan调用链，并生成GenAI标准指标上报。

接入后，以下能力将被自动监控：

• Agent执行链路（agent/turn/step的层级关系及各节点耗时）。
• LLM调用（模型名称、Token用量、输入/输出内容、首Token耗时TTFT）。
• 工具调用（Tool name、参数、返回结果、调用耗时）。
• 会话生命周期（session.start/session.end）。
• 错误事件（error事件及is_error标记）。

接入步骤

示例代码

以下示例展示一个基于Pi Agent Core框架创建的Agent，并通过TS探针接入可观测。示例中配置了read_file和list_files两个工具。

示例中使用华为云MaaS服务提供的大模型接口，可登录华为云MaaS服务控制台，创建API Key。

图2 创建API Key

整体流程

1. 创建项目目录和代码文件。
2. 安装Node.js依赖。
3. 修改代码中的配置项（API Key、探针路径等）。
4. 在终端中配置环境变量并启动Python采集器。
5. 在另一个终端中启动Pi Agent。
6. 验证事件文件是否生成。
7. 在AgentArts平台查看调用链和指标。

代码目录结构

按照以下目录要求创建文件夹及代码文件。

core_agent_demo/
├── src/
│   ├── app.ts          # Agent 主程序，放业务逻辑，不包含探针代码
│   └── tools.ts        # 工具定义（read_file, list_files）
├── bootstrap.mjs        # 探针预加载入口由NODE_OPTIONS=--import加载，在应用启动前为Agent类附加事件记录能力
├── package.json         # Node.js项目依赖配置文件。声明项目名称、依赖包和启动脚本
├── tsconfig.json        # TypeScript 编译配置
├── README.md            # 测试用文件（Agent 会读取）
└── run.bat              # 启动脚本（含 preload + 环境变量）

• package.json：项目依赖文件

  这个文件告诉Node.js：项目叫什么、依赖哪些第三方包、用哪个命令启动。执行 npm install 时，npm会读取这个文件，自动下载其中声明的依赖包。

  {
    "name": "pi-core-agent-demo",
    "version": "1.0.0",
    "private": true,
    "type": "module",
    "scripts": {
      "start": "tsx src/app.ts"
    },
    "dependencies": {
      "@earendil-works/pi-agent-core": "^0.85.1",
      "@earendil-works/pi-ai": "^0.85.1"
    },
    "devDependencies": {
      "tsx": "^4.0.0",
      "typescript": "^5.9.0",
      "@types/node": "^22.0.0"
    }
  }

• src/tools.ts：工具定义文件

  Pi Agent Core的工具是一个包含name、description、parameters（JSON Schema）、execute方法的对象。大模型会根据description和parameters自动决定什么时候调用工具、传什么参数。

  import * as fs from "node:fs";
  
  // ── read_file 工具 ──
  export const read_file = {
    name: "read_file",
    description: "读取指定路径的文件内容",
    parameters: {
      type: "object" as const,
      properties: {
        path: {
          type: "string",
          description: "要读取的文件路径",
        },
      },
      required: ["path"],
    },
  
    async execute(toolCallId: string, params: { path: string }) {
      try {
        const content = fs.readFileSync(params.path, "utf-8");
        const truncated = content.length > 4000
          ? content.substring(0, 4000) + "\n...[truncated]"
          : content;
        return {
          content: [{ type: "text" as const, text: truncated }],
        };
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `读取文件失败: ${err.message}` }],
          isError: true,
        };
      }
    },
  };
  
  // ── list_files 工具 ──
  export const list_files = {
    name: "list_files",
    description: "列出指定目录下的文件和子目录",
    parameters: {
      type: "object" as const,
      properties: {
        path: {
          type: "string",
          description: "要列出的目录路径，默认为当前目录",
        },
      },
      required: [],
    },
  
    async execute(toolCallId: string, params: { path?: string }) {
      try {
        const dir = params.path || ".";
        const entries = fs.readdirSync(dir, { withFileTypes: true });
        const items = entries.map((entry) => {
          const type = entry.isDirectory() ? "DIR " : "FILE";
          return `${type}  ${entry.name}`;
        });
        const result = items.length > 0 ? items.join("\n") : "(空目录)";
        return {
          content: [{ type: "text" as const, text: `${dir}:\n${result}` }],
        };
      } catch (err: any) {
        return {
          content: [{ type: "text" as const, text: `列目录失败: ${err.message}` }],
          isError: true,
        };
      }
    },
  };

• tsconfig.json：TypeScript编译配置文件

  这个文件告诉TypeScript编译器：按什么规则编译 .ts 文件。这里的 module 和 moduleResolution 配置是为了让代码能与Pi框架和tsx运行时正确配合：

  • module: "ESNext"：使用最新的ES模块语法（import/export）。
  • moduleResolution: "bundler"：使用打包工具风格的模块解析方式，能正确处理Pi框架的subpath exports（即允许import ... from "@earendil-works/pi-ai/compat"这种带子路径的导入）。

  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ESNext",
      "moduleResolution": "bundler",
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "outDir": "dist"
    },
    "include": ["src/**/*.ts"]
  }

• src/app.ts：Agent智能体的主程序
  这是Agent的业务代码文件。它不包含任何探针相关代码，探针会在应用启动时通过bootstrap.mjs自动加载。

  import { Agent } from "@earendil-works/pi-agent-core";
  import { createProvider, envApiKeyAuth, openAICompletionsApi } from "@earendil-works/pi-ai/compat";
  import { read_file, list_files } from "./tools.js";
  
  // ── LLM 配置（华为云 MaaS 服务，OpenAI 兼容接口）──
  const LLM_BASE_URL = "https://api.modelarts-maas.com/openai/v1";
  const LLM_API_KEY = process.env.LLM_API_KEY || "";
  const LLM_MODEL_ID = "deepseek-v4.1-flash";
  
  // ── 1. 创建 Pi 标准 Provider ──
  const provider = createProvider({
    id: "maas",
    name: "Huawei Cloud MaaS",
    baseUrl: LLM_BASE_URL,
    auth: envApiKeyAuth("Huawei Cloud MaaS API key", ["LLM_API_KEY"]),
    models: [{
      id: LLM_MODEL_ID,
      name: "deepseek-v4.1-flash",
      api: "openai-completions" as const,
      provider: "maas",
      baseUrl: LLM_BASE_URL,
      reasoning: false,
      input: ["text"],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: 128000,
      maxTokens: 4096,
    }],
    api: openAICompletionsApi(),
  });
  
  const model = provider.getModels()[0];
  
  async function main() {
    // ── 校验 API Key ──
    if (!LLM_API_KEY) {
      console.error("[demo] 请设置环境变量 LLM_API_KEY（在华为云 MaaS 控制台创建 API Key）");
      process.exit(1);
    }
  
    // ── 2. 创建 Agent ──
    // 注意：streamFn 使用 .bind(provider) 确保 provider 上下文不丢失
    const agent = new Agent({
      streamFn: provider.streamSimple.bind(provider),
      initialState: {
        model: model,
        systemPrompt: "你是一个代码分析助手。你可以使用工具读取文件和列出目录内容。请用中文回答。",
        tools: [read_file, list_files],
      },
      sessionId: `core-demo-${Date.now()}`,
      getApiKey: async (providerName: string) => {
        if (providerName === "maas") return LLM_API_KEY;
        return undefined;
      },
    });
  
    // ── 3. 运行 Agent ──
    const task = process.argv[2] || "列出当前目录的文件，读取 README.md 并总结内容";
    console.log(`[demo] 用户: ${task}`);
  
    try {
      await agent.prompt(task);
      await agent.waitForIdle();
      console.log("[demo] Agent 运行完成");
    } catch (err: any) {
      console.log("[demo] Agent 运行出错:", err.message);
    }
  }
  
  main().catch((err) => {
    console.error("[demo] 运行失败:", err);
    process.exit(1);
  });

  • app.ts不会import任何探针代码。
  • streamFn: provider.streamSimple.bind(provider) 中，provider.streamSimple是provider对象上的方法。如果直接赋值给streamFn，会丢失this上下文，导致运行时内部访问this.baseUrl / this.models 等属性失败。使用.bind(provider)绑定上下文，确保方法内部this指向正确的provider实例。
• bootstrap.mjs：preload入口

  这是探针的预加载入口，由NODE_OPTIONS=--import加载。它会在业务代码运行之前，找到Pi框架的Agent类，并给它附加事件记录能力。

  // bootstrap.mjs - 在用户代码 import 之前，先加载并 patch pi-agent-core
  
  // patchEntry 指向 wheel 内编译好的 patch.js
  // 通过 python -c "import opentelemetry; print(list(opentelemetry.__path__)[0])" 获取路径
  // Linux 示例: /opt/conda/lib/python3.11/site-packages/opentelemetry/instrumentation/pi_node/pi_agent_core/dist/src/patch.js
  // Windows 示例: C:/Users/xxx/site-packages/opentelemetry/instrumentation/pi_node/pi_agent_core/dist/src/patch.js
  // 路径中的空格用 %20 编码（如 Program%20Files）
  const patchEntry = "file:///<$OTEL_PY_HOME>/instrumentation/pi_node/pi_agent_core/dist/src/patch.js";
  
  try {
    // 使用动态 import 让 Node 模块解析自动处理路径，无需手动拼接 node_modules 路径
    const piModule = await import("@earendil-works/pi-agent-core");
    if (typeof piModule.Agent === "function") {
      const patchModule = await import(patchEntry);
      if (typeof patchModule.patchAgentClass === "function") {
        patchModule.patchAgentClass(piModule.Agent);
        if (process.env.PI_DEBUG === "true") {
          console.warn("[huawei-pi] bootstrap: Agent patched successfully");
        }
      } else {
        if (process.env.PI_DEBUG === "true") {
          console.warn("[huawei-pi] bootstrap: patchAgentClass not found in patch module");
        }
      }
    }
  } catch (error) {
    if (process.env.PI_DEBUG === "true") {
      console.warn("[huawei-pi] bootstrap: failed to patch Agent", error);
    }
  }

  <$OTEL_PY_HOME>需要替换为下面命令的实际输出路径：

  python -c "import opentelemetry; print(list(opentelemetry.__path__)[0])"

• README.md：创建一个简单的测试文件，内容随意，例如：

  # Pi Agent Core Demo
  
  这是一个用于测试 Pi 框架接入 AgentArts 观测的示例项目。

• run.sh / run.bat：启动脚本

  脚本中各参数取值请按照实际填写。

  Linux/macOS系统

  #!/bin/bash
  # run.sh (Linux/macOS)
  cd "$(dirname "$0")"
  
  # JSONL 事件输出目录（与 Collector 共用）
  export PI_JSONL_DIR=/var/lib/pi/events
  
  # TS 探针调试日志
  export PI_DEBUG=true
  
  # 采集 LLM 输入/输出内容
  export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
  
  # LLM API Key（在华为云 MaaS 控制台创建）
  export LLM_API_KEY=<your-api-key>
  
  # Pi 业务属性（写入 JSONL resource 字段）
  export PI_DOMAIN_ID=<your-domain-id>
  export PI_PROJECT_ID=<your-project-id>
  export PI_GEN_AI_RESOURCE_ID=<your-agent-id>
  export PI_GEN_AI_RESOURCE_TYPE=agent
  export PI_USER_ID=pi-demo-user
  export PI_AGENT_NAME=pi-demo-agent
  export PI_RESOURCE_VERSION=default
  
  # 通过 bootstrap.mjs 预加载探针
  export NODE_OPTIONS="--import file:///path/to/core_agent_demo/bootstrap.mjs"
  
  npx tsx src/app.ts "$@"

  Windows系统

  @echo off
  REM run.bat (Windows)
  cd /d "%~dp0"
  
  set "PI_JSONL_DIR=F:\pi-demo\events"
  set "PI_DEBUG=true"
  set "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true"
  set "LLM_API_KEY=<your-api-key>"
  set "PI_DOMAIN_ID=<your-domain-id>"
  set "PI_PROJECT_ID=<your-project-id>"
  set "PI_GEN_AI_RESOURCE_ID=<your-agent-id>"
  set "PI_GEN_AI_RESOURCE_TYPE=agent"
  set "PI_USER_ID=pi-demo-user"
  set "PI_AGENT_NAME=pi-demo-agent"
  set "PI_RESOURCE_VERSION=default"
  
  REM Windows 路径含空格需用 %%20 编码
  set "NODE_OPTIONS=--import file:///F:/path/to/core_agent_demo/bootstrap.mjs"
  
  npx tsx src\app.ts %*

  Windows系统中.bat文件注意事项：.bat文件必须使用CRLF行尾（LF行尾会导致set命令解析失败）；路径中的空格用%20编码（%在.bat中需转义为%%）。

安装依赖

在项目根目录 core_agent_demo 下执行：

npm init -y
npm install @earendil-works/pi-agent-core@^0.85.1 @earendil-works/pi-ai@^0.85.1
npm install -D tsx@^4.0.0 typescript@^5.9.0 @types/node@^22.0.0

修改代码配置

1. 修改bootstrap.mjs中的patchEntry路径。

   代码文件中的<$OTEL_PY_HOME>需要替换为下面命令的实际输出路径：

   python -c "import opentelemetry; print(list(opentelemetry.__path__)[0])"

2. 修改run.sh或run.bat中的环境变量。
   • LLM_API_KEY：华为云MaaS模型的API Key。
   • PI_DOMAIN_ID、PI_PROJECT_ID、PI_GEN_AI_RESOURCE_ID：AgentArts平台创建的Pi框架智能体身份信息。
   • PI_JSONL_DIR：这个变量指定JSONL事件文件的输出目录。它的值由用户自己选择。代码示例中的值 /var/lib/pi/events（Linux/macOS）或 F:\pi-demo\events（Windows）只是一个示例，可以改成任意合适的目录。建议使用一个专门的空目录，避免与已有文件混在一起。
   • NODE_OPTIONS：这个路径必须替换为你项目中 bootstrap.mjs 的绝对路径，不能直接使用示例中的 /path/to/core_agent_demo/bootstrap.mjs。

     获取方法：

     • Linux/macOS：在项目根目录执行 realpath bootstrap.mjs，输出的就是绝对路径。
     • Windows：右键单击bootstrap.mjs文件，选择“属性”，查看“位置”字段，与文件名拼接得到完整路径。注意路径中的反斜杠\在NODE_OPTIONS中需要改为正斜杠/，且路径中的空格要用%20编码。

3. 给run.sh添加可执行权限（对于Linux / macOS系统）。

   chmod +x run.sh

启动Python采集器

huaweicloud-instrument python -m opentelemetry.instrumentation.pi_collector --exporter otlp

采集器会持续运行，读取PI_JSONL_DIR目录下的JSONL事件并上报。请保持此终端窗口运行，不要关闭。

启动Pi Agent

打开另一个终端（假设为终端B），进入项目目录core_agent_demo，执行：

# Linux / macOS用户执行：
./run.sh
# Windows 用户执行：
run.bat

预期输出：

[huawei-pi] bootstrap: Agent patched successfully
==================================================
Core Agent Demo (Pi Agent Core + DeepSeek-V4.1-Flash)
模型: DeepSeek-V4.1-Flash (华为云 MaaS)
工具: read_file, list_files
==================================================
[demo] 用户: 列出当前目录的文件，读取 README.md 并总结内容

（Agent 调用 list_files 列目录）
（Agent 调用 read_file 读取 README.md）
（Agent 综合结果输出总结）

[demo] Agent 运行完成

验证事件文件

在终端B中执行：

ls -la $PI_JSONL_DIR/

应看到类似pi-agent-core-<pid>-<uuid>-00000.jsonl的文件。

查看其中一个文件的首行：

head -1 $(ls $PI_JSONL_DIR/*.jsonl | head -1) | python -m json.tool

应输出包含schema_version=1.0、source=pi-agent-core的事件。

在AgentArts查看调用链

Agent运行后，Python采集器会自动读取JSONL事件并上报。在AgentArts平台的“观测 > 调用链分析”中，可看到如下类似的调用链结构：

pi agent (AGENT)
└─ pi turn (WORKFLOW)
    ├─ chat deepseek-v4.1-flash (LLM) → execute_tool list_files (PLUGIN)
    └─ chat deepseek-v4.1-flash (LLM) → execute_tool read_file (PLUGIN)
        └─ chat deepseek-v4.1-flash (LLM) → 最终总结

查看监控数据

数据上报成功后，可在AgentArts智能体平台的观测功能中查看监控数据。

1. 登录AgentArts 智能体平台。
2. 在左侧导航栏选择“观测与优化 > 观测”。
3. 在“智能体列表”页面，找到已接入的智能体，单击智能体名称进入详情页面。

查看业务指标

在“指标分析”页签中，可以查看关键业务指标：

• Tokens消耗：Input Tokens和Output Tokens的消耗总量
• 模型调用次数：应用调用大模型的累计次数
• 模型调用平均耗时：模型调用的平均响应时间
• 模型调用成功率：大模型调用成功的比例
• 会话数：应用产生的会话总数
• 响应成功率：服务响应的成功率
• 工具调用次数：Agent 调用工具的累计次数及平均耗时
• 事件采集延迟：采集器处理事件相对事件产生时间的延迟

查看调用链信息

在“调用链分析”页签中，可以查看完整的Trace调用链路：

• 查看Agent、Workflow、LLM、Plugin等Span类型的层级关系及各节点耗时
  • Agent节点对应 agent.start / agent.end
  • Workflow节点对应 turn 与 step 执行
  • LLM节点对应 llm.start / llm.end
  • Plugin节点对应工具调用 tool.start / tool.end
• 单击具体Span查看详细信息：
  • LLM节点：可查看模型名称、输入/输出消息（Input/Output Messages）、Token消耗（Total tokens）、首Token耗时（TTFT）
  • Tool节点：可查看工具名称、输入参数、返回结果、调用耗时
  • Agent节点：可查看会话级累计Token用量（含cache_read/cache_write/reasoning tokens）及总成本

查看会话分析

在“会话分析”页签中，可以查看智能体与用户对话的历史数据：

• 追踪对话上下文
• 分析模型响应耗时
• 统计Token消耗
• 快速定位对话异常问题

更多参考

• 传递session_id与user_id

  Pi框架在事件中已携带 session_id（事件必填字段）与 user_id（事件resource字段）。开发者需在Pi框架应用侧通过框架API设置会话标识与用户标识，这些信息会随事件写入JSONL文件，采集器自动关联到Span和指标上：

  # Pi 框架应用侧（伪代码，具体 API 以 Pi 框架文档为准）
  agent.run(
      session_id="session-01",
      user_id="pi_user",
      messages=[{"role": "user", "content": "你好"}],
  )

  • session_id：会话标识，用于关联同一会话内的多轮调用，会写入Span的gen_ai.conversation.id属性。
  • user_id：用户标识，用于按用户维度统计和过滤，会写入Span的gen_ai.user.id属性。
• 跨进程链路关联

  Pi事件支持upstream_traceparent字段，用于将Pi框架产生的调用链与上游服务（如API网关、Web框架）的Trace上下文关联。若上游服务已接入OpenTelemetry，将W3C Traceparent字符串传入Pi框架事件即可实现跨进程链路串联。

• 控制内容采集

  默认情况下，采集器会采集Pi事件中messages与output_messages字段的LLM 输入/输出内容。如需关闭内容采集，可在Pi框架应用侧配置不输出messages字段，事件中缺失该字段时采集器自动跳过；或设置OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false。

常见问题

无数据上报

1. 检查 PI_JSONL_DIR 指向的目录下是否存在 *.jsonl 事件文件。执行 ls -la $PI_JSONL_DIR/。
2. 确认TS探针已加载。设置 PI_DEBUG=true 后重新启动Pi应用，观察Node侧日志。同时确认 PI_INSTRUMENTATION_MODE 不为 off。
3. 确认Python采集器已启动。执行 ps -ef | grep pi_collector 查看 pi_collector 进程是否存在。
4. 检查 PI_EXPORTER 是否设置为 otlp，以及APM/AOM的endpoint是否正确。
5. 检查APM/AOM凭证（Token/Access Code）是否有效，可从AgentArts平台重新获取。
6. 查看采集器日志，寻找OTLP上报错误或事件解析错误。

JSONL事件文件未生成

1. 确认Pi框架应用已正常运行，并触发了Agent/LLM/Tool调用。
2. 确认TS探针已正确加载。检查preload路径是否正确、目标框架包 @earendil-works/pi-agent-core 是否可以正常解析（可执行 ls -la 检查文件是否存在，或设 PI_DEBUG=true 看日志）。
3. 确认 PI_JSONL_DIR 配置正确，且Pi应用进程对目录有写权限（可执行 touch $PI_JSONL_DIR/test_write 验证）。

事件丢失或重复上报

1. 采集器通过checkpoint文件记录进度，确认PI_CHECKPOINT路径可写且未被意外删除。
2. 事件去重依赖event_id，确认Pi框架生成的event_id全局唯一。
3. 若事件文件被截断或inode变化，采集器会自动重置offset重新读取。

部分Span缺失或不完整

1. Span重建依赖operation_id与parent_operation_id的父子关系，确认Pi事件字段完整。
2. 若父操作事件缺失，采集器会丢弃孤儿子操作的事件并在日志中告警。
3. 若采集器被强制终止，未关闭的Span会标记pi.incomplete=true后强制结束。

指标上报失败（invalid temporality and type combination）

1. AOM后端仅接受Gauge类型，采集器已统一使用Gauge，确认使用最新版本探针。
2. 检查OTEL_EXPORTER_OTLP_METRICS_ENDPOINT是否指向AOM的OTLP地址。