How to Add AI Agents to Your App with an Agent API

If you're building a product, you don't want to reinvent the agent runtime — you want to call one. An agent API lets you embed a preconfigured AI agent into your app with a single HTTP request. Here's the clean way to do it.

What is an agent API?

An agent API sends a user message to a preconfigured agent and returns its response over HTTP. The key difference from a raw model API: the agent already carries its instructions, tools, and knowledge, so you get goal-directed behavior — not just a text completion — from one call. You manage the conversation; the platform manages the agent.

Step 1: Create a scoped API key

Generate an API key tied to a specific agent, with explicit permissions (read/write) and rate limits. Scoped keys are the safety boundary: if one leaks, its blast radius is limited to one agent at a capped rate. In SaintSal you do this in the Agent Hub under API Keys.

Keep keys server-side. Never embed an agent API key in client-side JavaScript or a mobile app bundle.

Step 2: Send a request

Authenticate with the key as a Bearer token and post the user's message:

curl https://api.example.com/v1/chat \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize this lead", "stream": true }'

Pass prior turns as a messages array to maintain conversation context.

Step 3: Stream the response

For chat-style UX, stream tokens as they're generated using Server-Sent Events so users see output immediately:

const res = await fetch(url, { method: 'POST', headers, body });
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split('\n')) {
    if (line.startsWith('data: ')) {
      const evt = JSON.parse(line.slice(6));
      if (evt.type === 'chunk') append(evt.content);
    }
  }
}

Step 4: Handle limits and cost

Production integrations must respect limits. Set per-key rate limits (minute / hour / day), and handle 429 (rate limited) and 402 (out of credits) by backing off and surfacing a clear message. Meter usage so one integration can't run up unbounded cost — track tokens and task time per key.

A clean integration pattern

• Server-side proxy: your backend holds the key and calls the agent API; your client calls your backend. Keys never reach the browser.
• Idempotency + retries: retry transient failures with backoff; make writes idempotent.
• Observability: log per-request tokens, latency, and outcome so you can tune prompts and catch regressions.

Ship it

Create an agent, mint a scoped key, and make your first streamed call. Start in the Agent Hub, read the API guide, and check pricing for usage tiers.