POML 与 AgentOps 集成

POML 与 AgentOps 集成

导语

AgentOps 是一款面向 AI Agent 与大语言模型应用的可观测性平台。POML 与 AgentOps 的集成可自动追踪你的 POML 调用，并将其发送至 AgentOps，用于监控、调试与分析。

安装与配置

安装

• 安装带 AgentOps 支持的 POML：

pip install poml[agent]

• 或单独安装 AgentOps：

pip install agentops

配置 API Key

• 将 AgentOps 的 API Key 配置为环境变量（可在 AgentOps Dashboard 获取）：

export AGENTOPS_API_KEY="your-api-key-here"

获取 API Key： app.agentops.ai

基本用法

启用 POML 的 AgentOps 追踪，并按常规方式使用 POML：

import os
import poml
import agentops
from openai import OpenAI

# Initialize AgentOps. Trace is automatically started.
agentops.init()

# Enable POML tracing with AgentOps
poml.set_trace("agentops", trace_dir="pomlruns")

# Use POML as usual
client = OpenAI()
messages = poml.poml(
    "explain_code.poml",
    context={"code_path": "sample.py"},
    format="openai_chat"
)
response = client.chat.completions.create(
    model="gpt-5",
    **messages
)

# Trace ends automatically at the end of the script.

追踪内容（What Gets Traced）

启用 AgentOps 集成后，POML 会自动捕获 POML Operations。每次 POML 调用会作为一次 operation 记录，包含：

• Operation 名称："poml"
• Prompt 内容：POML 原始源文本
• 上下文变量：传入 POML 调用的所有上下文变量
• 样式表：任意样式配置
• 结果：发送给 LLM 的处理后 Prompt 结构

示例 Trace 数据

{
  "resource_attributes": {
    "imported_libraries": "[\"agentops\",\"poml\"]"
  },
  "span_attributes": {
    "agentops": {
      "span": { "kind": "task" }
    },
    "task": {
      "input": "{\"args\": [\"../assets/explain_code.poml\", {\"code_path\": \"sample.py\"}, null], \"kwargs\": {}}",
      "output": "{\"messages\": [{\"speaker\": \"human\", \"content\": \"# Task\\n\\nYou are a senior Python developer. Please explain the code.\\n\\n```\\ndef greet(name):\\n print(f\\\"Hello, {name}!\\\")\\n\\ndef add(a, b):\\n return a + b\\n\\ndef factorial(n):\\n if n == 0:\\n return 1\\n else:\\n return n * factorial(n - 1)\\n\\ndef is_even(num):\\n return num % 2 == 0\\n\\ndef main():\\n greet(\\\"Alice\\\")\\n x = 5\\n y = 7\\n print(f\\\"{x} + {y} = {add(x, y)}\\\")\\n print(f\\\"Factorial of {x} is {factorial(x)}\\\")\\n if is_even(x):\\n print(f\\\"{x} is even\\\")\\n else:\\n print(f\\\"{x} is odd\\\")\\n\\nif __name__ == \\\"__main__\\\":\\n main()\\n```\"}], \"runtime\": {\"temperature\": 0.7, \"maxTokens\": 256}}"
    },
    "operation": { "name": "poml" }
  }
}

参考链接（See Also）

• POML Tracing Guide: microsoft.github.io/poml/stable…
• AgentOps Documentation: docs.agentops.ai
• AgentOps Dashboard: app.agentops.ai

总结

通过与 AgentOps 的集成，POML 调用会被自动追踪并发送到 AgentOps，用于监控、调试与分析；相关信息将以 operation 的形式记录，包括原始 POML、上下文变量、样式表与处理后的 Prompt 结构。更多细节可参考上述文档链接。