--- title: "Submit Agent Session Tool Outputs" method: POST path: "/v1/agent_sessions/{session_id}/tool_outputs" tags: ["chat"] --- # Submit Agent Session Tool Outputs `POST /v1/agent_sessions/{session_id}/tool_outputs` Persist resolved client tool outputs for the session's open turn. ## Path parameters - `session_id` string, required ## Request body - SubmitAgentSessionToolOutputsRequestBody — Persist resolved client tool outputs without continuing the turn. - `toolOutputs` union[], required — Client tool results for pending calls on the trailing assistant message, matched by ``toolCallId``. Resending a persisted output verbatim is a no-op; an output that differs from the persisted result or matches no call is rejected with HTTP 409 and code ``agent_session_tool_outputs_conflict``. - union - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputAvailablePart — Tool part in output-available state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown - `output` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputErrorPart — Tool part in output-error state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown - `rawInput` unknown - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputAvailablePart — Dynamic tool part in output-available state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown, required - `output` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputErrorPart — Dynamic tool part in output-error state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown, required - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - `id` string, required - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - `id` string, required - `approved` boolean, required - `reason` string, nullable - `lastMessageId` string, required — The trailing assistant message's id. On mismatch the submission is rejected with HTTP 409 and code ``agent_session_messages_stale``. ## Response `200` Successful Response - SubmitAgentSessionToolOutputsResponseBody — The trailing assistant message with the submitted outputs applied. - `data` PhoenixUIMessage, required — ``UIMessage`` with metadata narrowed to the Phoenix wire shapes. - `id` string, required - `role` 'system' | 'user' | 'assistant', required - `metadata` MessageMetadata — ``UIMessage.metadata`` as a registry of namespaces. - `phoenix` union - PhoenixAssistantMessageMetadata — The ``phoenix`` metadata namespace of an assistant message. - `type` 'assistant', required - `sessionId` string, required - `turnTraceContext` TurnTraceContext — The trace identity a turn's spans are parented to. - `traceId` string, required - `rootSpanId` string, required - `startedAt` string, date-time, required - `usage` AssistantMessageMetadataUsage - `tokens` AssistantMessageMetadataUsageTokens, required - … - `promptDetails` AssistantMessageMetadataUsageCacheTokenDetails — Prompt-cache token counts, mounted as the usage payload's ``prompt_details`` because cached tokens are a breakdown of the prompt. - … - `interrupted` boolean - PhoenixUserMessageMetadata — The ``phoenix`` metadata namespace the browser attaches to outgoing user messages. - `type` 'user', required - `currentDateTime` string, required - `timeZone` string, required - `isCompactionMessage` boolean - `pydantic_ai` PydanticAIMessageMetadata — Local pin of pydantic-ai's message-level ``pydantic_ai`` metadata namespace (its private ``_PydanticAIMessageMetadata``), merged into the assistant metadata by the stream's metadata chunk. - `timestamp` string, date-time, nullable - `parts` union[], required - union - TextUIPart — A text part of a message. - `type` 'text' - `text` string, required - `state` 'streaming' | 'done', nullable - `providerMetadata` object, nullable - ReasoningUIPart — A reasoning part of a message. - `type` 'reasoning' - `text` string, required - `state` 'streaming' | 'done', nullable - `providerMetadata` object, nullable - ToolInputStreamingPart — Tool part in input-streaming state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-streaming' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolInputAvailablePart — Tool part in input-available state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-available' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputAvailablePart — Tool part in output-available state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown - `output` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesToolOutputErrorPart — Tool part in output-error state. - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown - `rawInput` unknown - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolApprovalRequestedPart — Tool part in approval-requested state (awaiting user decision). - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-requested' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolApprovalRespondedPart — Tool part in approval-responded state (user approved/denied, execution pending). - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-responded' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - ToolOutputDeniedPart — Tool part in output-denied state (tool was denied, terminal state). - `type` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-denied' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolInputStreamingPart — Dynamic tool part in input-streaming state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-streaming' - `input` unknown - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolInputAvailablePart — Dynamic tool part in input-available state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'input-available' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputAvailablePart — Dynamic tool part in output-available state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-available' - `input` unknown, required - `output` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `preliminary` boolean, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - PhoenixDbTypesDataStreamProtocolRequestTypesDynamicToolOutputErrorPart — Dynamic tool part in output-error state. - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-error' - `input` unknown, required - `errorText` string, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `resultProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolApprovalRequestedPart — Dynamic tool part in approval-requested state (awaiting user decision). - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-requested' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolApprovalRespondedPart — Dynamic tool part in approval-responded state (user approved/denied, execution pending). - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'approval-responded' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - DynamicToolOutputDeniedPart — Dynamic tool part in output-denied state (tool was denied, terminal state). - `type` 'dynamic-tool' - `toolName` string, required - `toolCallId` string, required - `title` string, nullable - `state` 'output-denied' - `input` unknown, required - `providerExecuted` boolean, nullable - `callProviderMetadata` object, nullable - `approval` union - ToolApprovalRequested — Tool approval in requested state (awaiting user response). - … - ToolApprovalResponded — Tool approval in responded state (user has approved or denied). - … - SourceUrlUIPart — A source part of a message. - `type` 'source-url' - `sourceId` string, required - `url` string, required - `title` string, nullable - `providerMetadata` object, nullable - SourceDocumentUIPart — A document source part of a message. - `type` 'source-document' - `sourceId` string, required - `mediaType` string, required - `title` string, required - `filename` string, nullable - `providerMetadata` object, nullable - FileUIPart — A file part of a message. - `type` 'file' - `mediaType` string, required - `filename` string, nullable - `url` string, required - `providerMetadata` object, nullable - DataUIPart — Data part with dynamic type based on data name. - `type` string, required - `id` string, nullable - `data` unknown, required - StepStartUIPart — A step boundary part of a message. - `type` 'step-start' ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — The request conflicts with the session's current state; the body's ``code`` field says how. - `422` — Validation Error - `507` — Insufficient Storage --- [API](https://skmtc.net/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/8ac3f55fbe00/schema)