Agent Loops - Chatbot Platform Documentation

Agent Loops are autonomous AI workflows that can execute multi-step tasks, access tools via MCP (Model Context Protocol) servers, and operate without direct user interaction.

Overview

An Agent Loop is an AI agent that:

Runs Autonomously: Executes tasks without user messages
Uses Tools: Accesses MCP servers for capabilities like file systems, databases, APIs
Makes Decisions: Determines which tools to use and when
Sends Results: Delivers output via callback webhooks
Iterates: Can run multiple reasoning steps to complete tasks

Unlike bots (which respond to user messages), Agent Loops are proactive and task-oriented.

Use Cases

Scheduled Reports

Generate and send daily/weekly reports automatically

Data Processing

Process files, databases, or API data on schedule

Monitoring

Check systems and alert on issues

Content Generation

Create blog posts, summaries, or documentation

Agent Loop Components

System Prompt

Instructions that define the agent’s behavior:

You are a data analyst. Every day at 9 AM, you:
Fetch yesterday's sales data from the database
Calculate key metrics (total sales, top products)
Generate a summary report
Send the report via webhook

User Message

The task or question given to the agent:

Generate today's sales report and send it to the team.

MCP Servers

Tools the agent can use:

File System: Read/write files
Database: Query SQL databases
HTTP: Make API requests
Custom: Your own tool implementations

MCP server configured — MCP server configuration

Callback Webhook

Where to send results when the agent completes its task:

Callback configured — Callback webhook setup

Creating an Agent Loop

Navigate to Agent Loops

From your dashboard, click Agent Loops in the sidebar.

Click Create

Click Create Agent Loop to open the form.

Name Your Agent

Give it a descriptive name:

Write System Prompt

Define the agent’s role and behavior.

Set User Message

Provide the task or question.

Configure MCP Servers

Add any tools the agent needs (optional but recommended).

Add Callback Webhook

Specify where to send results (optional).

Configure Advanced Settings

Set model, max iterations, timeout, etc.

Save

Click Create to save the agent loop.

Running Agent Loops

Manual Execution

Run an agent loop on demand:

Open Agent Loop

Navigate to the agent loop details page.

Click Run

Click the Run button to start execution.

Monitor Progress

Watch the execution log for status updates.

Review Results

Check the output and any callback webhook responses.

Scheduled Execution (Coming Soon)

Future support for:

Cron-based schedules (daily, weekly, monthly)
Interval-based triggers (every N minutes/hours)
Event-based triggers (webhook received, file uploaded)

API Execution

Trigger agent loops via API:

curl -X POST https://api.chatbotplatform.io/v1/agent-loops/{id}/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

See API Reference for details.

MCP Servers

Model Context Protocol (MCP) servers provide tools for agents:

Built-in MCP Servers

File System:

Read files
Write files
List directories

HTTP Client:

Make GET/POST/PUT/DELETE requests
Handle authentication
Parse responses

Database (Coming Soon):

Query SQL databases
Execute statements
Transaction support

Custom MCP Servers

Deploy your own MCP servers:

Implement MCP Protocol

Follow the MCP specification to create a tool server.

Deploy Server

Host your MCP server at a public endpoint.

Add to Agent Loop

Configure the MCP server URL in your agent loop settings.

Test

Run the agent and verify tool calls work correctly.

Learn more in MCP Servers.

Callback Webhooks

Send agent results to external systems:

Webhook Format

The callback webhook receives:

{
  "agent_loop_id": "loop_abc123",
  "execution_id": "exec_xyz789",
  "status": "completed",
  "result": {
    "output": "The agent's final response",
    "tool_calls": 5,
    "iterations": 3
  },
  "metadata": {
    "started_at": "2024-01-15T10:00:00Z",
    "completed_at": "2024-01-15T10:02:30Z",
    "duration_seconds": 150
  }
}

Response Expected

Your webhook should return:

{
  "received": true
}

HTTP 200 status indicates success. Learn more in Callbacks.

Advanced Settings

Max Iterations

Limit how many reasoning steps the agent can take:

Iterations	Use Case
5	Simple tasks
10 (default)	Standard tasks
20	Complex multi-step tasks
50+	Very complex workflows

More iterations = longer execution time.

Timeout

Maximum execution time in seconds:

60s: Quick tasks
300s (5 min): Standard
900s (15 min): Long-running tasks
3600s (1 hour): Maximum

Agent stops if timeout is reached.

Best Practices

Clear Instructions

Write explicit system prompts and tasks

Right Tools

Provide only necessary MCP servers

Set Limits

Use appropriate iteration and timeout limits

Test First

Run manually before scheduling

System Prompt Tips

Good:

You are a sales analyst. Your task is to:
Query the database for yesterday's orders
Calculate total revenue and average order value
Identify top 5 products by sales
Format the results as a JSON report
Send the report via the callback webhook

Bad:

Analyze sales data.

Be specific about steps, data sources, and expected output.

Troubleshooting

Agent Doesn’t Complete

Check:

Max iterations is sufficient
Timeout is long enough
MCP servers are accessible
System prompt is clear

Tool Calls Fail

Check:

MCP server URLs are correct
Authentication is configured
Server is running and responsive
Agent has permission to access tools

No Callback Received

Check:

Callback URL is correct
Webhook endpoint is accessible
Agent loop completed successfully
Check execution logs for errors

API Access

Manage agent loops programmatically using the API.

Create an agent loop via API

cURL
JavaScript
PHP
Python

curl -X POST https://api.chatbotplatform.io/v1/agent-loops \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Sales Report",
    "system_prompt": "You generate daily sales reports.",
    "user_message": "Generate today\u0027s sales report.",
    "mcp_servers": ["filesystem", "http"],
    "callback_url": "https://your-app.com/webhook",
    "max_iterations": 10,
    "timeout": 300
  }'

const response = await fetch('https://api.chatbotplatform.io/v1/agent-loops', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Daily Sales Report',
    system_prompt: 'You generate daily sales reports.',
    user_message: 'Generate today\'s sales report.',
    mcp_servers: ['filesystem', 'http'],
    callback_url: 'https://your-app.com/webhook',
    max_iterations: 10,
    timeout: 300
  })
});
const data = await response.json();

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.chatbotplatform.io/v1/agent-loops', [
        'name' => 'Daily Sales Report',
        'system_prompt' => 'You generate daily sales reports.',
        'user_message' => 'Generate today\'s sales report.',
        'mcp_servers' => ['filesystem', 'http'],
        'callback_url' => 'https://your-app.com/webhook',
        'max_iterations' => 10,
        'timeout' => 300
    ]);

$agentLoop = $response->json();

response = requests.post(
    'https://api.chatbotplatform.io/v1/agent-loops',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'name': 'Daily Sales Report',
        'system_prompt': 'You generate daily sales reports.',
        'user_message': 'Generate today\'s sales report.',
        'mcp_servers': ['filesystem', 'http'],
        'callback_url': 'https://your-app.com/webhook',
        'max_iterations': 10,
        'timeout': 300
    }
)
agent_loop = response.json()

Run an agent loop

cURL
JavaScript
PHP
Python

curl -X POST https://api.chatbotplatform.io/v1/agent-loops/loop_123/run \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.chatbotplatform.io/v1/agent-loops/loop_123/run', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const execution = await response.json();

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.chatbotplatform.io/v1/agent-loops/loop_123/run');

$execution = $response->json();

response = requests.post(
    'https://api.chatbotplatform.io/v1/agent-loops/loop_123/run',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
execution = response.json()

List agent loop executions

cURL
JavaScript
PHP
Python

curl https://api.chatbotplatform.io/v1/agent-loops/loop_123/executions \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.chatbotplatform.io/v1/agent-loops/loop_123/executions', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const { data } = await response.json();

$response = Http::withToken('YOUR_API_KEY')
    ->get('https://api.chatbotplatform.io/v1/agent-loops/loop_123/executions');

$executions = $response->json('data');

response = requests.get(
    'https://api.chatbotplatform.io/v1/agent-loops/loop_123/executions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
executions = response.json()['data']

Complete API Reference

View the full API specification with all endpoints, parameters, and response schemas.

Next Steps

Getting Started

Create your first agent loop

MCP Servers

Configure tool access

Callbacks

Set up result webhooks

​Overview

​Use Cases

Scheduled Reports

Data Processing

Monitoring

Content Generation

​Agent Loop Components

​System Prompt

​User Message

​MCP Servers

​Callback Webhook

​Creating an Agent Loop

​Running Agent Loops

​Manual Execution

​Scheduled Execution (Coming Soon)

​API Execution

​MCP Servers

​Built-in MCP Servers

​Custom MCP Servers

​Callback Webhooks

​Webhook Format

​Response Expected

​Advanced Settings

​Max Iterations

​Timeout

​Best Practices

Clear Instructions

Right Tools

Set Limits

Test First

​System Prompt Tips

​Troubleshooting

​Agent Doesn’t Complete

​Tool Calls Fail

​No Callback Received

​API Access

Complete API Reference

​Next Steps

Getting Started

MCP Servers

Callbacks

Overview

Use Cases

Agent Loop Components

System Prompt

User Message

MCP Servers

Callback Webhook

Creating an Agent Loop

Running Agent Loops

Manual Execution

Scheduled Execution (Coming Soon)

API Execution

MCP Servers

Built-in MCP Servers

Custom MCP Servers

Callback Webhooks

Webhook Format

Response Expected

Advanced Settings

Max Iterations

Timeout

Best Practices

System Prompt Tips

Troubleshooting

Agent Doesn’t Complete

Tool Calls Fail

No Callback Received

API Access

Next Steps