Execute Agent

Code Examples

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]
  }'

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

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

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

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

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

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

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

How to use memories in an executionTo inject memory context into an agent, pass Memory Collection IDs in the memory_collections field. The full flow is:

Create a Collection — POST /api/memory-collections — and save the returned id.
Create Memories — POST /api/memories — passing collection_id and the memory text in the memory field.
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.

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:

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

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

Response

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

Authorizations

Authorization

string

header

required

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

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

integer

required

The agent ID.

Body

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.

Response

200

Execution started (or completed if waitExecution: true).

API Guide

API Reference

Integrations

Model Context Protocol (MCP)

Code Examples

Headers

Path Parameters

Request Body

Messages Roles (Chat Type Templates)

Response

Authorizations

Headers

Path Parameters

Body

Response

​Code Examples

​Headers

​Path Parameters

​Request Body

​Messages Roles (Chat Type Templates)

​Response

Authorizations

Headers

Path Parameters

Body

Response

Code Examples

Headers

Path Parameters

Request Body

Messages Roles (Chat Type Templates)

Response