Pular para o conteúdo principal
POST
/
agents
/
{id}
/
execute
curl --request POST \
  --url https://api.tess.im/agents/{id}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "temperature": "1",
  "model": "tess-6",
  "messages": [
    {
      "role": "user",
      "content": "Summarize the latest ticket updates."
    }
  ],
  "tools": "no-tools",
  "waitExecution": false,
  "file_ids": [
    123,
    321
  ]
}
'

Exemplos de Código

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],
    "memory_collections": [456]
  }'
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',
    'Content-Type': 'application/json'
  },
  data: data
};

try {
  const response = await axios(config);
  console.log(response.data);
} catch (error) {
  console.error(error);
}
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],
    "memory_collections": [456]
  }

response = requests.post(url, headers=headers, json=data)
print(response.json())
<?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",
    "Content-Type: application/json"
  ]
]);

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

curl_close($curl);

if ($err) {
  echo "Error: " . $err;
} else {
  echo $response;
}
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("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
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("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))
}
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 },
                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);
            }
        }
    }
}
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],
    "memory_collections": [456]
}.to_json

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

Cabeçalhos

ParâmetroTipoObrigatórioDescrição
x-workspace-idintegerNãoID do workspace. Se não fornecido, o workspace selecionado pelo usuário será usado. Será obrigatório em uma versão futura.

Parâmetros de Caminho

ParâmetroTipoObrigatórioDescrição
idintegerSimO ID do agente.

Corpo da Requisição

ParâmetroTipoObrigatórioDescrição
temperaturestringNãoCampo de Chat Agent. Temperatura de amostragem entre 0 e 2. Valores maiores geram resultados mais criativos (padrão: "1").
modelstringNãoCampo de Chat Agent. Identificador do modelo a ser utilizado (ex.: "tess-6").
toolsstringNãoCampo de Chat Agent. Configuração de ferramentas do agente (ex.: "agent", "no-tools").
root_idintegerNãoCampo de Chat Agent. ID de uma execução existente para continuar um thread de conversa.
messagesarrayNãoCampo de Chat Agent. As mensagens do agente. Suporta os papéis user, assistant e developer.
waitExecutionbooleanNãoSe true, aguarda a execução terminar antes de retornar (timeout: 100 s). Padrão: false.
file_idsarrayNãoArray de IDs de arquivo para anexar à execução.
memory_collectionsarrayNãoArray de IDs de Coleções de Memória 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 raizanyDepende do agenteIsto 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.
Como usar memórias numa execuçãoPara 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çãoPOST /api/memory-collections — e anote o id retornado.
  2. Criar MemóriasPOST /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.

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

Para modelos do tipo chat, o array messages suporta as seguintes funções:
FunçãoObrigatórioDescrição
userSimMensagens do usuário. Devem ser emparelhadas com mensagens assistant.
assistantSimMensagens do assistente. Devem ser emparelhadas com mensagens user.
developerNãoMensagem opcional do desenvolvedor. Permitida apenas como a primeira mensagem no array.
systemNãoNã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:
{
  "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:
{
  "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

Resposta

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

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cabeçalhos

x-workspace-id
integer

ID of the workspace. If not provided, the user's selected workspace will be used. This field will be required in a future release.

Parâmetros de caminho

id
integer
obrigatório

The agent ID.

Corpo

application/json

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

Free-form JSON object. Send known fields and any custom agent fields directly at the root level.

Resposta

200

Execution started (or completed if waitExecution: true).