当与 --print 搭配使用时，Cursor Agent CLI 通过 --output-format 选项提供多种输出格式。这些格式包括用于程序化使用的结构化格式（json、stream-json），以及用于便于阅读的进度跟踪的简化文本格式。
默认的 --output-format 为 stream-json。该选项仅在打印（--print）时有效，或在推断为打印模式（非 TTY 的 stdout 或经管道传入的 stdin）时生效。

​
JSON 格式

当运行成功完成时，json 输出格式会输出单个 JSON 对象（随后换行）。不会输出增量和工具事件；文本会聚合到最终结果中。 发生失败时，进程以非零退出码结束，并将错误消息写入 stderr。失败情况下不会输出任何格式良好的 JSON 对象。

​
成功响应

成功时，CLI 会输出具有以下结构的 JSON 对象： 
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "result": "<full assistant text>",
  "session_id": "<uuid>",
  "request_id": "<optional request id>"
}
FieldDescription
type终端结果始终为 "result"
subtype成功完成时始终为 "success"
is_error成功响应始终为 false
duration_ms总执行时长（毫秒）
duration_api_msAPI 请求时长（毫秒）（当前等于 duration_ms）
result完整的助手响应文本（所有文本增量的拼接）
session_id唯一会话标识符
request_id可选请求标识符（可能省略）

​
流式 JSON 格式

stream-json 输出格式会产生以换行分隔的 JSON（NDJSON）。每一行包含一个 JSON 对象，表示执行期间的实时事件。 成功时，流以终止性的 result 事件结束。失败时，进程会以非零退出码结束，流可能在没有终止事件的情况下提前结束；错误消息会写到 stderr。

​
事件类型

​
系统初始化

在每个会话开始时仅触发一次： 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
未来可能会在该事件中添加 tools 和 mcp_servers 等字段。

​
用户消息

包含用户的输入提示词： 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
助手文本增量

在助手生成响应时会多次触发。这些事件包含增量文本片段： 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
按顺序拼接所有 message.content[].text 的值，以重建完整的助手响应。

​
工具调用事件

通过开始与完成事件跟踪工具调用： 工具调用开始： 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
工具调用完成： 
{
  "type": "tool_call",
  "subtype": "completed",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" },
      "result": {
        "success": {
          "content": "file contents...",
          "isEmpty": false,
          "exceededLimit": false,
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

​
工具调用类型

读取文件工具：
  • 开始：tool_call.readToolCall.args 包含 { "path": "file.txt" }
  • 完成：tool_call.readToolCall.result.success 包含文件元数据和内容
写入文件工具：
  • 开始：tool_call.writeToolCall.args 包含 { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • 完成：tool_call.writeToolCall.result.success 包含 { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
其他工具：
  • 可能使用 tool_call.function 结构，形如 { "name": "tool_name", "arguments": "..." }

​
终止结果

成功完成时触发的最后一个事件： 
{
  "type": "result",
  "subtype": "success",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<full assistant text>",
  "session_id": "<uuid>",
  "request_id": "<optional request id>"
}

​
示例序列

下面是一个具有代表性的 NDJSON 序列，展示典型的事件流： 
{"type":"system","subtype":"init","apiKeySource":"login","cwd":"/Users/user/project","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","model":"Claude 4 Sonnet","permissionMode":"default"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"阅读 README.md 并生成摘要"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"我会"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"读取 README.md 文件"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"},"result":{"success":{"content":"# Project\n\nThis is a sample project...","isEmpty":false,"exceededLimit":false,"totalLines":54,"totalChars":1254}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"并生成摘要"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"},"result":{"success":{"path":"/Users/user/project/summary.txt","linesCreated":19,"fileSize":942}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"我会读取 README.md 文件并生成摘要","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
文本格式

text 输出格式以简洁、可读的方式呈现代理的动作流。与详细的 JSON 事件不同，它会实时输出代理正在执行操作的精炼文本描述。 这种格式适合在无需解析结构化数据的情况下监控代理进度，非常适合用于日志、调试或简单的进度跟踪。

​
示例输出

Read file
Edited file
Ran terminal command
Created new file
每个动作都会在代理执行时单独占一行，及时反馈代理的任务进展。

​
实现说明

  • 每个事件以单行形式发出，并以 \n 结尾
  • 在打印模式下会抑制 thinking 事件，且不会出现在任一输出格式中
  • 字段可能会随时间以向后兼容的方式新增（使用方应忽略未知字段）
  • 流式格式提供实时更新，而 JSON 格式会在完成后再输出结果
  • 将所有 assistant 消息的增量片段拼接以还原完整响应
  • 可使用工具调用 ID 将开始/完成事件关联起来
  • 会话 ID 在一次代理执行过程中保持不变