Introduction
Run an Agent through the public API — a single LLM configuration with tools, knowledge, and skills.
An Agent is the base unit you build on in Elizon: one LLM configuration — model, instructions, memory, tools, knowledge, skills — that you run directly with a prompt and get a reply back. Where a Team composes several Agents under a lead and a coordination mode, and a Workflow chains steps (Agents among them) into a graph, an Agent is the single call with nothing in front of it.
How this fits together
- Creating and configuring an Agent — its model, instructions, memory, tools, knowledge, and skills — is covered in the API Reference's Agents group (list, create, get, update), or in the Studio Agent Builder.
- Running an Agent — sending it a prompt and getting a response back — is the public API
surface covered in this section:
/run,/run-stream,/run-async, and/jobs.
What this section does not cover
Creating, updating, or deleting an Agent, or configuring its model, instructions, memory, tools, knowledge, or skills. Those are the Agents CRUD endpoints or the Studio Agent Builder — not part of this section.
Reasoning and tools
An Agent's Reasoning setting is Off, Scratchpad, or Native. Some OpenAI models reason by default, even with Reasoning set to Off, and they refuse tools (skills, Knowledge Bases, Tools) unless they are told not to reason. Elizon handles both cases for you:
- Off or Scratchpad, with tools: if the model refuses, the run is retried once without reasoning. Elizon remembers this for that model, so later runs send the setting from the start and the extra round trip happens once (the memory is cleared when the AI service restarts). If the model refuses again, the run fails with the provider's message.
- Native, with tools, on OpenAI: the run uses OpenAI's Responses API, which accepts a reasoning effort and tools together. Without tools, or on any other provider (Azure OpenAI and OpenAI-compatible providers included), nothing changes.
With /run-stream, the first refused run is not retried. It ends with
an error event that carries the provider's message, and later runs of that model succeed.
Where to go next
- Run (synchronous) —
POST /api/v1/agents/{agentId}/run, plus cancelling a run. - Run (streaming) —
POST /api/v1/agents/{agentId}/run-stream. - Run (async) —
POST /api/v1/agents/{agentId}/run-async. - Jobs — poll and cancel an async run.
New to the API entirely? Start with the Quickstart — it walks through creating an API key, listing your Agents, and running one, end to end.