Agents
An agent is one LLM worker definition: a single set of instructions, tools and model configuration. That is the whole of it. An agent is not a container for other agents, and it is not a small process flow — see process flows for the thing that is.
What an agent is made of
Three parts, and they are worth separating because they change at different rates.
The instructions say what the agent is for and how it should behave. The tools say what it may do — which Wexa tools it can call, and which skills it has. The model says which LLM it runs on, either one the platform provides or one you bring.
Changing the model is not changing the agent's purpose, and changing the instructions is not changing what it is permitted to do. Keeping the three separate is what makes an agent reviewable.
Those three appear in an agent's definition as named fields: a prompt template carrying the
instructions, a skills list holding real skill ids the agent has been granted, and an llm block
whose model names the LLM. llm.model defaults to the sentinel system_model, meaning whichever
model the organization has chosen rather than a particular one.
Two further settings belong to the definition rather than to any single run. An agent that does work can be set to pause and wait for a person before it proceeds. Any agent can be set to receive a summary of the agents that ran before it, and told which of them — off unless you turn it on.
What running one does
Running an agent starts a real, side-effecting run. It is asynchronous: the call returns an
execution_id and finishes, rather than waiting for the agent to be done. You read the outcome by
polling that execution — see
executions and versioning.
A run carries a goal in natural language, which is the request for that turn. It may also carry
input variables and file ids to put in front of the agent, and the id of an agent to start from. A
stable session_id reused across several calls makes them one conversation: the agent recalls the
earlier turns, and the runs are grouped together instead of appearing as unrelated one-shot runs.
What a run does not carry is which project, organization or person it belongs to. Those are filled in from the credential you authenticated with, and supplying them yourself is refused — see scope and server-bound arguments.
A run is a governed call like any other. Policy can refuse it, and that refusal is an answer the call gives you rather than a silent no-op. See policy decisions and approvals.
Agent or process flow
Use this rule.
- One agent when the work is one worker's job: one set of instructions, one role, one model, however many steps it takes internally to get there.
- A process flow when the work needs more than one worker — when two parts of it want different instructions, different skills, or a decision that routes between them.
The rule is about the shape of the work, not its size. A long, elaborate single-role task is still one agent. Two short tasks that need different instructions are already a process flow.
Where to go next
- Skills, actions and triggers — how an agent reaches the outside world, and how it starts without a person asking.
- Executions and versioning — reading a run, and shipping a change to an agent safely.
- Models — choosing the LLM, and what that choice costs.
- Tool reference:
run-agent,get-execution,list-skills.