Execute Endpoint

Execute an agent and receive a non-streaming JSON response.

Endpoint Overview

The Execute Endpoint allows applications, websites, backend services, and workflows to invoke an agent and receive a single JSON response.

Use this endpoint when you need a simple request/response integration without streaming. Unlike the Chat Endpoint, responses are returned as a single JSON payload containing the generated output and usage information.

Use the Execute Endpoint when:

• You want a simple request/response integration.
• You do not need real-time token streaming.
• You are generating content from prompt templates and variables.
• You are calling agents from forms, backend services, scheduled jobs, or workflows.
• You need a JSON response that can be easily consumed programmatically.

Use the Chat Endpoint instead when building streaming conversational experiences.

Authentication

Requests can be authenticated using a user session token, an agent key, or an organization API key.

Authorization: Bearer <supabase_jwt>

x-agent-key: agk_xxxxxxxxxxxxxxxxxxxxxxxxx

cf-api-key: cf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Optional Headers

Use the x-agent-payload header to pass additional metadata to downstream MCP integrations.

x-agent-payload: {"x-user-id":"123","x-tenant-id":"acme"}

• Must contain valid JSON.
• Only string, number, and boolean values are preserved.
• Unsafe headers such as authorization, host, and content-length are automatically removed before forwarding.

Request Body

The Execute Endpoint accepts a lightweight JSON payload.

Request Fields

How Message Works

The message field provides a one-off user instruction for the agent.

{
  "message": "Write a short summary of this product launch"
}

If you send message, the server converts it into a single user message internally before running the agent.

If you omit message, the server still executes the agent using the rendered system prompt and the supplied vars.

That makes /execute especially useful for prompt-template style use cases, where variables are enough and no chat transcript is needed.

Template-Driven Execution

For many use cases, you do not need to provide a message.

If your agent already contains a prompt template that expects variables, you can execute the agent using only vars.

{
  "vars": {
    "title": "AI in logistics",
    "tone": "professional",
    "keywords": "automation, supply chain, forecasting"
  }
}

Integration Examples

const agentId = "YOUR_AGENT_ID";
 
const response = await fetch(`/api/agents/${agentId}/execute`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-agent-key": "YOUR_AGENT_KEY",
},
body: JSON.stringify({
message: "Write a product announcement email",
vars: {
productName: "Chocolate Factory AI",
audience: "existing customers",
tone: "friendly",
},
}),
});
 
if (!response.ok) {
const errorBody = await response.text();
throw new Error(`Execute request failed: ${response.status} ${errorBody}`);
}
 
const data = await response.json();
 
console.log(data.text);
console.log(data.usage);
console.log(data.finishReason);

const response = await fetch(
`/api/agents/${agentId}/execute`,
{
    method: "POST",
    headers: {
    "Content-Type": "application/json",
    "x-agent-key": "YOUR_AGENT_KEY",
},
    body: JSON.stringify({
    vars: {
    title: "AI in logistics",
    tone: "professional",
    keywords: "automation, supply chain, forecasting",
},
}),
}
);
 
const data = await response.json();
console.log(data.text);

curl -X POST "https://yourdomain.com/api/agents/YOUR_AGENT_ID/execute" \
-H "Content-Type: application/json" \
-H "x-agent-key: YOUR_AGENT_KEY" \
-d '{
"message": "Create a short sales pitch",
"vars": {
"productName": "Chocolate Factory AI",
"market": "retail",
"tone": "confident"
}
}'

Success Responses

Successful requests return HTTP 200 with a JSON response.

• Return HTTP 200
• Execute the agent synchronously
• Return a single JSON payload
• Include generated output in text
• Include token usage statistics
• Include a generation finish reason

Response Fields

Response Example

{
  "text": "Generated output from the agent",
  "usage": {
    "inputTokens": 123,
    "outputTokens": 456,
    "totalTokens": 579
  },
  "finishReason": "stop"
}

Error Responses

Best Practices

• Use the Execute Endpoint for forms, content generation, workflows, bots, and backend jobs.
• Use the Chat Endpoint for streaming conversations and interactive chat experiences.
• Use vars when your agent prompt is template-driven.
• Use message when you need to provide a direct user instruction.
• Prefer x-agent-key for external integrations.
• Leverage template-driven execution when user input is unnecessary.
• Inspect the usage object to monitor token consumption.