> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Run a Sigma agent (Beta)

POST https://api.sigmacomputing.com/v2/workbooks/{workbookId}/agents/{agentId}
Content-Type: application/json

Run a Sigma agent and return its reply.

**Beta**: This documentation describes a public beta feature and is subject to the [Beta features](/docs/sigma-product-releases#beta-features) disclaimer.

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`.

### 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.

Reference: https://help.sigmacomputing.com/reference/run-agent

## Authentication

- OAuth2 — send the obtained token as `Authorization: Bearer <token>`

## Servers

- `https://api.sigmacomputing.com` (Server for GCP (US) hosted organizations, default)
- `https://api.sa.gcp.sigmacomputing.com` (Server for GCP (KSA) hosted organizations)
- `https://aws-api.sigmacomputing.com` (Server for AWS US (West) hosted organizations)
- `https://api.us-a.aws.sigmacomputing.com` (Server for AWS US (East) hosted organizations)
- `https://api.ca.aws.sigmacomputing.com` (Server for AWS Canada hosted organizations)
- `https://api.eu.aws.sigmacomputing.com` (Server for AWS Europe hosted organizations)
- `https://api.au.aws.sigmacomputing.com` (Server for AWS Australia and APAC hosted organizations)
- `https://api.uk.aws.sigmacomputing.com` (Server for AWS UK hosted organizations)
- `https://api.us.azure.sigmacomputing.com` (Server for Azure US hosted organizations)
- `https://api.eu.azure.sigmacomputing.com` (Server for Azure Europe hosted organizations)
- `https://api.ca.azure.sigmacomputing.com` (Server for Azure Canada hosted organizations)
- `https://api.uk.azure.sigmacomputing.com` (Server for Azure United Kingdom hosted organizations)
- `https://api.au.azure.sigmacomputing.com` (Server for Azure Australia hosted organizations)

## Request

### Path parameters

- `workbookId` (string, required) — Unique identifier of the workbook that contains the agent.
- `agentId` (string, required) — Unique identifier of the Sigma agent to run.

### Body (application/json)

This endpoint expects an object.

- `messages` (list of object or object or object or object, required) — Full conversation contents.
  - User message
    - `role` (enum, required)
      - Allowed values: `user`
    - `content` (string or list of object, required) — Content of the turn, as plain text or an array of content blocks.
  - Assistant message
    - `role` (enum, required)
      - Allowed values: `assistant`
    - `content` (string, optional, nullable) — The text content generated by the AI assistant. Might be null if the AI assistant only calls tools.
    - `reasoning` (string, optional, 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` (list of object, optional) — Tool calls made by the AI assistant.
      - `id` (string, required) — Unique identifier for this tool call.
      - `type` (enum, required) — The type of tool call.
        - Allowed values: `function`
      - `function` (object, 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.
  - Tool message
    - `role` (enum, required)
      - Allowed values: `tool`
    - `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.
  - System message
    - `role` (enum, required)
      - Allowed values: `system`
    - `content` (string, required) — The workbook agent's instructions.
- `stream` (boolean, optional) — When `true`, the response is a stream of events instead of a single JSON body. Defaults to `false`.
- `sigma:versionTagName` (string, optional) — Name of the version tag whose workbook version to run the agent against. Omit to run against the latest published version.
- `responseFormat` (object or object, optional)
  - Text
    - `type` (enum, required)
      - Allowed values: `text`
  - JSON schema
    - `type` (enum, required)
      - Allowed values: `json_schema`
    - `jsonSchema` (object, required) — JSON schema the output is validated against.
- `maxTurns` (double, optional) — Maximum tool-calling steps per turn before the agent stops running. Default 50, max 100.
- `maxOutputTokens` (double, optional) — Maximum total output tokens the agent can generate. When omitted, no limit is applied.
- `metadata` (map from string to string or double or boolean, optional) — Caller-defined key/value metadata logged to the `ai_usage` table in your warehouse.

## Response

### 200

The response body.

- `object` (enum, required) — Object type, always `agent.run`.
  - Allowed values: `agent.run`
- `runId` (string, required) — Unique identifier for the agent run.
- `createdAt` (double, required) — Unix timestamp (in seconds) of when the run began.
- `completedAt` (double, required, nullable) — Unix timestamp (in seconds) when the run completed.
- `model` (string, required) — Identifier of the model that served the run.
- `status` (enum, required) — Status of the run.
  - Allowed values: `completed`, `failed`, `incomplete`, `cancelled`
- `incompleteDetails` (object, required, nullable) — Details about why the run is `incomplete`, or `null` when the run completed normally.
  - `reason` (enum, 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`).
    - Allowed values: `max_turns`, `token_limit`, `invalid_output`, `deadline`, `output_truncated`
- `output` (list of object or object or object, required) — The agent's reply turn, containing the answer text and any tool calls or tool results.
  - User message
    - `role` (enum, required)
      - Allowed values: `user`
    - `content` (string or list of object, required) — Content of the turn, as plain text or an array of content blocks.
  - Assistant message
    - `role` (enum, required)
      - Allowed values: `assistant`
    - `content` (string, optional, nullable) — The text content generated by the AI assistant. Might be null if the AI assistant only calls tools.
    - `reasoning` (string, optional, 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` (list of object, optional) — Tool calls made by the AI assistant.
      - `id` (string, required) — Unique identifier for this tool call.
      - `type` (enum, required) — The type of tool call.
        - Allowed values: `function`
      - `function` (object, 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.
  - Tool message
    - `role` (enum, required)
      - Allowed values: `tool`
    - `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` (object, required)
  - `turns` (double, required) — Number of tool-calling steps taken by the agent.
  - `durationMs` (double, required) — Total run time for the turn, in milliseconds.
  - `inputTokens` (double, required) — Input tokens consumed by the run.
  - `outputTokens` (double, required) — Output tokens produced by the run.
  - `totalTokens` (double, required) — Total tokens consumed by the run.
- `outputParsed` (object, optional) — 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, optional) — Present when a `responseFormat` was requested but the structured output could not be produced or failed schema validation.
- `workbookVersion` (double, optional) — Workbook version used to run the agent turn.

## Examples

### Simple prompt

**Request**

```json
{
  "messages": [
    {
      "content": "Summarize this month's sales trends.",
      "role": "user"
    }
  ]
}
```

**Response**

```json
{
  "object": "agent.run",
  "runId": "018f5a6e-9c2b-7d41-8e3a-2b6f9c1d4a70",
  "createdAt": 1716312245,
  "completedAt": 1716312248,
  "model": "gpt-5.1-2025-11-13",
  "status": "completed",
  "incompleteDetails": null,
  "output": [
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 2,
    "durationMs": 3210,
    "inputTokens": 512,
    "outputTokens": 24,
    "totalTokens": 536
  },
  "workbookVersion": 14
}
```

**SDK Code**

```python Simple prompt
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = { "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        }
    ] }
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Simple prompt
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Simple prompt
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Simple prompt
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Simple prompt
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}")
  .asString();
```

```php Simple prompt
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    }
  ]
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Simple prompt
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Simple prompt
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = ["messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Continue a conversation

**Request**

```json
{
  "messages": [
    {
      "content": "Summarize this month's sales trends.",
      "role": "user"
    },
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    },
    {
      "content": "Which product drove that growth?",
      "role": "user"
    }
  ]
}
```

**Response**

```json
{
  "object": "agent.run",
  "runId": "018f5a71-4d8b-7a92-9f1c-6e3b8a2d5c91",
  "createdAt": 1716312301,
  "completedAt": 1716312305,
  "model": "gpt-5.1-2025-11-13",
  "status": "completed",
  "incompleteDetails": null,
  "output": [
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "The Enterprise plan drove most of the growth, contributing 5 of the 8 points.",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 3,
    "durationMs": 4032,
    "inputTokens": 604,
    "outputTokens": 21,
    "totalTokens": 625
  },
  "workbookVersion": 14
}
```

**SDK Code**

```python Continue a conversation
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = { "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        },
        {
            "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
            "role": "user"
        },
        {
            "content": "Sales grew 8% month-over-month, led by the Northeast region.",
            "role": "assistant"
        },
        {
            "content": "Which product drove that growth?",
            "role": "user"
        }
    ] }
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Continue a conversation
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"},{"content":"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.","role":"user"},{"content":"Sales grew 8% month-over-month, led by the Northeast region.","role":"assistant"},{"content":"Which product drove that growth?","role":"user"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Continue a conversation
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Continue a conversation
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Continue a conversation
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}")
  .asString();
```

```php Continue a conversation
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    },
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    },
    {
      "content": "Which product drove that growth?",
      "role": "user"
    }
  ]
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Continue a conversation
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Continue a conversation
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = ["messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ],
    [
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    ],
    [
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    ],
    [
      "content": "Which product drove that growth?",
      "role": "user"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Structured JSON output

**Request**

```json
{
  "messages": [
    {
      "content": "Summarize this month's sales trends.",
      "role": "user"
    }
  ],
  "responseFormat": {
    "jsonSchema": {
      "properties": {
        "percentChange": {
          "type": "number"
        },
        "summary": {
          "type": "string"
        }
      },
      "required": [
        "summary",
        "percentChange"
      ],
      "type": "object"
    },
    "type": "json_schema"
  }
}
```

**Response**

```json
{
  "object": "agent.run",
  "runId": "018f5a74-2e6f-7c83-b4d2-9a1e5f3c7b62",
  "createdAt": 1716312410,
  "completedAt": 1716312413,
  "model": "gpt-5.1-2025-11-13",
  "status": "completed",
  "incompleteDetails": null,
  "output": [
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "{\"summary\":\"Sales grew 8% month-over-month, led by the Northeast region.\",\"percentChange\":8}",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 2,
    "durationMs": 2876,
    "inputTokens": 540,
    "outputTokens": 30,
    "totalTokens": 570
  },
  "outputParsed": {
    "percentChange": 8,
    "summary": "Sales grew 8% month-over-month, led by the Northeast region."
  },
  "workbookVersion": 14
}
```

**SDK Code**

```python Structured JSON output
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = {
    "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        }
    ],
    "responseFormat": {
        "jsonSchema": {
            "properties": {
                "percentChange": { "type": "number" },
                "summary": { "type": "string" }
            },
            "required": ["summary", "percentChange"],
            "type": "object"
        },
        "type": "json_schema"
    }
}
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Structured JSON output
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"}],"responseFormat":{"jsonSchema":{"properties":{"percentChange":{"type":"number"},"summary":{"type":"string"}},"required":["summary","percentChange"],"type":"object"},"type":"json_schema"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Structured JSON output
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Structured JSON output
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Structured JSON output
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}")
  .asString();
```

```php Structured JSON output
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    }
  ],
  "responseFormat": {
    "jsonSchema": {
      "properties": {
        "percentChange": {
          "type": "number"
        },
        "summary": {
          "type": "string"
        }
      },
      "required": [
        "summary",
        "percentChange"
      ],
      "type": "object"
    },
    "type": "json_schema"
  }
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Structured JSON output
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Structured JSON output
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = [
  "messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ]
  ],
  "responseFormat": [
    "jsonSchema": [
      "properties": [
        "percentChange": ["type": "number"],
        "summary": ["type": "string"]
      ],
      "required": ["summary", "percentChange"],
      "type": "object"
    ],
    "type": "json_schema"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Tool calls

**Request**

```json
{
  "messages": [
    {
      "content": "Summarize this month's sales trends.",
      "role": "user"
    }
  ]
}
```

**Response**

```json
{
  "object": "agent.run",
  "runId": "018f5a77-8b3d-7f15-a6c9-3d2e8b4f1a95",
  "createdAt": 1716312501,
  "completedAt": 1716312516,
  "model": "gpt-5.1-2025-11-13",
  "status": "completed",
  "incompleteDetails": null,
  "output": [
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "function": {
            "arguments": "{\"query\":\"SELECT region, SUM(revenue) AS revenue FROM sales GROUP BY region ORDER BY revenue DESC LIMIT 5\"}",
            "name": "database_execute_query"
          },
          "id": "call_9qFY3EaBsBb0uJh0rqXvVsED",
          "type": "function"
        }
      ]
    },
    {
      "content": "[{\"region\":\"Northeast\",\"revenue\":482000},{\"region\":\"West\",\"revenue\":401500},{\"region\":\"Midwest\",\"revenue\":312800},{\"region\":\"South\",\"revenue\":298100},{\"region\":\"Southeast\",\"revenue\":210400}]",
      "role": "tool",
      "tool_call_id": "call_9qFY3EaBsBb0uJh0rqXvVsED"
    },
    {
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 3,
    "durationMs": 15239,
    "inputTokens": 16700,
    "outputTokens": 654,
    "totalTokens": 17354
  },
  "workbookVersion": 14
}
```

**SDK Code**

```python Tool calls
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = { "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        }
    ] }
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Tool calls
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Tool calls
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Tool calls
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Tool calls
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}")
  .asString();
```

```php Tool calls
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    }
  ]
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Tool calls
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Tool calls
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = ["messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Streaming response

**Request**

```json
{
  "messages": [
    {
      "content": "Summarize this month's sales trends.",
      "role": "user"
    }
  ],
  "stream": true
}
```

**Response**

```json
{
  "object": "agent.run",
  "runId": "018f5a6e-9c2b-7d41-8e3a-2b6f9c1d4a70",
  "createdAt": 1716312245,
  "completedAt": 1716312248,
  "model": "gpt-5.1-2025-11-13",
  "status": "completed",
  "incompleteDetails": null,
  "output": [
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 2,
    "durationMs": 3210,
    "inputTokens": 512,
    "outputTokens": 24,
    "totalTokens": 536
  },
  "workbookVersion": 14
}
```

**SDK Code**

```python Streaming response
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = {
    "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        }
    ],
    "stream": True
}
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Streaming response
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"}],"stream":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Streaming response
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"stream\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Streaming response
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"stream\": true\n}"

response = http.request(request)
puts response.read_body
```

```java Streaming response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"stream\": true\n}")
  .asString();
```

```php Streaming response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    }
  ],
  "stream": true
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Streaming response
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"stream\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Streaming response
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = [
  "messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ]
  ],
  "stream": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```