> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tess.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Agent

> Execute a specific agent by ID.

### **Code Examples**

```http cURL theme={null}
curl --request POST \
  --url 'https://api.tess.im/agents/{id}/execute' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": false,
    "file_ids": [123, 321],
    "memory_collections": [456]
  }'
```

```json Node.js theme={null}
const axios = require('axios');

const data = {
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": false,
    "file_ids": [123, 321],
    "memory_collections": [456]
  };

const config = {
  method: 'post',
  url: 'https://api.tess.im/agents/{id}/execute',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
      'x-workspace-id': 'YOUR_WORKSPACE_ID',
    'Content-Type': 'application/json'
  },
  data: data
};

const response = await axios(config);
console.log(response.data);
```

```python Python theme={null}
import requests
import json

url = "https://api.tess.im/agents/{id}/execute"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
      "x-workspace-id": "YOUR_WORKSPACE_ID",
    "Content-Type": "application/json"
}
data = {
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": False,
    "file_ids": [123, 321],
    "memory_collections": [456]
  }

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

```php PHP theme={null}
<?php
$curl = curl_init();

$data = [
    "temperature" => "1",
    "model" => "tess-5",
    "messages" => [
        [ "role" => "user", "content" => "Hello, how can you help me today?" ]
    ],
    "tools" => "no-tools",
    "waitExecution" => false,
    "file_ids" => [123, 321],
    "memory_collections" => [456]
];

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/agents/{id}/execute",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($data),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
      "x-workspace-id: YOUR_WORKSPACE_ID",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "Error: " . $err;
} else {
  echo $response;
}
```

```java Java theme={null}
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();

        Map<String, Object> data = Map.of(
            "temperature", "1",
            "model", "tess-5",
            "messages", List.of(Map.of("role", "user", "content", "Hello, how can you help me today?")),
            "tools", "no-tools",
            "waitExecution", false,
            "file_ids", List.of(123, 321),
            "memory_collections", List.of(456)
        );

        String jsonPayload = mapper.writeValueAsString(data);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tess.im/agents/{id}/execute"))
            .header("Authorization", "Bearer YOUR_API_KEY")
      .header("x-workspace-id", "YOUR_WORKSPACE_ID")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```go Go theme={null}
package main

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

func main() {
    payload := `{
        "temperature": "1",
        "model": "tess-5",
        "messages": [
            { "role": "user", "content": "Hello, how can you help me today?" }
        ],
        "tools": "no-tools",
        "waitExecution": false,
        "file_ids": [123, 321],
        "memory_collections": [456]
    }`

    client := &http.Client{}
    req, err := http.NewRequest("POST", "https://api.tess.im/agents/{id}/execute", strings.NewReader(payload))
    if err != nil {
        fmt.Println(err)
        return
    }
    
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("x-workspace-id", "YOUR_WORKSPACE_ID")
    req.Header.Add("Content-Type", "application/json")
    
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }
    
    fmt.Println(string(body))
}
```

```jsonnet .NET theme={null}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

class Program
{
    static async Task Main(string[] args)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");
            client.DefaultRequestHeaders.Add("x-workspace-id", "YOUR_WORKSPACE_ID");

            var data = new
            {
                temperature = "1",
                model = "tess-5",
                messages = new List<object> { new { role = "user", content = "Hello, how can you help me today?" } },
                tools = "no-tools",
                waitExecution = false,
                file_ids = new List<int> { 123, 321 },
                memory_collections = new List<int> { 456 }
            };

            var jsonPayload = JsonConvert.SerializeObject(data);
            var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

            try
            {
                var response = await client.PostAsync("https://api.tess.im/agents/{id}/execute", content);
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException e)
            {
                Console.WriteLine("\nException Caught!");
                Console.WriteLine("Message :{0} ", e.Message);
            }
        }
    }
}
```

```ruby Ruby theme={null}
require 'uri'
require 'net/http'
require 'json'

uri = URI('https://api.tess.im/agents/{id}/execute')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['x-workspace-id'] = 'YOUR_WORKSPACE_ID'
request['Content-Type'] = 'application/json'
request.body = {
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": false,
    "file_ids": [123, 321],
    "memory_collections": [456]
}.to_json

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

### **Headers**

**x-workspace-id** `integer` *required*

Workspace ID. **Required as of 2026-09-01.** Until then, if omitted, the user's selected workspace is used (deprecated). After the cutoff, a missing header returns **422**.

### **Path Parameters**

| **Parameter** | **Type** | **Required** | **Description** |
| :- | :- | :- | :- |
| `id` | integer | Yes | The agent ID. |

### **Request Body**

| **Parameter** | **Type** | **Required** | **Description** |
| :- | :- | :- | :- |
| `temperature` | string | No | Chat Agent field. Sampling temperature between 0 and 2. Higher values produce more creative outputs (default: `"1"`). |
| `model` | string | No | Chat Agent field. Model identifier to use for execution (e.g., `"tess-6"`). |
| `tools` | string | No | Chat Agent field. Tool configuration for the agent (e.g., `"agent"`, `"no-tools"`). |
| `root_id` | integer | No | Chat Agent field. ID of an existing execution to continue a conversation thread. |
| `messages` | array | No | Chat Agent field. The agent messages. Required for Chat Agent templates. Supports `user`, `assistant`, `developer` roles. |
| `waitExecution` | boolean | No | If `true`, waits for execution to finish before returning (timeout: 100 s). Default: `false`. |
| `file_ids` | array | No | Array of file IDs to attach to the execution. |
| `memory_collections` | array | No | Array of [Memory Collection](https://docs.tess.im/en/list-collections.md) IDs to use in this execution. Memories indexed in these collections are automatically retrieved and injected into the agent context via semantic search. |
| Other root-level fields | any | Depends on agent | This is not a fixed field name. You can send additional fields required by your specific agent directly at the request root. Check which fields are required in [Get Agent by ID](https://docs.tess.im/en/get-agent.md). |

> [!NOTE]
>
> **How to use memories in an execution**
>
> To inject memory context into an agent, pass Memory Collection IDs in the `memory_collections` field. The full flow is:
>
> 1. **Create a Collection** — `POST /api/memory-collections` — and save the returned `id`.
> 2. **Create Memories** — `POST /api/memories` — passing `collection_id` and the memory text in the `memory` field.
> 3. **Execute the Agent** — include `"memory_collections": [collection_id]` in the request body.
>
> The agent will automatically use the relevant memories to contextualize the response.
>
> See the full guide at [Memories](https://docs.tess.im/en/memories.md).

#### **Messages Roles (Chat Type Templates)**

For chat type templates, the `messages` array supports the following roles:

| **Role** | **Required** | **Description** |
| :- | :- | :- |
| `user` | Yes | User messages. Must be paired with `assistant` messages. |
| `assistant` | Yes | Assistant messages. Must be paired with `user` messages. |
| `developer` | No | Optional developer message. **Only allowed as the first message** in the array. |
| `system` | No | **Not supported**. Using this role will cause an error. |

**Important rules:**

* Messages must alternate between `user` and `assistant` roles (after the optional `developer` message).
* The `developer` role can only appear as the first message in the array and will be extracted before processing the rest.
* If two consecutive messages have the same role (e.g., two `user` messages), the API will return a validation error: "Chat messages must be a pair of user/assistant".
* The `system` role is not supported and will cause an error.

**Example with developer message:**

```json theme={null}
{
  "messages": [
    { "role": "developer", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" },
    { "role": "assistant", "content": "Hi there! How can I help you?" },
    { "role": "user", "content": "What's the weather like?" }
  ]
}
```

**Example without developer message:**

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "Hello!" },
    { "role": "assistant", "content": "Hi there! How can I help you?" },
    { "role": "user", "content": "What's the weather like?" }
  ]
}
```

Get more details of which options are accepted by this Agent requesting this endpoint: [Get Agent](https://docs.tess.im/en/get-agent.md)

### **Response**

```json theme={null}
{
"template_id": "8794",
"responses": [
  {
    "id": 4773337,
    "status": "starting",
    "input": "hello",
    "output": "",
    "credits": 0.000337,
    "root_id": 4773337,
    "created_at": "2025-01-05T19:35:21.000000Z",
    "updated_at": "2025-01-05T19:35:21.000000Z",
    "template_id": 8794
  }
]
}
```


## OpenAPI

````yaml api-reference/agents-execution.openapi.json POST /agents/{id}/execute
openapi: 3.1.0
info:
  title: Tess API - Agent Execution
  version: 1.0.0
servers:
  - url: https://api.tess.im
security: []
paths:
  /agents/{id}/execute:
    post:
      summary: Execute Agent
      description: Execute a specific agent by ID.
      operationId: executeAgent
      parameters:
        - $ref: '#/components/parameters/agentId'
        - $ref: '#/components/parameters/workspaceId'
      requestBody:
        description: >-
          Send a JSON object. Known fields are supported, and you can add custom
          fields directly at the root (for example: `department`,
          `reporting_period`, `include_risks`).
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: >-
                Free-form JSON object. Send known fields and any custom agent
                fields directly at the root level.
            example:
              temperature: '1'
              model: tess-6
              messages:
                - role: user
                  content: Summarize the latest ticket updates.
              tools: no-tools
              waitExecution: false
              file_ids:
                - 123
                - 321
            examples:
              defaultExecution:
                summary: Default execution payload
                value:
                  temperature: '1'
                  model: tess-6
                  messages:
                    - role: user
                      content: Summarize the latest ticket updates.
                  tools: no-tools
                  waitExecution: false
                  file_ids:
                    - 123
                    - 321
              customFieldsAtRoot:
                summary: Execution with custom root-level fields
                value:
                  temperature: '1'
                  messages:
                    - role: user
                      content: Generate a status report.
                  department: finance
                  reporting_period: 2026-Q1
                  include_risks: true
      responses:
        '200':
          description: 'Execution started (or completed if `waitExecution: true`).'
      security:
        - bearerAuth: []
components:
  parameters:
    agentId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: The agent ID.
    workspaceId:
      name: x-workspace-id
      in: header
      required: true
      schema:
        type: integer
      description: >-
        Workspace ID. Required as of 2026-09-01. Until then, if omitted, the
        user's selected workspace is used (deprecated). After the cutoff, a
        missing header returns 422.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.