Skip to main content
POST
/
agents
/
{agentId}
/
stop
Stop Agent
curl --request POST \
  --url https://api.example.com/agents/{agentId}/stop \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "graceful": true,
  "timeout": 123
}
'
{
  "success": true,
  "message": "<string>",
  "data": {
    "data.agentId": "<string>",
    "data.status": "<string>",
    "data.stoppedAt": 123
  }
}

Endpoint

POST /agents/{agentId}/stop
Stops an agent’s runtime, preventing it from processing new messages. The agent’s configuration and data are preserved and can be restarted later.

Request

Path Parameters

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

Headers

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

Body Parameters (Optional)

graceful
boolean
default:"true"
Whether to wait for in-progress messages to complete
timeout
number
default:"30000"
Maximum time in milliseconds to wait for graceful shutdown

Response

success
boolean
required
Indicates if the agent stopped successfully
message
string
Status message
data
object
required
Agent stop details
data.agentId
string
required
Unique identifier for the agent
data.status
string
required
New status: inactive
data.stoppedAt
number
Unix timestamp when the agent was stopped

Examples

Basic Stop

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

Graceful Stop

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

Force Stop

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

Response Example

Success Response

{
  "success": true,
  "message": "Agent stopped successfully",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "inactive",
    "stoppedAt": 1709683200000
  }
}

Code Examples

JavaScript/Node.js

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

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

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}/stop',
    json={'graceful': True, 'timeout': 30000}
)

data = response.json()

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

TypeScript

interface StopAgentRequest {
  graceful?: boolean;
  timeout?: number;
}

interface StopAgentResponse {
  success: boolean;
  message: string;
  data: {
    agentId: string;
    status: 'inactive';
    stoppedAt: number;
  };
}

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

const request: StopAgentRequest = {
  graceful: true,
  timeout: 30000
};

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

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

Error Responses

404 Not Found

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

409 Conflict

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

408 Request Timeout

{
  "success": false,
  "error": "Graceful shutdown timed out"
}

500 Internal Server Error

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

Graceful vs Force Stop

A graceful stop:
  • Waits for in-progress messages to complete
  • Allows actions to finish executing
  • Saves state before shutting down
  • Closes connections cleanly
await fetch(`http://localhost:3000/agents/${agentId}/stop`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ graceful: true, timeout: 60000 })
});

Force Stop

A force stop:
  • Immediately terminates the agent runtime
  • May interrupt in-progress operations
  • Use only when graceful stop fails
await fetch(`http://localhost:3000/agents/${agentId}/stop`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ graceful: false })
});

Shutdown Process

When an agent stops gracefully:
  1. Stop Accepting Messages - New messages are rejected
  2. Complete In-Progress - Wait for current operations to finish
  3. Save State - Persist any pending data
  4. Close Connections - Disconnect from services
  5. Mark Inactive - Update agent status to inactive

Use Cases

Maintenance Window

Stop agents during maintenance:
// Stop all agents
const agents = await fetch('http://localhost:3000/agents').then(r => r.json());

for (const agent of agents.data) {
  if (agent.status === 'active') {
    await fetch(`http://localhost:3000/agents/${agent.agentId}/stop`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ graceful: true })
    });
  }
}

Resource Management

Stop idle agents to free resources:
const stopIdleAgents = async () => {
  const agents = await getActiveAgents();
  
  for (const agent of agents) {
    const lastActivity = await getLastActivityTime(agent.agentId);
    const idleTime = Date.now() - lastActivity;
    
    if (idleTime > 3600000) { // 1 hour
      await stopAgent(agent.agentId);
    }
  }
};

Next Steps

Start Agent

Restart the agent when ready

Get Agent

Check agent status

Update Agent

Modify configuration while stopped

Delete Agent

Permanently remove the agent

Build docs developers (and LLMs) love