generate() & stream()
These two functions are the primitive. Agent is built on stream() and adds conversation management on top — so when you don't want a conversation, drop to this layer directly. Batch jobs, stateless request handlers, evaluation harnesses, or your own conversation container.
Because there's no conversation here, there are no turns. These functions deal in messages and steps, and stream() emits StreamEvent rather than the TurnEvents you'd get from Agent.
generate() | stream() | |
|---|---|---|
| Returns | Promise<GenerateResult> (exactly stream().final) | A handle with .on() and .final |
| Events | None | StreamEvent |
| Cancellable | Via signal | Via signal or handle.cancel() |
Both run the complete tool loop. Neither keeps any history — you pass messages in and get messages back.
generate()
import { generate } from "@fifthrevision/axle";
const result = await generate({
provider,
model,
messages: [{ role: "user", content: "What's the weather in Lisbon?" }],
tools: [getWeather],
});
if (!result.ok) throw new Error(result.error.message);
result.response; // the final AxleAssistantMessage
result.messages; // everything produced this runWatch out for one difference from Agent: response is the whole assistant message, not a string. Reach into content for the parts you want. It's deliberate — at this level you usually want more than the text.
stream()
import { stream } from "@fifthrevision/axle";
const handle = stream({ provider, model, messages, tools: [getWeather] });
handle.on((event) => {
if (event.type === "text:delta") process.stdout.write(event.delta);
});
const result = await handle.final;You don't have to hurry to register callbacks — processing starts on the next microtask, so anything registered synchronously after the call sees every event.
handle.cancel(reason) aborts, and handle.final then rejects with AxleAbortError carrying reason, usage, messages, and partial (partial is undefined when the cancel landed before anything was written).
Passing an Instruct
Both take an Instruct in place of a final user message, which is how you get structured output without an agent:
const result = await generate({
provider,
model,
messages: previousMessages, // prior context — optional
instruct: new Instruct({
prompt: "Answer {{question}}.",
schema: z.object({ answer: z.string() }),
}).withInput("question", "Should we proceed?"),
});
if (result.ok) result.response.answer; // typedWhen you give both messages and instruct, messages is treated as prior context and the rendered Instruct is appended as the new user message. With instruct, response becomes the parsed value rather than a message.
Tools
Supply tools inline:
stream({ provider, model, messages, tools: [a], providerTools: [b] });tools takes executable and deferred tools side by side (AnyTool). The loop builds every request from the values it was given. (registry was removed in 0.34.0 — the loop never reads one, so a tool added to a ToolRegistry after the call no longer appears mid-loop. To change tools or the prompt mid-loop, return them from onToolBatchComplete, below. See Upgrading.)
When the model requests several tool calls in one message, they all start at once — the step's tool phase takes as long as its longest call, and results answer in request order. tool:exec-start fires for every call up front and completions interleave in finish order, so key on id. A fatal tool error or a cancelled run aborts the batch's other calls through ctx.signal.
There's also onToolCall, which answers the deferred tools in tools — definitions with no execute that the caller resolves:
stream({
provider,
model,
messages,
tools: [a, askUser],
onToolCall: (call) => {
if (!isCall(askUser, call)) return; // this branch answers nothing: the call waits
return prompt(call.input.question);
},
});The handler receives one call ({ id, name, input }, input already validated) plus the tool context, and returns what an execute would — or throws to hand the model an error. It never sees executable tools; those always run through their own execute. A call the handler doesn't answer waits instead of failing: answer it from outside through the handle while it waits, or bound the wait with the tool's timeout:
const handle = stream({ provider, model, messages, tools: [askUser] });
handle.on((event) => {
if (event.type === "tool:waiting") showPrompt(event.id, event.input);
});
handle.toolCall(id)?.answer("teal");generate() has no handle, so nothing outside its handler can answer. It keeps failing fast: a call the handler doesn't answer, or any call when there's no handler, is an execution error result at once. See Tools.
Bounding the loop
const result = await generate({ provider, model, messages, tools, maxSteps: 8 });
const result2 = await generate({ provider, model, messages, tools, maxContextTokens: 100_000 });maxSteps caps model requests. maxContextTokens caps the context budget, checked after each step's tools are answered against that step's reported usage.
Crossing either one is a stop, not an error — you get ok: true with stopped: "max-steps" | "token-limit" and everything accumulated so far. The conversation is well-formed and continuable, and it's your call whether to compact and carry on. Non-positive limits throw at call time.
streamStallMs is the other bound: the longest gap in milliseconds between two chunks from the provider on one step's stream, the wait for the first included. When it passes, the request aborts and the run ends ok: false with an api / StreamStall failure. It is not retried, and it is unset by default — reach for it when a hung socket is worse than a failed run.
See Results & errors.
Steering the loop yourself
handle.onToolBatchComplete((message) => (done ? "finish" : "continue"));This runs after each tool batch settles. "finish" ends the run without another provider request — every tool in that batch has already completed and committed, so nothing is lost. It's the primitive behind agent.stop().
It can also steer the loop: return { system?, tools?, providerTools? } (typed as ToolBatchDecision) and the loop continues with those inputs replacing the current ones, exactly as the initial call set them. That's how the Agent keeps skill and registry changes live mid-turn — the same mechanism is available to you when you drive stream() directly.
One step at a time
stream() with maxSteps: 1 performs exactly one provider request and reads final — the bottom of the stack for when you're building your own orchestration and want Axle purely for provider normalization. (The standalone generateStep() was removed in 0.32.0 when generate() was unified onto the streaming transport.)
When to use Agent instead
Use Agent when you want history management, a FIFO queue, turn events, session snapshots, compaction, or lazy MCP resolution. That's a fair amount of machinery to rebuild, and Agent is essentially stream() plus exactly those things.
Next
- Stream events — what
stream()emits, in full - generate() & stream() reference