agenthog-setup

Agenthog 设置

你（正在阅读此技能的 AI 编码 Agent）需要在用户的项目中安装并配置 AgentHog 跟踪。请从头到尾遵循此技能。 不要跳过验证步骤。

1. 检测运行时

查看项目根目录，以确定语言和主要框架：

• Python：如果看到 pyproject.toml、requirements.txt、setup.py 或 *.py 文件。
• TypeScript / Node：如果看到 package.json 中含有 "type": "module"、TypeScript 文件或 tsconfig.json。

如果两者都有，默认采用主要入口文件使用的语言。如果确实无法判断，请询问用户。

确定主要框架：FastAPI、Flask、Django、LangGraph、LangChain、Express、Vercel AI SDK、Next.js、Hono 等。框架决定 init 应放在哪里，以及逐请求循环位于何处。

2. 收集配置

用户需要提供两个值。端点会自动设置默认值——除非触发下方某个覆盖条件，否则不要询问用户端点。

必需：AGENTOS_API_KEY 和 AGENTOS_WORKSPACE_ID

这些是机密，在运行时从环境中读取——SDK 会从环境变量读取 AGENTOS_API_KEY / AGENTOS_WORKSPACE_ID（请参阅下方的 init 示例）。你的任务是让代码读取这些环境变量，并确认变量已设置——绝不要自行获取、查看或存储机密。

1. 环境中已设置？（已设置 AGENTOS_API_KEY、AGENTOS_WORKSPACE_ID）——很好，无需收集。让代码读取它们，然后继续。

2. 尚未设置？由用户提供，你绝不要处理机密。 提供两种方式，并且优先推荐第一种。单独使用 export 只在当前 shell 中生效，终端关闭后就会失效——这常导致“跟踪过一次，然后就停止了”，而且其他 shell（包括你自己的工具 shell）都看不到：

   • 首选 — agenthog init（agenthog >= 0.5.0）：提示输入这两个值，将其写入受 Git 忽略的 .env（0600），并在重启后及不同 shell 中保留。由用户运行并输入密钥；你不要代为操作。由于它会写入 .env，这些值在新终端中仍然有效——不会出现两个 shell 之间的设置不一致。

   • 备用 — shell export（临时方式，适合快速单次运行）：用户在运行应用的终端中设置这些值：

     export AGENTOS_API_KEY=<their key>
     export AGENTOS_WORKSPACE_ID=<their workspace id>
     

     快速入门页面提供了可直接粘贴的 export 代码块。这些设置仅在当前 shell 会话中有效——如需持久保存，请推荐使用 agenthog init。

   请从 https://app.theagentos.space 获取这些值（API 密钥：Settings → API Keys；工作区 ID：侧边栏标签 / 右上角）。用户完成其中一种方式后，按名称确认变量已设置（见下文），然后继续。

确认变量已设置，但绝不读取机密：

检查变量是否已设置，绝不要检查其值——只进行布尔值存在性测试，绝不要 cat .env，也不要将密钥回显到你的上下文中：

# prints only yes/no; resolves env first, then a gitignored .env the app loads
python3 -c "import os; print('AGENTOS_API_KEY set:', bool(os.getenv('AGENTOS_API_KEY')))"

如果输出 False，说明用户尚未完成 agenthog init / export——请让他们完成，不要尝试查找其值。

凭证安全（不得偏离）：

• 绝不接受用户粘贴到聊天中的 API 密钥。 如果用户提出要粘贴密钥，请婉拒，并告知他们改为运行 agenthog init（或使用 export）——你只按名称引用 AGENTOS_API_KEY，绝不涉及其值。
• 绝不搜索文件系统或读取文件来查找密钥，也绝不打开 .env 读取机密。只能按环境变量名称确认其是否存在（如上所述）。
• 绝不在源代码中硬编码密钥，也绝不打印或回显密钥。代码通过环境变量引用 AGENTOS_API_KEY，绝不包含密钥字面值。
• Agent 绝不将明文机密写入磁盘。 由用户运行 agenthog init 并输入密钥，或由用户自行写入。你可以创建或更新 .env.example 并填入占位符（第 6 步）；真实值绝不由你处理。

Endpoint：默认静默使用

AGENTOS_ENDPOINT 按以下顺序解析，不会提示用户：

1. 如果环境中已设置 AGENTOS_ENDPOINT，则使用该值。
2. 否则，使用默认值：https://api.theagentos.space。

仅当有明确证据表明用户想要覆盖该值时，才询问用户 Endpoint——例如，他们在请求中说了类似“我在自托管”或“我们在自己的基础设施上运行 agenthog”的话。

否则：采用默认值并继续。每次快速入门都询问 Endpoint，会给使用托管云服务的 95% 用户带来恼人的阻碍。

绝不要提交明文 API 密钥，也不要自行将其写入磁盘——由用户填写真实值（第 6 步会配置代码和 .env.example 占位符）。

3. 安装 SDK（必须使用足够新的版本）

最低支持版本：Python agenthog >= 0.9.0，TypeScript agenthog >= 0.3.0。 数据接入 API 会拒绝来自较旧 SDK 的事件（HTTP 426）。Python 的最低版本为 0.9.0，因为此技能从头到尾都依赖其功能：agenthog init 凭据（0.5.0）、用于 OpenAI 兼容 Endpoint 的原始 HTTP 大模型捕获 + 退出时自动刷新（0.6.0）、用于追踪 Agent 工具的 @agenthog.tool / @traceable 装饰器（0.7.0），以及一次调用即可捕获工具的 instrument_module（第 5b 步，0.9.0）——确保不会静默遗漏任何工具。低于最低版本时，配置会产生不完整的追踪记录（缺少工具步骤，或者短生命周期进程完全没有追踪记录）。

作为配置的一部分，使用项目现有的包管理器安装（或升级）agenthog——也就是当前用于管理项目依赖的包管理器。告知用户你要添加的内容，并锁定最低版本要求，以便升级现有的旧版本，而不是维持原样。如果无法确定包管理器，请先询问再安装。

Python

检测包管理器（uv、poetry、pip、pipenv），并安装满足最低版本要求的版本，同时执行升级：

# uv  (uv add always resolves to the newest allowed; the floor guarantees ≥0.9.0)
uv add 'agenthog>=0.9.0'

# poetry
poetry add 'agenthog@>=0.9.0'

# pip  (-U upgrades an already-installed older copy)
pip install -U 'agenthog>=0.9.0'

对于支持一流自动检测的框架，安装相应的 extras：

# OpenAI calls
uv add 'agenthog[openai]>=0.9.0'

# Anthropic
uv add 'agenthog[anthropic]>=0.9.0'

# LangChain / LangGraph
uv add 'agenthog[langchain]>=0.9.0'

# OpenTelemetry passthrough
uv add 'agenthog[otel]>=0.9.0'

TypeScript

# pnpm (preferred)
pnpm add agenthog@latest

# npm
npm install agenthog@latest

# yarn
yarn add agenthog@latest

# bun
bun add agenthog@latest

TypeScript 的自动检测通过导入集成来配置——安装时无需额外的 extras。请参阅 reference/typescript.md。

验证已安装的版本满足最低要求（不得跳过）

安装后，确认版本符合要求（Python >= 0.9.0，TypeScript >= 0.3.0）。如果不符合，请先升级并重新检查，再继续操作——后续配置（以及数据接入 API）都以此为前提。

# Python — prints the installed version; exits non-zero if below the floor.
python -c "import agenthog, sys; from importlib.metadata import version; \
v=version('agenthog'); print('agenthog', v); \
sys.exit(0 if tuple(map(int, v.split('.')[:2])) >= (0,9) else 1)"

# TypeScript — same idea.
node -e "const v=require('agenthog/package.json').version; const [a,b]=v.split('.').map(Number); \
console.log('agenthog', v); process.exit((a>0||b>=3)?0:1)"

如果检查结果显示版本低于最低要求（Python 0.9.0，TypeScript 0.3.0），请使用与安装时相同的方式升级（通过包管理器升级 agenthog），然后重新运行检查。如果仍无法达到最低版本要求（例如，注册表尚未发布该版本），请停止并告知用户，不要继续使用不受支持的版本——否则其遥测数据会在接入时遭到拒绝，或者追踪记录会缺少工具步骤。

4. 在应用启动时配置 init

必须在任何想要追踪的 LLM/工具调用之前运行一次 init。请将其放在应用的主要入口点：

框架	调用 init 的位置
FastAPI	main.py 中，位于 app = FastAPI() 之前
Flask	app.py 中，位于 app = Flask(__name__) 之前
Django	settings.py 底部，或 apps.py 的 ready() 钩子中
LangGraph 脚本	脚本顶部，位于构建图之前
Express	index.ts/server.ts 中，位于 app.listen 之前
Next.js	instrumentation.ts（Next.js 官方 OTel/追踪钩子）
Vercel AI SDK	构造 AI 客户端的位置

Python 初始化模式

import os
import agenthog

agenthog.init(
    api_key=os.environ["AGENTOS_API_KEY"],
    endpoint=os.environ.get("AGENTOS_ENDPOINT", "https://api.theagentos.space"),
    workspace_id=os.environ["AGENTOS_WORKSPACE_ID"],
    agent_id="<descriptive-agent-name>",  # pick based on what this service is
)

# Auto-instrument supported LLM / framework libraries. Detects installed
# packages (openai, anthropic, langchain) and patches them. As of
# agenthog >= 0.6.0 it ALSO captures raw-HTTP calls to OpenAI-compatible
# /chat/completions endpoints made via `requests` or `httpx` — so agents that
# POST directly to NVIDIA, Together, Groq, OpenRouter, a local vLLM/Ollama,
# etc. (instead of through a vendor SDK) get traced with no code change.
agenthog.autoinstrument()

Provider 覆盖范围。 autoinstrument()（>= 0.6.0）支持供应商 SDK 以及原始 HTTP OpenAI 兼容调用。如果 Agent 使用的自定义或 非 OpenAI 格式端点无法被这两种方式识别，LLM 调用将不会被自动捕获——请使用 agenthog.emit("agent.llm_call", {...}) 显式记录（工具则使用 log_tool_call，见步骤 5b）。验证时（步骤 7）， 请确认跟踪中实际显示了 LLM 步骤，而不只是一个空的 task_run。

agenthog >= 0.6.0 会自动在退出时刷新：init() 会注册 atexit + SIGTERM 清理处理程序，因此短时运行的 CLI / 脚本无需手动调用 flush()， 缓冲数据也会送达。只有强制终止（SIGKILL、os._exit）会跳过此操作——如果会发生这种退出， 请在退出前调用 agenthog.shutdown()。

TypeScript 初始化模式

import { init } from "agenthog";

init({
  apiKey: process.env.AGENTOS_API_KEY!,
  endpoint: process.env.AGENTOS_ENDPOINT ?? "https://api.theagentos.space",
  workspaceId: process.env.AGENTOS_WORKSPACE_ID!,
  agentId: "<descriptive-agent-name>",
});

// Auto-instrumentation is per-integration in TS. Import the wrapper for the
// LLM client you use. Examples:
//   import "agenthog/integrations/openai";
//   import "agenthog/integrations/anthropic";
//   import "agenthog/integrations/vercelAI";
//   import "agenthog/integrations/langchain";

选择一个能描述服务功能、而不只是仓库名称的 agentId。 示例：customer-support-bot、code-review-agent、etl-pipeline。

5. 使用 start_task_run 包装主要 Agent 循环

一个 task_run = Agent 的一次端到端执行（一条用户消息 → 一个最终响应，或一次 cron 触发 → 一个任务完成）。各个 Span 嵌套在其中。

Python — 上下文管理器

with agenthog.start_task_run(user_id=user_id) as ctx:
    # Auto-instrumented LLM calls in here are traced under one task_run_id.
    # Tool calls are NOT auto-traced unless they go through a framework
    # (LangChain/LangGraph) — see Step 5b for hand-written tool loops.
    result = my_agent.run(user_input)
    return result

可用的 kwargs：agent_id、task_run_id、trace_id、user_id、 session_id。没有 metadata= kwarg——请改用上述显式 kwargs 附加归因信息。

对于 HTTP 处理程序（FastAPI/Flask），请包装处理程序主体：

@app.post("/chat")
async def chat(req: ChatRequest):
    with agenthog.start_task_run(user_id=req.user_id):
        return await my_agent.run(req.message)

TypeScript — 回调

import { startTaskRun } from "agenthog";

app.post("/chat", async (req, res) => {
  await startTaskRun({ userId: req.body.userId }, async () => {
    const out = await myAgent.run(req.body.message);
    res.json(out);
  });
});

可用的 StartTaskRunArgs 字段：agentId、taskRunId、traceId、 userId、sessionId。没有 metadata 字段。

如果用户使用的框架提供中间件机制（Express、Hono、FastAPI 中间件），优先将 start_task_run 接入为中间件，以便自动为每个请求 创建一个 task_run。

5b. 为 Agent 的工具添加插桩（完整执行树）

autoinstrument() 会捕获 LLM 调用（供应商 SDK + 原始 HTTP OpenAI 兼容调用），但不会捕获 Agent 的工具：调用 API、查询数据库、地理编码、运行计算的普通函数。如果不做处理，跟踪中 只会显示 LLM 步骤，而查找工具使用情况的评估会错误地报告“Agent 从未使用工具 / 出现幻觉”。这是所有跟踪器的相同边界——Arize/LangSmith 只有在经过插桩的 框架中才会自动跟踪完整执行树；对于手写工具，它们也要求添加注解。

此步骤会生成完整的工作流树（工具调用 + LLM 调用），而不仅仅是 模型步骤。只要 Agent 有工具/辅助函数，就要执行此步骤。

首选方案 — 一次调用即可处理整个工具模块（Python，agenthog >= 0.9.0）

将 instrument_module 指向存放 Agent 工具函数的模块。它会通过一次调用，将其中定义的每个公开函数包装为一个 agent.tool_call 步骤——这样就不会像逐个函数添加装饰器那样，悄然漏掉工具。它会返回已包装名称的列表；请保留该列表，用于步骤 7 的数量核验。

import agenthog
import weather            # the module with the agent's tool functions

agenthog.init(...)
wrapped = agenthog.instrument_module(weather)
# wrapped == ['get_weather', 'get_air_quality', 'geocode']

它会跳过私有辅助函数（名称以 _ 开头）、导入的名称、类和常量。 如果默认筛选不符合需求，可调整选择范围：

• 公开函数不是工具 → instrument_module(weather, exclude=["build_prompt"])。
• 工具名称以 _ 开头，或该工具与导入项同处一个模块 → instrument_module(weather, include=["_geocode"])。

已使用 @agenthog.tool 装饰的函数会被识别，不会重复包装。枚举 Agent 的工具模块，并将每个模块传入一次 instrument_module 调用——这样，“捕获所有工具”就由结构保障，而不是依赖可能执行不彻底的逐函数判断。

当工具分散在多个文件中，或你想单独控制每个函数时——逐个添加装饰器

在 Agent 使用的每个工具函数上添加 @agenthog.tool。每个函数只需一行； 它会捕获参数 → tool.input、返回值 → tool.output，以及时长 / 状态 / 错误，并将其作为 agent.tool_call 步骤记录在当前活动的 task_run 下。适用于同步和异步函数；在调用 init() 之前添加也安全。请为每个工具添加装饰器——漏掉的工具不会出现在跟踪记录中（这正是 instrument_module 能避免的问题）。

import agenthog

@agenthog.tool
def get_weather(city: str) -> dict | None:
    ...

@agenthog.tool(name="geocode")          # custom step name
def _geocode(city: str) -> tuple[float, float] | None:
    ...

TypeScript 目前还没有 @tool 装饰器或 instrument_module（JS SDK 尚未达到 0.6.0；批量捕获、装饰器、原始 HTTP 捕获和退出时自动刷新目前仅适用于 Python）。对于 Node/TS Agent，请使用下方“替代方案”中的显式 logToolCall 路径来检测工具；还要注意，在 JS SDK 追上之前，其他自动捕获功能不如 Python 完善。

识别工具函数——通常是入口点在调用 LLM 之前或前后调用的辅助函数（数据获取、查询、操作）。任一方式都应生成类似这样的多步骤跟踪记录： task_run → get_weather → geocode → get_air_quality → llm_call。

替代方案 — 显式记录（用于较旧的 SDK，或原始工具调用循环）

如果无法添加装饰器（例如，工具在模型工具调用循环中动态分派，或使用既没有 instrument_module 也没有 @tool 的 TS SDK），请记录每次调用：

result = run_tool(name, **args)
agenthog.get_default_client().log_tool_call(name=name, input=args, output=result)

const result = await runTool(name, args);
await getDefaultClient()!.logToolCall({ name, input: args, output: result });

log_tool_call / logToolCall 接受 name，以及可选的 input、output、 status、duration_ms、error。只有在每个工具都已通过自动检测的框架运行时，才跳过工具检测。

6. 记录配置（仅占位符——绝不能写入真实密钥）

在 .env.example 中添加三行占位符（或创建该文件）。此文件会提交到代码库，因此绝不能包含真实密钥：

AGENTOS_API_KEY=agops_replace_me
AGENTOS_WORKSPACE_ID=ws_replace_me
AGENTOS_ENDPOINT=https://api.theagentos.space

对于真实值：

• **Python（在第 2 步中使用了 agenthog init）：**已写入并忽略 .env（由 gitignore 规则排除）——除了上面的 .env.example 占位符（供团队成员使用）之外，无需再做其他操作。
• **其他情况：**告知用户自行设置真实值——可在其 shell 环境、密钥管理器或被 gitignore 排除的 .env 中设置。请勿代替用户将明文密钥写入任何文件。如果他们使用 .env，请确认它已列入 .gitignore（如果缺失则添加），以免密钥被提交。

确保 .env 确实被加载（不要跳过）

.env 文件不会自行填充 os.environ / process.env。SDK 会在运行时从环境中读取密钥（第 4 步），因此，如果应用没有加载 .env，即使用户正确设置了所有内容，仍会因密钥为空或缺失而没有跟踪记录。请根据运行时配置加载步骤：

运行时	.env 如何进入环境
Next.js	自动加载——Next 会加载 .env / .env.local。无需添加任何内容。
Node（非 Next）	使用 node --env-file=.env … 运行（Node 20+），或将 import "dotenv/config"; 添加为第一个导入语句。
Python — FastAPI / Flask / 脚本	在 agenthog.init(...) 之前添加 from dotenv import load_dotenv; load_dotenv()（添加 python-dotenv 依赖），或使用 pydantic-settings，或通过 uv run --env-file .env … 运行。
任何运行时	或者在启动前直接在 shell 中导出：export AGENTOS_API_KEY=… AGENTOS_WORKSPACE_ID=…。

请选择与项目匹配的方式。如果添加了 load_dotenv()，请将其放在入口点顶部，在 init 运行之前。完成前，请确认变量确实已填充（第 7 步中的“确认 AGENTOS_API_KEY 已加载”检查）。

7. 验证（硬性门槛——不得跳过，不得想当然）

此步骤为强制步骤，且具有阻断性。 只有看到真实运行产生的真实追踪记录，才算完成设置。仅接入 init 和 start_task_run 本身不会产生追踪记录：如果没有捕获到 LLM/工具调用，追踪记录就只是空的 task_run，不会显示任何有用内容。绝不要因为代码“看起来接好了”就报告成功——只有在实际看到追踪记录后才能报告成功。

检查追踪记录是否完整，而不只是确认它存在。 记录应包含 LLM 调用，以及 Agent 使用的每个工具对应的 tool_call 步骤（步骤 5b）。**统计数量：**不同的 tool_call 步骤数量必须等于已插桩的工具数量——也就是 instrument_module 返回的列表长度，或使用 @agenthog.tool 装饰的函数数量。数量更少就说明有工具遗漏（或某条执行路径未运行）；如果追踪记录只有 llm_call、没有工具步骤，说明工具完全没有插桩——返回步骤 5b 重新处理。数量不匹配时不得通过此门槛。目标是获得完整的执行树，就像 Arize/LangSmith 展示的那样。

运行应用。发起一个会触发包装后处理程序的请求。然后按以下顺序，从最简单的方式开始，选择一种途径验证：

途径 A——仪表板（始终可用）

在浏览器中打开：

https://app.theagentos.space/traces

如有需要，请登录。刚才发起请求产生的追踪记录应会在几秒内出现。默认使用此途径。

途径 B——CLI 验证器（离线，基于密码学）

agenthog CLI 作为已安装的入口点提供，不能通过 python -m agenthog 运行。项目没有 __main__.py。请直接调用入口点：

# If agenthog[audit] is installed in the active env:
agenthog audit verify --workspace-id $AGENTOS_WORKSPACE_ID

# Or, ephemerally without modifying the project's deps:
uvx --with 'agenthog[audit]' agenthog audit verify --workspace-id $AGENTOS_WORKSPACE_ID

# Or, with uv run from outside any project (mirrors `uv run --no-project`):
uv run --no-project --with 'agenthog[audit]' agenthog audit verify \
    --workspace-id $AGENTOS_WORKSPACE_ID

不要运行 python -m agenthog audit verify——这会因 'agenthog' is a package and cannot be directly executed 而失败。CLI 通过 agenthog 控制台脚本入口点调用，而非通过模块运行器。

注意：agenthog audit verify 需要 [audit] 额外依赖（会安装 cryptography，用于 Ed25519 验证）。如果你为了追踪只安装了 agenthog[openai]，请添加 [audit] 以进行验证，或使用途径 A。

30 秒后仍未出现追踪记录

1. 检查应用的标准输出中是否有 [agenthog.sdk] 警告行。
2. 确认已加载 AGENTOS_API_KEY（不为空，也不是占位符）。
3. 确认端点可访问：curl -I $AGENTOS_ENDPOINT。
4. 确认应用确实在处理程序运行前调用了 init（有时 init 接在处理程序导入之后——请调整导入顺序，确保模块加载时先运行 init）。
5. 追踪记录已出现，但内容为空（没有 LLM 步骤）？ 模型调用未被捕获。autoinstrument() 会覆盖供应商 SDK，并且在 agenthog >= 0.6.0 时，也会覆盖原始 HTTP 的 OpenAI 兼容 /chat/completions 调用。自定义或不符合 OpenAI 格式的端点不会被自动追踪：请使用 agenthog.emit("agent.llm_call", {...}) 记录。（旧版 SDK 永远不会捕获原始 requests / httpx 调用——请升级到 >= 0.6.0，或改用设置了自定义 base_url 的 OpenAI SDK。）
6. 短时运行的脚本没有发送任何内容？ 在 agenthog >= 0.6.0 中，缓冲区会在退出时自动刷新；旧版本则需在进程退出前添加 agenthog.flush()，或进行升级。

8. 反馈结果

确认追踪记录可见后，请告知用户：

• 安装了什么（哪些额外依赖）
• init 调用所在位置（文件 + 行号）
• 包装循环所在位置（文件 + 行号）
• 验证追踪记录的 trace_id（方便用户直接打开）

规则

• 绝不抛出异常。 即使 AgentHog 配置错误，用户的 Agent 也必须继续运行。SDK 保证自身调用不会引发异常；你的接线方式应符合这一约定。
• 凭据必须保留在环境变量中。 API 密钥会在运行时从环境变量读取。绝不要将其硬编码、打印或回显，也不要将明文值写入文件，更不要扫描文件系统来查找它。将代码接入环境变量，并让用户自行放置密钥（步骤 2）。
• 不要自动采集机密信息。 如果用户的提示词包含 PII 或 API 密钥，请在报告中说明隐私控制选项（capture_content=False）——不要悄悄更改默认设置。
• 不要重构无关代码。 只修改接入追踪所必需的部分。如果用户希望开展更广泛的可观测性工作，请让他们明确提出。
• 如果项目中已有 uv，就使用 uv。 否则，使用项目现有的包管理器。不要引入新的包管理器。