Skip to main content
POST /agents/{id}/execute Execute a specific agent by ID.

​
Code Examples

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",
    "wait_execution": false,
    "file_ids": [123, 321]
  }'

​
Headers

ParameterTypeRequiredDescription
x-workspace-idintegerNoID of the workspace. If not provided, the user’s selected workspace will be used.
Note: This field will be required in a future release of the API. It is highly recommended to set it now to ensure compatibility with future updates.

​
Path Parameters

ParameterTypeRequiredDescription
idintegerYesThe agent ID

​
Request Body

ParameterTypeRequiredDescription
answersobjectYesThe agent answers
messagesarrayOnly for Chat AgentThe agent messages
wait_executionbooleanNoIndicates whether the execution should wait until completion. The timeout is 100 seconds. For longer executions, use wait_execution=false in combination with the Get Agent Response endpoint with a polling strategy (default: false).
file_idsarrayNoArray of file IDs to attach to the execution.

​
Messages Roles (Chat Type Templates)

For chat type templates, the messages array supports the following roles:
RoleRequiredDescription
userYesUser messages. Must be paired with assistant messages.
assistantYesAssistant messages. Must be paired with user messages.
developerNoOptional developer message. Only allowed as the first message in the array.
systemNoNot 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
  }
]
}