Agent Endpoints

Agent Endpoints let you deploy AI agents as REST APIs. Each endpoint gets a unique URL, an API key, and runs an agentic loop powered by any LLM provider — with full access to your MCP workspace tools.

Think of it as “deploy an AI function as an API.” You define a system prompt, pick a model, connect a workspace, and get a callable URL. Consumers send input, the agent reasons, calls tools if needed, and returns structured output.

How It Works

You call POST /api/run/:slug with your input
    → Agent loads tools from your MCP workspace
    → LLM reasons, calls tools if needed
    → Returns structured output

Each execution is logged with token counts, cost, latency, and tool call history — all viewable in the dashboard.

Key Concepts

System Prompt

The system prompt defines your agent’s behavior. It tells the LLM who it is, what it should do, and how to format its response. This is the core of your agent — everything else is configuration around it.

MCP Workspace

Every agent endpoint connects to an MCP workspace. The workspace provides the tools the agent can use during execution. If your workspace has a GitHub MCP server connected, the agent can read repos, create issues, and open PRs. If it has a database MCP server, the agent can query and write data.

Output Formats

Agents can return output in three formats:

Format	Description
`text`	Plain text (default). The LLM responds naturally.
`json`	Structured JSON. Optionally validated against a schema you define.
`markdown`	Formatted markdown text.

Auth Modes

Mode	Description
`api_key`	Default. Consumers must pass an API key via `Authorization: Bearer <key>` or `X-API-Key` header.
`public`	No authentication. Anyone can call the endpoint. Additional per-IP rate limiting (20 req/min) applies.

Use Cases

Data Extraction — Parse invoices, receipts, or documents. Send raw text, get structured JSON with extracted fields. Connect a storage MCP server to save results automatically.

Content Generation — Generate blog posts, product descriptions, or email drafts. The agent uses your brand guidelines from the system prompt and can pull context from connected data sources via MCP tools.

Code Review — Point the agent at a GitHub workspace. Send a PR number, and the agent reads the diff, analyzes the code, and returns structured feedback with severity levels.

Customer Classification — Route support tickets by sending the ticket text to an agent that classifies urgency, topic, and suggested department. Use JSON output format to get machine-readable results.

Data Enrichment — Send a company name, get back enriched data. The agent uses web search MCP tools to find company info, then returns structured results.

LLM Providers

Agent Endpoints support any of these providers:

Provider	Example Models
`openai`	`gpt-4o`, `gpt-4o-mini`
`anthropic`	`claude-sonnet-4-20250514`, `claude-3-5-haiku-20241022`
`gemini`	`gemini-2.0-flash`, `gemini-1.5-pro`
`groq`	`llama-3.3-70b-versatile`, `mixtral-8x7b-32768`
`workers-ai`	`@cf/meta/llama-3-8b-instruct`

Rate Limits

Scope	Limit	Window
Per endpoint (all callers)	60 requests	1 minute
Per IP (public mode only)	20 requests	1 minute
Admin test runs	10 requests	1 minute

Quick Example

# Call an agent endpoint
curl -X POST https://api.aerostack.dev/api/run/summarizer \
  -H "Authorization: Bearer aek_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input": "Summarize this article: Aerostack is a headless backend platform..."}'

{
  "output": "Aerostack is a headless backend platform for developers...",
  "usage": {
    "tokens_input": 245,
    "tokens_output": 89,
    "cost_cents": 0.12,
    "latency_ms": 1823,
    "iterations": 1
  }
}

Next Steps

Quick Start — Create your first agent endpoint in 3 minutes
SSE Streaming — Stream agent responses in real time
Output Formats — Text, JSON, and Markdown output
Pricing — Per-run billing and cost breakdown
API Reference — Full endpoint documentation