What Is an AI Agent API? A Developer's Guide
A developer-focused explanation of AI agent APIs — how they differ from LLM APIs, how the async job pattern works, and when to use one.
AI agent APIs are a layer above language model APIs. Instead of getting raw text from a language model and parsing it yourself, you call a pre-built agent that accepts structured input, does the AI work internally, and returns typed JSON.
The difference is the same as using a library function vs. writing the underlying code yourself.
LLM API vs Agent API
When you call an LLM API directly, you're responsible for:
- Writing and maintaining the prompt
- Parsing unstructured text output
- Handling model failures and retries
- Choosing the right model
- Versioning your prompt as models change
When you call an agent API:
- The prompt is the agent builder's problem
- Output is typed JSON you consume directly
- Model selection is handled internally
- You call once and get a result
The Call Pattern
All Runcept agents use the same two-step async pattern.
Step 1 — Start the job:
curl -X POST https://www.runcept.com/api/v1/run \
-H "Authorization: Bearer runcept_sk_..." \
-H "Content-Type: application/json" \
-d '{"agent": "code-reviewer", "input": {"diff": "..."}}'
# → {"job_id": "job_abc123", "status": "queued"}
Step 2 — Poll for result:
curl https://www.runcept.com/api/v1/jobs/job_abc123 \
-H "Authorization: Bearer runcept_sk_..."
# → {"status": "complete", "output": {"score": 82, "issues": [...]}}
The two-step approach is necessary because AI calls take 5-60 seconds — too long for a synchronous HTTP response.
What Agent APIs Are Good For
Automating repetitive AI tasks in CI/CD: Code review, PR descriptions, commit messages — all callable from GitHub Actions without a chat UI.
Integrating AI into existing code: Drop a single function call into your pipeline. No prompt management, no model selection.
Consistent structured output: You get the same JSON shape every time, not unpredictable text you need to parse differently each run.
Predictable billing: Pay per run, not per token. Know the cost before you call.
What They're Not Good For
Agent APIs are not the right choice when:
- You need custom behavior specific to your codebase
- You're building an interactive chat experience
- You need a model with specific capabilities no existing agent has
- You're experimenting and iterating on prompts
In those cases, call the LLM API directly and build your own agent.
The Marketplace Layer
Runcept adds a marketplace on top: builders publish agents with pricing, consumers discover and run them. This means the agent landscape grows over time as developers publish new agents — similar to how npm grows.
Getting Started
The fastest way to understand agent APIs is to run one. Runcept's echo agent is free and shows the full request/response cycle. From there, browse the marketplace for agents that match your use case.