AgentHog Setup 是一个面向 AI 编程助手的技能，用于在用户项目中安装并配置 AgentHog 追踪（tracing）能力。它要求端到端执行，且不得跳过验证步骤。
一、用途 该技能的目标是让 AI 编程助手自动完成 AgentHog SDK 的安装、初始化、环境变量接线、主智能体循环包装、工具调用埋点，并验证首条追踪数据成功上报。适用于需要为智能体项目接入可观测性追踪的场景。
二、运行时检测 技能首先检查项目根目录以确定语言与主框架：若存在 pyproject.toml、requirements.txt、setup.py 或 *.py 文件则判定为 Python；若存在含 "type": "module" 的 package.json、TypeScript 文件或 tsconfig.json 则判定为 TypeScript/Node。若两者皆有，默认以主入口点使用的语言为准，确实模糊时询问用户。随后识别主框架（FastAPI、Flask、Django、LangGraph、LangChain、Express、Vercel AI SDK、Next.js、Hono 等），框架决定 init 的放置位置与每请求循环的位置。
三、配置收集 需要两个值：AGENTOS_API_KEY 与 AGENTOS_WORKSPACE_ID。这些是密钥，运行时从环境变量解析，SDK 读取 AGENTOS_API_KEY / AGENTOS_WORKSPACE_ID。助手的工作是将代码接线到这些环境变量并确认值存在，绝不获取、查看或存储密钥本身。若环境变量已设置则直接接线；未设置时用户提供，推荐使用 agenthog init（agenthog >= 0.5.0），它会提示输入两个值、写入被 gitignore 的 .env（权限 0600）并跨重启与跨 shell 持久化；备选方案是 shell export（临时，仅当前 shell 会话有效）。值可从 https://app.theagentos.space 获取（API key：Settings → API Keys；workspace ID：侧边栏标签/右上角）。确认存在性时只做布尔检测，不读取值，例如运行 python3 -c "import os; print('AGENTOS_API_KEY set:', bool(os.getenv('AGENTOS_API_KEY')))"。凭据安全要求：绝不接受聊天中粘贴的 API key；绝不搜索文件系统或读取文件寻找密钥；绝不打开 .env 读取密钥；绝不硬编码密钥；绝不打印或回显密钥。端点 AGENTOS_ENDPOINT 默认静默使用 https://api.theagentos.space，仅在有明确证据用户想覆盖时才询问。
四、安装 SDK 最低支持版本：Python agenthog >= 0.9.0，TypeScript agenthog >= 0.3.0。低于此版本的 SDK 事件会被摄取 API 拒绝（HTTP 426）。Python 下限为 0.9.0 是因为该技能端到端依赖其特性：agenthog init 凭据（0.5.0）、面向 OpenAI 兼容端点的原始 HTTP LLM 捕获与退出时自动刷新（0.6.0）、用于追踪智能体工具的 @agenthog.tool / @traceable 装饰器（0.7.0）、以及一次调用捕获工具的 instrument_module（0.9.0）。安装时使用项目现有包管理器并固定下限。Python 示例：uv add 'agenthog>=0.9.0'、poetry add 'agenthog@>=0.9.0'、pip install -U 'agenthog>=0.9.0'；针对框架可安装 extras，如 agenthog[openai]、agenthog[anthropic]、agenthog[langchain]、agenthog[otel]。TypeScript 示例：pnpm add agenthog@latest、npm install agenthog@latest、yarn add agenthog@latest、bun add agenthog@latest。TS 的自动埋点通过 integrations 导入接线，安装时无需 extras。安装后必须验证版本满足下限，不满足则升级并重新检查；若仍无法满足则停止并告知用户。
五、在应用启动时接线 init init 调用必须运行一次，位于任何想要追踪的 LLM/工具调用之前。放置位置因框架而异：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；Vercel AI SDK 在构造 AI 客户端处。Python 初始化模式使用 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>")，随后调用 agenthog.autoinstrument() 自动埋点支持的 LLM/框架库。TypeScript 初始化模式使用 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>" })，并按集成导入包装器。agentId 应描述服务用途而非仅仓库名。
六、包装主智能体循环 一个 task_run 等于智能体的一次端到端执行。Python 使用上下文管理器 with agenthog.start_task_run(user_id=user_id) as ctx:，可用 kwargs 包括 agent_id、task_run_id、trace_id、user_id、session_id，没有 metadata= kwarg。TypeScript 使用回调 await startTaskRun({ userId: req.body.userId }, async () => {...})，可用字段包括 agentId、taskRunId、traceId、userId、sessionId，无 metadata 字段。若框架有中间件概念，优先将 start_task_run 接线为中间件。
七、工具埋点 autoinstrument() 捕获 LLM 调用但不捕获智能体工具。首选方式是使用 instrument_module（Python，agenthog >= 0.9.0）对工具模块一次调用包装所有公共函数，返回被包装名称列表；它会跳过私有辅助函数、导入名称、类和常量，可用 exclude/include 调整。当工具分散在多个文件或需要逐函数控制时，使用 @agenthog.tool 装饰器逐个装饰。TypeScript 目前没有 @tool 装饰器或 instrument_module，需使用显式 logToolCall 路径。替代方案是显式记录：Python 使用 agenthog.get_default_client().log_tool_call(name=name, input=args, output=result)，TypeScript 使用 await getDefaultClient()!.logToolCall({ name, input: args, output: result })。
八、文档与验证 向 .env.example 添加三行占位符（仅占位符，绝不写真实密钥）。最后验证首条追踪数据成功上报，确认追踪中实际显示 LLM 步骤而非空 task_run。
九、限制 TypeScript 的自动捕获能力目前弱于 Python（JS SDK 为 pre-0.6.0，批量捕获、装饰器、原始 HTTP 捕获、退出时自动刷新均为 Python 独有）。若智能体与自定义或非 OpenAI 形状的端点通信且两条路径均无法识别，LLM 调用不会被自动捕获，需显式记录。退出时刷新在 agenthog >= 0.6.0 自动进行，但硬杀（SIGKILL、os._exit）会绕过，需在退出前调用 agenthog.shutdown()。