Call Sigma agents with the API (Beta)

You can run a Sigma agent programmatically with the Sigma REST API and use the reply in your own application, instead of interacting with the agent through a chat element or action in a workbook.

For example, you can use the API to embed a Sigma agent in a custom chat interface in your own application or call an agent from a script or an automated pipeline.

The API runs the agent with the calling user’s permissions and row-level security, using the same instructions, data sources, and tools configured for the agent in the workbook.

User requirements

To call an agent using the API, you must have the following:

• Client credentials with the REST API scope
• The client credentials must be assigned to a user with at least Can view access to the workbook containing the agent that you want to run.

Limitations

• You cannot interact with a warehouse agent using this API endpoint. Instead, use the API endpoints associated with your data platform.
• Some action tools do not run when called programmatically. For a list of action tools that run when called by an agent run programmatically, see About automated action sequences.
• Only one system message can be specified per conversation.

What you can do with the agent API

The agent API is a stateless, chat-completion-style endpoint. With it, you can do any of the following:

• Send a full conversation and get the agent’s next reply, including any text, tool calls, and tool results.
• Continue a multi-turn conversation by replaying the previous output as part of the next request’s messages.
• Retrieve the agent response as a structured JSON schema, instead of free-form text.
• Limit a run with a maximum number of tool-calling steps (maxTurns) or a maximum number of output tokens (maxOutputTokens).
• Run the agent against a tagged version of the workbook, instead of the latest published version.
• Attach caller-defined metadata to a run, which is logged to the ai_usage table (if configured) in your data platform for tracking and auditing.
• Stream the agent’s reply as a sequence of events instead of waiting for the full turn to complete.

Decide whether to retrieve a streaming response

By default, the agent API returns a single JSON response after the agent finishes its turn. Set stream to true in the request to instead receive a sequence of events as the agent works.

Decide which response type fits your use case by reviewing the following table:

Get started calling an agent with the API

To get started calling an agent with the API:

1. Identify the agents that you have access to. You can call the List agents endpoint to retrieve the list of all agents that you can access in your Sigma organization, including the workbookId and agentId of each agent.

2. Decide whether to modify the default request with optional details, such as:

   • Send your user prompt as a message with "role": "user" in the messages list.
   • Determine whether your use case needs a streaming or non-streaming response.
   • Determine whether you want to receive a response as text or structured JSON.
   • Specify arbitrary metadata to be logged to the AI_USAGE table.
   • Include previous conversation output as context in the messages list. See Continue a conversation.

Run an agent

To run an agent, send a POST request to the Run a Sigma agent endpoint.

• Include the workbookId and agentId for the agent.
• Specify relevant content in the request.
• If you want to add system-level context to the agent instructions, such as “never tell the user what source you are querying”, include that as a system message.
• Store the returned runId alongside your own logs so you can correlate a run with a support request if needed.

curl -X POST https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "messages": [
    {
      "content": "Summarize this month'\''s sales trends.",
      "role": "user"
    }
  ]
}'

The response includes the agent’s reply in output, along with usage details about the run, such as the number of turns and tokens consumed.

Continue a conversation

Chat history is not currently stored for agents, so to continue a conversation with an agent, provide the context about the current conversation when making a request to run the agent.

To continue a conversation, append the previous response’s output to the messages array and send the full history again on the next call:

curl -X POST https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "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"
    }
  ]
}'

Retrieve structured output

If you want to structure the output returned by the agent, you can specify a desired JSON output structure when you make a request:

curl -X POST https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "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"
  }
}'

That request returns a response like the following:

{
  "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
}

Related resources

• About Sigma agents (Beta)
• Build Sigma agents (Beta)
• Chat with Sigma agents (Beta)
• Generate API client credentials