Agent Thought Event

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/orq/main/json-schema/orq-agent-thought-streaming-event-schema.json",
  "title": "Agent Thought Event",
  "description": "Emitted during agent reasoning. Contains the incremental message changes, model choices, iteration count, and token usage for this processing step.",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/orq-openapi.json#/components/schemas/AgentThoughtStreamingEvent",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "event.agents.thought"
      ]
    },
    "timestamp": {
      "type": "string",
      "description": "ISO timestamp of the event"
    },
    "data": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string"
        },
        "message_difference": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "messageId": {
                "type": "string"
              },
              "role": {
                "type": "string",
                "enum": [
                  "user",
                  "agent",
                  "tool",
                  "system"
                ]
              },
              "parts": {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "$ref": "#/$defs/TextPart"
                    },
                    {
                      "$ref": "#/$defs/ErrorPart"
                    },
                    {
                      "$ref": "#/$defs/DataPart"
                    },
                    {
                      "$ref": "#/$defs/FilePart"
                    },
                    {
                      "$ref": "#/$defs/ToolCallPart"
                    },
                    {
                      "$ref": "#/$defs/ToolResultPart"
                    }
                  ]
                }
              },
              "metadata": {
                "type": "object",
                "additionalProperties": {}
              },
              "agent_id": {
                "type": "string"
              },
              "agent_execution_id": {
                "type": "string"
              },
              "workspace_id": {
                "type": "string"
              }
            },
            "required": [
              "messageId",
              "role",
              "parts",
              "agent_id",
              "agent_execution_id",
              "workspace_id"
            ]
          }
        },
        "choice": {
          "type": "object",
          "properties": {
            "finish_reason": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "stop",
                "length",
                "tool_calls",
                "content_filter",
                "function_call",
                null
              ],
              "description": "The reason the model stopped generating tokens."
            },
            "index": {
              "type": "number",
              "default": 0,
              "description": "The index of the choice in the list of choices."
            },
            "message": {
              "type": "object",
              "properties": {
                "content": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "refusal": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "tool_calls": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "index": {
                        "type": "number"
                      },
                      "id": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string",
                        "enum": [
                          "function"
                        ]
                      },
                      "function": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64."
                          },
                          "arguments": {
                            "type": "string",
                            "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function."
                          }
                        }
                      },
                      "thought_signature": {
                        "type": "string",
                        "description": "Encrypted representation of the model internal reasoning state during function calling. Required by Gemini 3 models when continuing a conversation after a tool call."
                      }
                    }
                  }
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "assistant"
                  ]
                },
                "reasoning": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Internal thought process of the model"
                },
                "reasoning_signature": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The signature holds a cryptographic token which verifies that the thinking block was generated by the model, and is verified when thinking is part of a multiturn conversation. This value should not be modified and should always be sent to the API when the reasoning is redacted. Currently only supported by `Anthropic`."
                },
                "redacted_reasoning": {
                  "type": "string",
                  "description": "Occasionally the model's internal reasoning will be flagged by the safety systems of the provider. When this occurs, the provider will encrypt the reasoning. These redacted reasoning is decrypted when passed back to the API, allowing the model to continue its response without losing context."
                },
                "audio": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "integer"
                    },
                    "data": {
                      "type": "string"
                    },
                    "transcript": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "expires_at",
                    "data",
                    "transcript"
                  ],
                  "description": "If the audio output modality is requested, this object contains data about the audio response from the model."
                }
              },
              "description": "A chat completion message generated by the model."
            },
            "logprobs": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "content": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "properties": {
                      "token": {
                        "type": "string",
                        "description": "The token."
                      },
                      "logprob": {
                        "type": "number",
                        "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely."
                      },
                      "bytes": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "number"
                        },
                        "description": "A list of integers representing the UTF-8 bytes representation of the token."
                      },
                      "top_logprobs": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "token": {
                              "type": "string",
                              "description": "The token."
                            },
                            "logprob": {
                              "type": "number",
                              "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely."
                            },
                            "bytes": {
                              "type": [
                                "array",
                                "null"
                              ],
                              "items": {
                                "type": "number"
                              },
                              "description": "A list of integers representing the UTF-8 bytes representation of the token."
                            }
                          },
                          "required": [
                            "token",
                            "logprob",
                            "bytes"
                          ]
                        },
                        "description": "List of the most likely tokens and their log probability, at this token position."
                      }
                    },
                    "required": [
                      "token",
                      "logprob",
                      "bytes",
                      "top_logprobs"
                    ]
                  },
                  "description": "A list of message content tokens with log probability information."
                },
                "refusal": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "properties": {
                      "token": {
                        "type": "string",
                        "description": "The token."
                      },
                      "logprob": {
                        "type": "number",
                        "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely."
                      },
                      "bytes": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "number"
                        },
                        "description": "A list of integers representing the UTF-8 bytes representation of the token."
                      },
                      "top_logprobs": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "token": {
                              "type": "string",
                              "description": "The token."
                            },
                            "logprob": {
                              "type": "number",
                              "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely."
                            },
                            "bytes": {
                              "type": [
                                "array",
                                "null"
                              ],
                              "items": {
                                "type": "number"
                              },
                              "description": "A list of integers representing the UTF-8 bytes representation of the token."
                            }
                          },
                          "required": [
                            "token",
                            "logprob",
                            "bytes"
                          ]
                        },
                        "description": "List of the most likely tokens and their log probability, at this token position."
                      }
                    },
                    "required": [
                      "token",
                      "logprob",
                      "bytes",
                      "top_logprobs"
                    ]
                  },
                  "description": "A list of message refusal tokens with log probability information."
                }
              },
              "required": [
                "content",
                "refusal"
              ],
              "description": "Log probability information for the choice."
            }
          },
          "required": [
            "finish_reason",
            "message"
          ]
        },
        "choiceIndex": {
          "type": "number"
        },
        "iteration": {
          "type": "number"
        },
        "accumulated_execution_time": {
          "type": "number"
        },
        "responseId": {
          "type": "string"
        },
        "usage": {
          "type": "object",
          "properties": {
            "completion_tokens": {
              "type": "number",
              "description": "Number of tokens in the generated completion."
            },
            "prompt_tokens": {
              "type": "number",
              "description": "Number of tokens in the prompt."
            },
            "total_tokens": {
              "type": "number",
              "description": "Total number of tokens used in the request (prompt + completion)."
            },
            "prompt_tokens_details": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "cached_tokens": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "cache_creation_tokens": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "audio_tokens": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The number of audio input tokens consumed by the request."
                }
              }
            },
            "completion_tokens_details": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "reasoning_tokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "accepted_prediction_tokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "rejected_prediction_tokens": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "audio_tokens": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The number of audio output tokens produced by the response."
                }
              }
            }
          },
          "description": "Usage statistics for the completion request."
        }
      },
      "required": [
        "agent_id",
        "message_difference",
        "iteration",
        "accumulated_execution_time"
      ]
    }
  },
  "required": [
    "type",
    "timestamp",
    "data"
  ],
  "$defs": {
    "DataPart": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "data"
          ]
        },
        "data": {
          "type": "object",
          "additionalProperties": {}
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "kind",
        "data"
      ],
      "title": "Data Part",
      "description": "A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools."
    },
    "ErrorPart": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "error"
          ]
        },
        "error": {
          "type": "string"
        },
        "code": {
          "type": "number"
        }
      },
      "required": [
        "kind",
        "error"
      ],
      "title": "Error Part",
      "description": "An error content part containing error information. Used when an error occurs during agent execution."
    },
    "FilePart": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "file"
          ]
        },
        "file": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "bytes": {
                  "type": "string",
                  "minLength": 1,
                  "description": "base64 encoded content of the file"
                },
                "mimeType": {
                  "type": "string",
                  "description": "Optional mimeType for the file"
                },
                "name": {
                  "type": "string",
                  "description": "Optional name for the file"
                }
              },
              "required": [
                "bytes"
              ],
              "title": "Binary format",
              "description": "Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format."
            },
            {
              "type": "object",
              "properties": {
                "uri": {
                  "type": "string",
                  "description": "URL for the File content"
                },
                "mimeType": {
                  "type": "string",
                  "description": "Optional mimeType for the file"
                },
                "name": {
                  "type": "string",
                  "description": "Optional name for the file"
                }
              },
              "required": [
                "uri"
              ],
              "title": "File in URI format",
              "description": "File in URI format. Check in the model's documentation for the supported mime types for the URI format"
            }
          ]
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "kind",
        "file"
      ],
      "title": "File Part",
      "description": "A file content part that can contain either base64-encoded bytes or a URI reference. Used for images, documents, and other binary content in agent communications."
    },
    "TextPart": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "text"
          ]
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "kind",
        "text"
      ],
      "title": "Text Part",
      "description": "A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses."
    },
    "ToolCallPart": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "tool_call"
          ]
        },
        "tool_name": {
          "type": "string"
        },
        "tool_call_id": {
          "type": "string",
          "minLength": 1
        },
        "arguments": {
          "type": "object",
          "additionalProperties": {}
        },
        "thought_signature": {
          "type": "string"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "kind",
        "tool_name",
        "tool_call_id",
        "arguments"
      ],
      "title": "Tool Call Part",
      "description": "A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution."
    },
    "ToolResultPart": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "tool_result"
          ]
        },
        "tool_call_id": {
          "type": "string",
          "minLength": 1
        },
        "result": {},
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        }
      },
      "required": [
        "kind",
        "tool_call_id"
      ],
      "title": "Tool Result Part",
      "description": "The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation."
    }
  }
}