AI与Agent · 2026-07-05

Agent任务日志应该记录哪些字段

Agent 任务日志不是聊天记录，而是可追溯的执行账本：身份、阶段、工具、产物、错误、人审、成本和安全边界都要能查到。

团队开始使用 Agent 之后，很快会遇到一个新问题：它做事很快，但做完之后，别人不一定知道它到底做了什么。一个 Agent 可能查了网页、读了文件、调用了工具、生成了图片、写了 JSON、改了队列、跑了发布 dry-run、写回知识库。最后它说“已完成”，团队却想问：哪一步完成了？证据在哪？失败过没有？谁批准发布？下次怎么复现？

这就是任务日志的价值。Agent 任务日志不是聊天记录，也不是把终端输出原样保存。它应该是一份可追溯的执行账本：记录任务身份、阶段状态、工具调用、重要产物、证据来源、错误恢复、人审结果和下一步。日志写得好，团队就能复盘、排障、审计、交接和改进工作流；日志写得差，Agent 做得越多，团队越难管理。

很多团队把日志当成“出了问题才需要的东西”。但对 Agent 来说，日志应该从第一天就设计。因为 Agent 常常会跨工具、跨文件、跨服务、跨时间执行任务。没有统一字段，后续追踪会很麻烦。

这篇文章给出一份面向团队管理者的 Agent 任务日志字段模板。它不是某个框架的官方标准，而是一组可以落地的记录方法。

先分清日志、追踪和指标

Agent 可观测性里，经常会混用三个词：日志、追踪、指标。它们相关，但用途不同。

日志记录事件。比如“开始生成图片”“dry-run 通过”“Personal OS 写回失败”“CSV 状态已更新”。它回答的是发生了什么。

追踪连接事件。OpenAI Agents SDK 的 Tracing 文档说明，SDK 内置 tracing，会收集 agent run 中的 LLM generations、tool calls、handoffs、guardrails 和自定义事件，帮助调试、可视化和监控工作流。也就是说，追踪不只看单条日志，而是把一次任务里的步骤串起来。

指标统计趋势。比如每天完成多少任务、平均耗时、失败率、重试次数、图片生成耗时、发布 dry-run 通过率。它回答的是整体运行情况。

OpenTelemetry 把 traces、metrics、logs 都放在可观测性框架里，并通过 Semantic Conventions 提供统一命名思路。对 Agent 团队来说，这提醒我们：字段命名要稳定，不要今天叫 taskId，明天叫 job_id，后天又叫 runName。

一个稳妥的起点是：每个任务有一份任务日志，每个阶段有事件记录，每次外部调用有 trace_id 或 run_id，最后再汇总成指标。

第一组字段：任务身份

任务身份字段让团队知道“这是什么任务”。没有身份，后面的日志都难以关联。

建议记录：

• task_id：任务唯一 ID；
• parent_task_id：如果它来自批量任务或上游任务，记录父任务；
• article_id 或 business_id：业务侧稳定 ID；
• title：任务标题；
• goal：本次目标；
• requester：发起人或发起系统；
• owner_agent：执行 Agent；
• reviewer：人审负责人；
• priority：优先级；
• risk_level：风险等级；
• created_at：创建时间。

task_id 和业务 ID 要分开。task_id 是执行账本的 ID，article_id、order_id、ticket_id 这类业务 ID 是外部对象的 ID。一个业务对象可能经历多次任务，比如初稿、修订、审发、发布验证。混成一个 ID，后期很难追踪。

第二组字段：阶段和状态

长任务不能只写“完成”或“失败”。它应该有阶段状态。

建议记录：

• current_stage：当前阶段；
• stage_status：pending、running、done、failed、needs_review、blocked；
• started_at；
• finished_at；
• duration_ms；
• completed_stages；
• pending_stages；
• next_action；
• status_reason。

阶段名称要贴近工作流，而不是贴近代码实现。比如内容生产可以有 context_loaded、sources_collected、draft_written、images_generated、manifest_checked、dry_run_passed、os_writeback_done。团队成员看到这些名字，应该能知道任务推进到哪里。

状态原因很重要。failed 只是结果，status_reason 才说明为什么。比如“图片生成第三张超时”“来源不足，需要补官方文档”“dry-run 被平台规则拦截”。没有原因，状态只是标签。

第三组字段：上下文和输入版本

Agent 的输出很依赖输入。输入变了，结果就会变。任务日志要记录当时用的上下文和输入版本。

建议记录：

• prompt_version：任务提示词或工作流模板版本；
• context_query：读取上下文时使用的查询词；
• context_result_path：上下文接口返回文件；
• source_queue_path：队列文件或任务源；
• source_row_id：队列行 ID；
• config_version：重要配置版本；
• model_profile：使用的模型或路由；
• environment：本地、测试、生产、dry-run 等执行环境。

这里要注意隐私和安全。日志不应该记录 token、cookie、完整密钥、私人原文或敏感输入。可以记录“从哪个安全来源读取了凭据”“使用了哪个环境变量名”，但不要把值写进日志。

第四组字段：工具调用和外部动作

Agent 的能力来自工具调用。工具调用如果不记录，后续就很难解释结果从哪里来。

建议每次工具调用记录：

• tool_name；
• tool_category；
• call_id；
• started_at；
• finished_at；
• status；
• latency_ms；
• input_summary；
• output_summary；
• output_path；
• retry_count；
• error_type；
• error_message；
• side_effect。

input_summary 只写摘要，不写敏感原文。比如“调用 Personal OS context，查询词为 Agent 任务日志 字段”，不要把 token 写进去。side_effect 用来标记这次调用是否改变了外部状态，比如写文件、上传图片、发布草稿、更新任务系统。外部动作要写清楚，因为恢复任务时需要知道哪些步骤已经发生。

W3C Trace Context 规范定义了用于传播分布式追踪上下文的 HTTP 头和值格式，让跨服务请求可以被关联起来。Agent 如果跨多个服务运行，至少要有类似 trace_id、span_id、parent_span_id 的关联字段，方便把一次任务串成事件链。

第五组字段：产物和证据

Agent 任务的结果不应该只写“已生成”。要记录产物路径和证据。

建议记录：

• artifact_type；
• artifact_path；
• artifact_hash；
• artifact_status；
• source_url；
• source_title；
• source_type；
• evidence_path；
• manifest_path；
• contact_sheet_path；
• dry_run_output_path；
• public_url；
• canonical_url。

对内容生产来说，article.md、article.html、sources.md、image_prompts.json、image_generation_manifest.json、image_contact_sheet.jpg、dry-run 输出、发布 URL 都应该进入日志。对代码任务来说，修改文件、测试输出、构建结果、PR 链接也应该进入日志。

artifact_hash 不一定每次都要有，但重要产物最好有。它能帮助判断文件是否被后续改过。没有 hash，也至少要有路径和更新时间。

第六组字段：错误、恢复和重试

任务日志必须能支持恢复，不只是记录失败。

建议记录：

• last_error_type；
• last_error_message；
• failed_stage；
• retry_count；
• retry_strategy；
• next_retry_at；
• recoverable；
• recovery_action；
• blocked_by；
• human_review_required。

错误类型要稳定，比如 temporary_network、invalid_input、permission_denied、quality_gate_failed、external_policy_blocked。不要每次写一段自由文本就结束。稳定类型能让团队统计：到底是接口不稳、输入质量差、权限问题多，还是图片质量门禁常失败。

recoverable 是一个实用字段。它告诉系统这次失败是否适合 Agent 继续处理。如果 recoverable=false，就不要自动重试，转入人审或等待外部条件。

第七组字段：人审和授权

Agent 任务日志不只记录机器做了什么，也要记录人在哪里做了判断。

建议记录：

• review_status；
• reviewer；
• review_started_at；
• review_finished_at；
• review_notes_path；
• decision；
• decision_reason；
• approved_for_publish；
• publish_authorizer；
• approval_artifacts。

NIST AI Risk Management Framework 强调通过治理、映射、测量和管理来处理 AI 风险。放在 Agent 任务里，治理不是一句口号，而是能看见谁做了什么判断、依据是什么、是否允许进入下一步。

尤其是对外发布、客户资料、财经、健康、法律等内容，人审和授权字段不该省。Agent 可以准备材料，但团队要知道谁承担了发布判断。

第八组字段：成本、用量和性能

团队管理者还需要知道 Agent 消耗了多少资源。

建议记录：

• model_calls；
• tool_calls；
• input_tokens；
• output_tokens；
• image_generations；
• api_cost_estimate；
• elapsed_time_ms；
• queue_wait_ms；
• retry_total；
• files_changed；
• artifacts_count。

这些字段不只是为了算钱，也能帮助优化流程。比如某类任务总是图片生成耗时很长，团队就可以调整图片策略；某类任务总是重试多，说明输入或工具稳定性要改善；某个 Agent 产物很多但通过率低，说明质量门禁要前移。

第九组字段：安全和保留

日志本身也可能变成风险。如果日志里保存了密钥、私人信息、客户原文、未脱敏数据，问题会比没有日志更严重。

建议记录：

• contains_sensitive_data；
• redaction_applied；
• retention_policy；
• access_level；
• pii_present；
• secret_scanned；
• safe_to_share；
• deletion_due_at。

这里的原则很简单：日志要能追踪任务，但不应该泄露任务不该泄露的内容。对外协作时，最好能生成“可分享日志摘要”，只包含任务 ID、阶段、产物路径、验证结果和剩余风险，不包含原始敏感输入。

一条可用的日志记录长什么样

一条简化的 Agent 任务日志可以长这样：

{
  "task_id": "xy-plus-ai-014-production-20260703",
  "business_id": "XY-PLUS-AI-014",
  "title": "Agent任务日志应该记录哪些字段",
  "current_stage": "dry_run_passed",
  "stage_status": "done",
  "owner_agent": "codex",
  "risk_level": "normal",
  "artifacts": [
    "article.md",
    "image_generation_manifest.json",
    "output/publish_dry_run_xy_plus_ai_014.json"
  ],
  "last_error_type": null,
  "human_review_required": true,
  "next_action": "等待审发线检查并正式发布",
  "updated_at": "2026-07-03T15:10:00+08:00"
}

这不是完整 schema，但已经能回答很多问题：它是什么任务，做到哪一步，有哪些产物，是否需要人审，下一步是什么。

一张字段清单

如果只能先建一个最小版本，可以从 20 个字段开始：

• task_id；
• business_id；
• title；
• goal；
• owner_agent；
• reviewer；
• risk_level；
• current_stage；
• stage_status；
• status_reason；
• artifact_paths；
• source_paths；
• tool_calls；
• side_effects；
• last_error_type；
• retry_count；
• human_review_required；
• next_action；
• safe_to_share；
• updated_at。

这 20 个字段不复杂，但足以让团队从“Agent 做完说一声”升级为“Agent 做事可追溯”。

有些内容不要进日志

日志不是越详细越好。很多团队一开始为了追求可追溯，会把完整输入、完整输出、完整网页内容、完整终端输出都塞进日志。短期看起来资料很全，长期会带来搜索噪音、权限风险和存储压力。

Agent 日志应该尽量记录“足以复盘的摘要”和“能找到证据的路径”，而不是把所有原文复制一遍。比如来源资料可以记录标题、URL、访问时间和摘录路径，不必把整篇网页写进日志；工具调用可以记录输入摘要、输出文件和状态，不必保存完整密钥、请求头或用户私密原文；错误信息可以保留错误类型和可排查片段，不必把包含凭据的环境变量一起保存。

尤其不要记录五类内容：密钥和 token，cookie 和会话凭证，未经脱敏的客户资料，私人聊天或私人笔记全文，包含身份证号、手机号、地址、健康信息等个人数据的原始表格。需要排障时，可以把敏感内容放在受控证据文件或安全系统里，日志只保存引用路径和访问级别。

这条边界很重要。一个好的任务日志应该让团队能追踪 Agent 做了什么，而不是把所有风险集中到日志系统里。可追溯和少暴露并不冲突，重点是记录 ID、摘要、路径、状态和责任人。

字段落地可以分三步

团队不必第一天就把所有字段做成复杂平台。更实际的做法，是分三步落地。

第一步，先建最小执行账本。每个 Agent 任务都记录 task_id、business_id、current_stage、stage_status、artifact_paths、last_error_type、next_action、updated_at。这一步解决“做到哪了”和“下一步是什么”。

第二步，补上证据和恢复字段。把 source_paths、tool_calls、side_effects、retry_count、human_review_required、review_status 加进去。这一步解决“证据在哪”“失败怎么处理”“谁需要看”。

第三步，再接入标准化追踪和指标。把 trace_id、span_id、latency_ms、token 用量、图片生成次数、失败率、阶段耗时做成可查询数据。这一步解决跨服务排障和团队级复盘。

字段从小开始，并不代表管理粗糙。只要命名稳定、路径清楚、敏感信息不乱写，最小日志也能发挥作用。等任务量上来，再把日志、追踪和指标接到同一个可观测性系统里，成本会低很多。

结论：日志是 Agent 团队协作的共同语言

Agent 任务日志不是为了堆数据，而是为了让团队能管理自动化。它让管理者知道进度，让审稿人找到证据，让开发者定位错误，让发布负责人看到授权，让下一个 Agent 接得住任务。

好的日志不会把所有东西都塞进去。它会记录任务身份、阶段状态、工具调用、产物证据、错误恢复、人审授权、资源消耗和安全边界。它也会刻意避开密钥和敏感原文，只留下足够复盘和恢复的信息。

当 Agent 只是偶尔帮忙，日志可以很轻；当 Agent 开始承担内容生产、发布、数据处理或客户流程，日志就变成团队的共同语言。没有这门语言，自动化越多，管理越模糊；有了它，Agent 才能从“会做事”走向“做事可追溯”。