当与 --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可选请求标识符（可能省略）

​
Stream 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 在单次代理执行过程中保持一致