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

<CodeGroup>
  ```http cURL theme={null}
  curl --request POST \
    --url 'https://api.tess.im/agents/{id}/execute' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --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]
    }'
  ```

  ```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]
    };

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

  try {
    const response = await axios(config);
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
  ```

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

  url = "https://api.tess.im/agents/{id}/execute"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "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]
    }

  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]
  ];

  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",
      "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)
          );

          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("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]
      }`

      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("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");

              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 }
              };

              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['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]
  }.to_json

  response = http.request(request)
  puts response.read_body
  ```
</CodeGroup>

### **Headers**

| **Parameter**    | **Type** | **Required** | **Description**                                                                                                         |
| :--------------- | :------- | :----------- | :---------------------------------------------------------------------------------------------------------------------- |
| `x-workspace-id` | integer  | No           | ID of the workspace. If not provided, the user's selected workspace will be used. Will be required in a future release. |

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

#### **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)

### **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: false
      schema:
        type: integer
      description: >-
        ID of the workspace. If not provided, the user's selected workspace will
        be used. **This field will be required in a future release.**
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````