--output-format
quando usada junto com --print
. Esses formatos incluem opções estruturadas para uso programático (json
, stream-json
) e um formato de texto simplificado para acompanhamento de progresso legível por humanos.
O
--output-format
padrão é stream-json
. Essa opção só é válida ao imprimir (--print
) ou quando o modo de impressão é inferido (stdout não TTY ou stdin encadeado).Formato JSON
json
emite um único objeto JSON (seguido por uma nova linha) quando a execução é concluída com sucesso. Deltas e eventos de ferramenta não são emitidos; o texto é agregado ao resultado final.
Em caso de falha, o processo encerra com um código diferente de zero e escreve uma mensagem de erro em stderr. Nenhum objeto JSON bem formado é emitido em casos de falha.
Resposta de sucesso
Field | Description |
---|---|
type | Sempre "result" para resultados do terminal |
subtype | Sempre "success" para conclusões bem-sucedidas |
is_error | Sempre false para respostas bem-sucedidas |
duration_ms | Tempo total de execução em milissegundos |
duration_api_ms | Tempo da chamada à API em milissegundos (atualmente igual a duration_ms ) |
result | Texto completo da resposta do assistente (concatenação de todos os deltas de texto) |
session_id | Identificador único da sessão |
request_id | Identificador opcional da requisição (pode ser omitido) |
Formato JSON em stream
stream-json
emite JSON delimitado por novas linhas (NDJSON). Cada linha contém um único objeto JSON que representa um evento em tempo real durante a execução.
O stream termina com um evento terminal result
em caso de sucesso. Em caso de falha, o processo encerra com um código diferente de zero e o stream pode terminar antes, sem um evento terminal; uma mensagem de erro é escrita em stderr.
Tipos de eventos
Inicialização do sistema
Campos futuros, como
tools
e mcp_servers
, podem ser adicionados a este evento.Mensagem do usuário
Delta de texto do assistant
Concatena todos os valores de
message.content[].text
na ordem para reconstruir a resposta completa da assistente.Eventos de chamadas de ferramenta
Tipos de chamadas de ferramenta
- Iniciada:
tool_call.readToolCall.args
contém{ "path": "file.txt" }
- Concluída:
tool_call.readToolCall.result.success
contém metadados e conteúdo do arquivo
- Iniciada:
tool_call.writeToolCall.args
contém{ "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
- Concluída:
tool_call.writeToolCall.result.success
contém{ "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
- Podem usar a estrutura
tool_call.function
com{ "name": "tool_name", "arguments": "..." }
Resultado do terminal
Sequência de exemplo
Formato de texto
text
fornece um fluxo simplificado e legível por pessoas das ações do agente. Em vez de eventos JSON detalhados, ele emite descrições de texto concisas do que o agente está fazendo em tempo real.
Esse formato é útil para acompanhar o progresso do agente sem o custo de analisar dados estruturados, sendo ideal para logs, depuração ou um acompanhamento simples de progresso.
Exemplo de saída
Notas de implementação
- Cada evento é emitido como uma única linha terminada por
\n
- Eventos
thinking
são ocultados no modo de impressão e não aparecem em nenhum dos formatos de saída - Novos campos podem ser adicionados ao longo do tempo de maneira retrocompatível (consumidores devem ignorar campos desconhecidos)
- O formato de streaming fornece atualizações em tempo real, enquanto o formato JSON aguarda a conclusão antes de emitir resultados
- Concatena todos os deltas da mensagem do
assistant
para reconstruir a resposta completa - IDs de chamadas de ferramenta podem ser usados para correlacionar eventos de início e conclusão
- IDs de sessão permanecem consistentes durante toda a execução de um único agente