Workflows, agents & steps
Every Apodex response is built from three nested objects. One API request is one workflow, which runs one or more agents, each of which executes steps.
workflowOne API requestholds input, state and outputstatus: in_progressagentresearcherowns one responsibility1…n per workflowsteptool_callruns a web searchcompletedstepmessagestreams tokens via deltain_progressNesting is literal: a step never exists outside an agent, and an agent never outside a workflow.
Workflow
the top-level execution containerA Workflow is the highest-level execution unit in the platform. It represents a complete AI task request from the user, containing all input, output, and execution state. Each Workflow corresponds to one API request and manages the entire lifecycle of an AI task.
| Property | Description |
|---|---|
workflow_id | Unique identifier for tracking and managing the workflow |
status | Execution state — queued, in_progress, completed, failed, cancelled. |
input | Input messages provided by the user (array of message objects) |
agents | List of Agents executed within this workflow |
Agent
autonomous task executorAn Agent is an autonomous AI entity within a Workflow that executes specific tasks. Each Agent has a unique name and role (e.g., 'researcher', 'writer', 'reviewer'). Agents can collaborate and communicate with each other to complete complex multi-step tasks.
| Property | Description |
|---|---|
agent_id | Unique identifier for the agent |
name | Agent name, e.g. main, researcher, analyzer. |
status | Execution state — started, completed, failed. |
steps | List of Steps executed by this agent |
Step
the smallest unit of executionA Step is the smallest unit of execution within an Agent. Each Step represents a specific action, such as generating a text message or calling an external tool. Steps are executed sequentially and can be streamed in real-time to provide incremental updates.
| Property | Description |
|---|---|
step_id | Unique identifier for the step |
type | Step type — message or tool_call. |
status | Execution state — created, in_progress, completed, failed. |
delta | Incremental updates (e.g., new tokens for message steps) |
Step types
| Type | Description |
|---|---|
message | Generates text content with a model, streamed token by token. |
tool_call | Calls an external tool or API — web search, calculator, database query. |
Execution flow
- 01A request arrives and becomes one
workflow, carrying the user's input. - 02The workflow starts and creates a
researcheragent. - 03The agent runs a
tool_callstep — a web search. - 04The agent runs a
messagestep, streaming the summary token by token. - 05The agent completes and the workflow returns its final output.