--- title: "Run a Sigma agent" method: POST path: "/v2/workbooks/{workbookId}/agents/{agentId}" tags: ["Workbooks"] --- # Run a Sigma agent `POST /v2/workbooks/{workbookId}/agents/{agentId}` ## Request - Base URL: `https://api.sigmacomputing.com` - URL: `https://api.sigmacomputing.com/v2/workbooks/{workbookId}/agents/{agentId}` - Auth: HTTP bearer Run a Sigma agent and return its reply. The API is stateless. Include the full conversation in `messages` on every call. To continue a conversation, append the response `output` to your `messages` and send them on the next call. The agent runs with your access against the workbook's latest published version unless you pass `versionTagName`. For a guide to calling Sigma agents from the API, see [Call Sigma agents with the API](https://help.sigmacomputing.com/docs/call-agents-with-the-api). ### Usage notes - Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint. - Retrieve the **agentId** by calling the [/v2/workbooks/{workbookId}/agents](https://help.sigmacomputing.com/reference/list-agents-in-workbook) endpoint. - Retrieve the **versionTagName** by calling the [/v2/tags](https://help.sigmacomputing.com/reference/list-version-tag) endpoint and using the `name` in the response. Omit to run against the latest published version. - If the `workbookVersion` changes between turns, the workbook was published mid-conversation. ### Usage scenarios - **Evaluate agent responses**: Include the response `runId` in support requests, and use it to correlate runs with your logs. ## Path parameters - `workbookId` string, required - `agentId` string, required ## Request body - object - `messages` V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItems[], required: Full conversation contents. - union - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItems0: A message from the user. - `role` 'user', required - `content` union, required: Content of the turn, as plain text or an array of content blocks. - string - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItemsOneOf0ContentOneOf1Items[]: Content as an array of text blocks. - `type` 'text', required - `text` string, required: Plain text content included as a message. If sent from a user, the contents of the prompt. If sent from the agent, the contents of the message. - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItems1: A message from the AI assistant. - `role` 'assistant', required - `content` string, nullable: The text content generated by the AI assistant. Might be null if the AI assistant only calls tools. - `reasoning` string, nullable: The AI assistant's reasoning for this turn, when the model produced any. Informational; it is ignored if sent back in a later request. - `tool_calls` V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItemsOneOf1ToolCallsItems[]: Tool calls made by the AI assistant. - `id` string, required: Unique identifier for this tool call. - `type` 'function', required: The type of tool call. - `function` V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItemsOneOf1ToolCallsItemsFunction, required: Function call details. - `name` string, required: Name of the tool invoked by the agent. - `arguments` string, required: The tool call arguments, serialized as a JSON object string. - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItems2: A tool result message. - `role` 'tool', required - `tool_call_id` string, required: The ID of the tool call this result corresponds to. - `content` string, required: The result of the tool call, as a string. - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaMessagesItems3: A system message providing instructions. - `role` 'system', required - `content` string, required: The workbook agent's instructions. - `stream` boolean: When `true`, the response is a stream of events instead of a single JSON body. Defaults to `false`. - `sigma:versionTagName` string: Name of the version tag whose workbook version to run the agent against. Omit to run against the latest published version. - `responseFormat` union - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaResponseFormat0: Free-form text output, with no enforced structure. - `type` 'text', required - V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaResponseFormat1: A JSON object validated against the supplied JSON schema. - `type` 'json_schema', required - `jsonSchema` V2WorkbooksWorkbookIdAgentsAgentIdPostRequestBodyContentApplicationJsonSchemaResponseFormatOneOf1JsonSchema, required: JSON schema the output is validated against. - `maxTurns` number, double: Maximum tool-calling steps per turn before the agent stops running. Default 50, max 100. - `maxOutputTokens` number, double: Maximum total output tokens the agent can generate. When omitted, no limit is applied. - `metadata` object: Caller-defined key/value metadata logged to the `ai_usage` table in your warehouse. ## Response `200` The response body. - WorkbooksRunAgentResponse200 - `object` 'agent.run', required: Object type, always `agent.run`. - `runId` string, required: Unique identifier for the agent run. - `createdAt` number, double, required: Unix timestamp (in seconds) of when the run began. - `completedAt` number, double, nullable, required: Unix timestamp (in seconds) when the run completed. - `model` string, required: Identifier of the model that served the run. - `status` 'completed' | 'failed' | 'incomplete' | 'cancelled', required: Status of the run. - `incompleteDetails` V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaIncompleteDetails, required: Details about why the run is `incomplete`, or `null` when the run completed normally. - `reason` 'max_turns' | 'token_limit' | 'invalid_output' | 'deadline' | 'output_truncated', required: Why the run stopped early: `max_turns`, `token_limit`, `deadline`, or `output_truncated` identify the limit that stopped the run; `invalid_output` means the requested `responseFormat` could not be produced (see `outputError`). - `output` V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItems[], required: The agent's reply turn, containing the answer text and any tool calls or tool results. - union - V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItems0: A message from the user. - `role` 'user', required - `content` union, required: Content of the turn, as plain text or an array of content blocks. - string - V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItemsOneOf0ContentOneOf1Items[]: Content as an array of text blocks. - `type` 'text', required - `text` string, required: Plain text content included as a message. If sent from a user, the contents of the prompt. If sent from the agent, the contents of the message. - V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItems1: A message from the AI assistant. - `role` 'assistant', required - `content` string, nullable: The text content generated by the AI assistant. Might be null if the AI assistant only calls tools. - `reasoning` string, nullable: The AI assistant's reasoning for this turn, when the model produced any. Informational; it is ignored if sent back in a later request. - `tool_calls` V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItemsOneOf1ToolCallsItems[]: Tool calls made by the AI assistant. - `id` string, required: Unique identifier for this tool call. - `type` 'function', required: The type of tool call. - `function` V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItemsOneOf1ToolCallsItemsFunction, required: Function call details. - `name` string, required: Name of the tool invoked by the agent. - `arguments` string, required: The tool call arguments, serialized as a JSON object string. - V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputItems2: A tool result message. - `role` 'tool', required - `tool_call_id` string, required: The ID of the tool call this result corresponds to. - `content` string, required: The result of the tool call, as a string. - `usage` V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaUsage, required - `turns` number, double, required: Number of tool-calling steps taken by the agent. - `durationMs` number, double, required: Total run time for the turn, in milliseconds. - `inputTokens` number, double, required: Input tokens consumed by the run. - `outputTokens` number, double, required: Output tokens produced by the run. - `totalTokens` number, double, required: Total tokens consumed by the run. - `outputParsed` V2WorkbooksWorkbookIdAgentsAgentIdPostResponsesContentApplicationJsonSchemaOutputParsed: The agent's answer parsed into the structure requested in `responseFormat`. Present only when a `responseFormat` was specified and the output satisfied it. - `outputError` string: Present when a `responseFormat` was requested but the structured output could not be produced or failed schema validation. - `workbookVersion` number, double: Workbook version used to run the agent turn. --- [API](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api.md) - [All operations](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/revisions/fb6036208c49?raw)