Skip to main content
POST
/
agents
/
{agentId}
/
start
Start Agent
curl --request POST \
  --url https://api.example.com/agents/{agentId}/start \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "enableAutonomy": true,
  "settings": {}
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "data.agentId": "<string>",
    "data.status": "<string>",
    "data.startedAt": 123,
    "data.enableAutonomy": true
  }
}

Endpoint

POST /agents/{agentId}/start
Starts an agent’s runtime, enabling it to process messages, execute actions, and interact with users. An agent must be started before it can respond to messages.

Request

Path Parameters

agentId
string
required
Unique identifier (UUID) of the agent to start

Headers

Content-Type
string
required
Must be application/json
Authorization
string
Bearer token for authentication (if required)

Body Parameters (Optional)

enableAutonomy
boolean
default:"false"
Enable autonomous mode where the agent can initiate conversations
settings
object
Runtime-specific settings to override agent configuration

Response

success
boolean
required
Indicates if the agent started successfully
message
string
Status message
data
object
required
Agent runtime details
data.agentId
string
required
Unique identifier for the agent
data.status
string
required
New status: active
data.startedAt
number
Unix timestamp when the agent was started
data.enableAutonomy
boolean
Whether autonomy is enabled

Examples

Basic Start

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Content-Type: application/json" \
  -d '{}'

Start with Autonomy

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "enableAutonomy": true
  }'

Start with Custom Settings

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "temperature": 0.8,
      "maxTokens": 2000
    }
  }'

Response Example

Success Response

{
  "success": true,
  "message": "Agent started successfully",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "startedAt": 1709683200000,
    "enableAutonomy": false
  }
}

Code Examples

JavaScript/Node.js

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(
  `http://localhost:3000/agents/${agentId}/start`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      enableAutonomy: false
    })
  }
);

const { success, message, data } = await response.json();

if (success) {
  console.log(message);
  console.log(`Agent status: ${data.status}`);
}

Python

import requests

agent_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.post(
    f'http://localhost:3000/agents/{agent_id}/start',
    json={'enableAutonomy': False}
)

data = response.json()

if data['success']:
    print(data['message'])
    print(f"Agent status: {data['data']['status']}")

TypeScript

interface StartAgentRequest {
  enableAutonomy?: boolean;
  settings?: Record<string, any>;
}

interface StartAgentResponse {
  success: boolean;
  message: string;
  data: {
    agentId: string;
    status: 'active';
    startedAt: number;
    enableAutonomy?: boolean;
  };
}

const agentId = "550e8400-e29b-41d4-a716-446655440000";

const request: StartAgentRequest = {
  enableAutonomy: false
};

const response = await fetch(
  `http://localhost:3000/agents/${agentId}/start`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  }
);

const result: StartAgentResponse = await response.json();

Error Responses

404 Not Found

{
  "success": false,
  "error": "Agent not found"
}

409 Conflict

{
  "success": false,
  "error": "Agent is already running"
}

400 Bad Request

{
  "success": false,
  "error": "Invalid agent ID format"
}

500 Internal Server Error

{
  "success": false,
  "error": "Failed to start agent runtime"
}

Autonomy Mode

When autonomy is enabled, the agent can:
  • Initiate conversations proactively
  • Respond to scheduled triggers
  • Monitor channels for relevant topics
  • Execute background tasks
Autonomy mode requires additional configuration in your agent’s character settings. See the autonomy documentation for more details.

Startup Process

When an agent starts, the following happens:
  1. Initialize Runtime - Create the agent runtime environment
  2. Load Configuration - Load character settings and plugins
  3. Connect Services - Initialize database and external service connections
  4. Register Actions - Register available actions and providers
  5. Start Listening - Begin processing incoming messages

Health Checks

After starting an agent, verify it’s running correctly:
curl http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000
Check that the status field is active.

Next Steps

Send Message

Start chatting with your agent

Stop Agent

Stop the agent when done

Get Agent

Check agent status and details

Build docs developers (and LLMs) love