コンテンツにスキップ
Pi Documentation

JSON イベントストリームモード

Terminal window
pi --mode json "Your prompt"

すべてのセッションイベントを JSON 行として stdout に出力します。pi を他のツールやカスタム UI に統合するのに便利です。

イベント型

Section titled “イベント型”

イベントは AgentSessionEvent で定義されています：

type AgentSessionEvent =
  | AgentEvent
  | { type: "queue_update"; steering: readonly string[]; followUp: readonly string[] }
  | { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
  | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
  | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };

queue_update はキューが変更されるたびに、保留中の steering と follow-up キュー全体を発行します。compaction_start と compaction_end は手動および自動コンパクションの両方をカバーします。

基本イベントは AgentEvent から：

type AgentEvent =
  // Agent lifecycle
  | { type: "agent_start" }
  | { type: "agent_end"; messages: AgentMessage[] }
  // Turn lifecycle
  | { type: "turn_start" }
  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
  // Message lifecycle
  | { type: "message_start"; message: AgentMessage }
  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
  | { type: "message_end"; message: AgentMessage }
  // Tool execution
  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };

メッセージ型

Section titled “メッセージ型”

基本メッセージは packages/ai/src/types.ts から：

  • UserMessage（134 行目）
  • AssistantMessage（140 行目）
  • ToolResultMessage（152 行目）

拡張メッセージは packages/coding-agent/src/core/messages.ts から：

  • BashExecutionMessage（29 行目）
  • CustomMessage（46 行目）
  • BranchSummaryMessage（55 行目）
  • CompactionSummaryMessage（62 行目）

出力形式

Section titled “出力形式”

各行は JSON オブジェクトです。最初の行はセッションヘッダー：

{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}

続いてイベントが発生順に出力されます：

{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{"role":"assistant","content":[],...}}
{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}

例

Section titled “例”
Terminal window
pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'