Should I build an agent or a workflow?
Ask who is driving. If a person is talking to it and the next move depends on the reply, build an agent. If it is a job with a start and an end that has to finish whatever happens, build a workflow.
An agent is open-ended. You declare it with defineDeepAgent(...): a name, a
model and the tools it can call. You write its instruction in Studio rather than
in the file, and the runtime reads it when it builds the agent. The model
decides which tool to call from the name, description and schema you gave each
one. The agent keeps the thread across turns, and the runtime serves it over the
standard chat endpoints.
A workflow is fixed and auditable: validate, call a model, write a side effect.
Each 'use step' runs once, persists its result, and retries on failure. The
run survives crashes and redeploys and can pause for months waiting on a sleep
or a human decision.
You can mix the two. A workflow step can hand a turn to an agent with
callDeepAgent(name, input). Use it when a pipeline needs one piece of
judgement in the middle. One rule applies to both: touch stackbone.* only
inside a step, never in the workflow body.
Read more
- Agents: the authoring model and the tools an agent calls.
- Workflows:
'use workflow','use step'and what replay means for your code. - Workflow + Agents: delegating a turn to an agent from inside a step.