Skip to main content
Run agents on-demand via HTTP webhooks using agentuse serve. Integrate with external services, CI/CD pipelines, or any system that can make HTTP requests.

​
Quick Start

  1. Start the server:
agentuse serve
  1. Trigger an agent via HTTP:
curl -X POST http://127.0.0.1:12233/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "assistant.agentuse"}'

​
API Reference

​
POST /run

Execute an agent and receive the result. Request: 
{
  "agent": "path/to/agent.agentuse",
  "prompt": "Optional additional instructions",
  "model": "anthropic:claude-sonnet-4-5",
  "timeout": 300,
  "maxSteps": 100
}
FieldTypeRequiredDescription
agentstringYesPath to agent file (relative to project root)
promptstringNoAdditional prompt appended to agent instructions
modelstringNoOverride model in agent file
timeoutnumberNoMax execution time in seconds (default: 300)
maxStepsnumberNoMax tool call steps
Response: 
{
  "success": true,
  "result": {
    "text": "Agent response",
    "finishReason": "end-turn",
    "duration": 1234,
    "tokens": { "input": 500, "output": 200 },
    "toolCalls": 3
  }
}
Error Response: 
{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent file not found: my-agent.agentuse"
  }
}
Error CodeHTTP StatusDescription
AGENT_NOT_FOUND404Agent file doesn’t exist
INVALID_PATH400Path outside project root
INVALID_REQUEST400Invalid JSON body
MISSING_FIELD400Required field missing
TIMEOUT504Execution timed out
EXECUTION_ERROR500Runtime error

​
Streaming Response

For real-time output, request NDJSON streaming: 
curl -N -X POST http://127.0.0.1:12233/run \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  -d '{"agent": "analyzer.agentuse"}'
Each line is a JSON event: 
{"type": "text", "text": "Analyzing..."}
{"type": "tool-call", "name": "read_file", "args": {"path": "data.txt"}}
{"type": "tool-result", "name": "read_file", "result": "..."}
{"type": "text", "text": "Complete!"}
{"type": "finish", "finishReason": "end-turn", "duration": 2345}

​
Authentication

When exposing the server externally, authentication is required: 
# Set API key
export AGENTUSE_API_KEY="your-secret-key"

# Start on all interfaces
agentuse serve --host 0.0.0.0
Include the key in requests: 
curl -X POST http://server:12233/run \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "assistant.agentuse"}'
Use --no-auth to bypass authentication (dangerous for production).

​
Exposing Your Local Server

Access from your devices or team only:
brew install tailscale
tailscale up
agentuse serve
Connect via http://<machine-name>:12233 from any device on your tailnet.

​
Integration Examples

​
GitHub Webhook

Create an agent to handle GitHub events: 
---
model: anthropic:claude-sonnet-4-5
description: Process GitHub webhook events
tools:
  bash:
    commands:
      - "gh *"
      - "git *"
---

Process the incoming GitHub event and take appropriate action.
Configure a GitHub webhook to POST to your server: 
URL: https://your-server.com/run
Content-Type: application/json
Body: {"agent": "github-handler.agentuse", "prompt": "<webhook payload>"}

​
Slack Integration

Slack slash commands require a response within 3 seconds and signature verification. Use a workflow tool as middleware: With n8n or Make:
  1. Add Slack trigger node (receives slash commands)
  2. Add HTTP Request node → POST to http://server:12233/run
  3. Return agent response to Slack
With Zapier:
  1. Trigger: Slack → New Slash Command
  2. Action: Webhooks → POST to AgentUse /run
  3. Action: Slack → Send Channel Message with result
Direct Slack integration requires handling the 3-second timeout, form-urlencoded parsing, and request signature verification. Workflow tools handle this automatically.

​
n8n / Make / Zapier

Use HTTP request nodes to trigger agents:
  1. Set URL to http://your-server:12233/run
  2. Method: POST
  3. Headers: Content-Type: application/json
  4. Body:
{
  "agent": "workflow-agent.agentuse",
  "prompt": "{{trigger.data}}"
}

​
Cron Job (External)

Trigger from system cron instead of built-in scheduler: 
# /etc/cron.d/agent-tasks
0 * * * * curl -s -X POST http://127.0.0.1:12233/run \
  -H "Content-Type: application/json" \
  -d '{"agent": "hourly-task.agentuse"}'

​
Server Configuration

See CLI Commands - agentuse serve for all server options including port, host, debug mode, and authentication configuration.

​
Production Deployment

For deploying agentuse serve in production with reverse proxies (nginx), process management (PM2), and Docker, see Self-Hosting.

​
Next Steps

Scheduled Agents

Run agents on a cron schedule

Self-Hosting

Deploy in production