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

# Executar Agente

> Executar um agente específico por ID.

### **Exemplos de Código**

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

  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",
        "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
  ```
</CodeGroup>

### **Cabeçalhos**

<ParamField header="x-workspace-id" type="integer" required>
  ID do workspace. **Obrigatório a partir de 01/09/2026.** Até lá, se omitido, usa o workspace selecionado do usuário (deprecated). Após a data, ausência → **422**.
</ParamField>

### **Parâmetros de Caminho**

| **Parâmetro** | **Tipo** | **Obrigatório** | **Descrição**   |
| :------------ | :------- | :-------------- | :-------------- |
| `id`          | integer  | Sim             | O ID do agente. |

### **Corpo da Requisição**

| **Parâmetro**         | **Tipo** | **Obrigatório**   | **Descrição**                                                                                                                                                                                                                                      |
| :-------------------- | :------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `temperature`         | string   | Não               | Campo de Chat Agent. Temperatura de amostragem entre 0 e 2. Valores maiores geram resultados mais criativos (padrão: `"1"`).                                                                                                                       |
| `model`               | string   | Não               | Campo de Chat Agent. Identificador do modelo a ser utilizado (ex.: `"tess-6"`).                                                                                                                                                                    |
| `tools`               | string   | Não               | Campo de Chat Agent. Configuração de ferramentas do agente (ex.: `"agent"`, `"no-tools"`).                                                                                                                                                         |
| `root_id`             | integer  | Não               | Campo de Chat Agent. ID de uma execução existente para continuar um thread de conversa.                                                                                                                                                            |
| `messages`            | array    | Não               | Campo de Chat Agent. As mensagens do agente. Suporta os papéis `user`, `assistant` e `developer`.                                                                                                                                                  |
| `waitExecution`       | boolean  | Não               | Se `true`, aguarda a execução terminar antes de retornar (timeout: 100 s). Padrão: `false`.                                                                                                                                                        |
| `file_ids`            | array    | Não               | Array de IDs de arquivo para anexar à execução.                                                                                                                                                                                                    |
| `memory_collections`  | array    | Não               | Array de IDs de [Coleções de Memória](https://docs.tess.im/pt-BR/list-collections) a serem usadas nesta execução. As memórias indexadas nessas coleções serão automaticamente recuperadas e injetadas no contexto do agente via busca semântica.   |
| Outros campos na raiz | any      | Depende do agente | Isto não é um nome de campo fixo. Você pode enviar outros campos exigidos pelo seu agente diretamente na raiz da requisição. Consulte quais campos são obrigatórios em [Obter Agente por ID](https://docs.tess.im/pt-BR/api/endpoints/agents/get). |

<Info>
  **Como usar memórias numa execução**

  Para injetar contexto de memória num agente, passe os IDs das Coleções de Memória no campo `memory_collections`. O fluxo completo é:

  1. **Criar uma Coleção** — `POST /api/memory-collections` — e anote o `id` retornado.
  2. **Criar Memórias** — `POST /api/memories` — passando `collection_id` e o texto da memória no campo `memory`.
  3. **Executar o Agente** — inclua `"memory_collections": [id_da_colecao]` no corpo da requisição.

  O agente usará automaticamente as memórias relevantes para contextualizar a resposta.

  Veja o guia completo em [Memórias](https://docs.tess.im/pt-BR/memories).
</Info>

#### **Funções das Mensagens (Modelos do Tipo Chat)**

Para modelos do tipo chat, o array `messages` suporta as seguintes funções:

| **Função**  | **Obrigatório** | **Descrição**                                                                               |
| :---------- | :-------------- | :------------------------------------------------------------------------------------------ |
| `user`      | Sim             | Mensagens do usuário. Devem ser emparelhadas com mensagens `assistant`.                     |
| `assistant` | Sim             | Mensagens do assistente. Devem ser emparelhadas com mensagens `user`.                       |
| `developer` | Não             | Mensagem opcional do desenvolvedor. **Permitida apenas como a primeira mensagem** no array. |
| `system`    | Não             | **Não suportado**. Usar esta função causará um erro.                                        |

**Regras importantes:**

* As mensagens devem alternar entre as funções `user` e `assistant` (após a mensagem opcional `developer`).
* A função `developer` só pode aparecer como a primeira mensagem no array e será extraída antes do processamento do restante.
* Se duas mensagens consecutivas tiverem a mesma função (por exemplo, duas mensagens `user`), a API retornará um erro de validação: "Chat messages must be a pair of user/assistant".
* A função `system` não é suportada e causará um erro.

**Exemplo com mensagem developer:**

```json theme={null}
{
  "messages": [
    { "role": "developer", "content": "Você é um assistente prestativo." },
    { "role": "user", "content": "Olá!" },
    { "role": "assistant", "content": "Oi! Como posso ajudá-lo?" },
    { "role": "user", "content": "Como está o tempo?" }
  ]
}
```

**Exemplo sem mensagem developer:**

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "Olá!" },
    { "role": "assistant", "content": "Oi! Como posso ajudá-lo?" },
    { "role": "user", "content": "Como está o tempo?" }
  ]
}
```

Obter mais detalhes sobre quais opções são aceitas por este Agente solicitando este endpoint: [Obter Agente](https://docs.tess.im/pt-BR/api/endpoints/agents/get)

### **Resposta**

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

````