Reusable application agent
Build a reusable assistant with stable model instructions and a shared tool set.
AI Tools · Class
Experimental_Agent
Experimental_Agent is a reusable AI SDK class that combines a model, instructions, tools, and loop control. It can generate text, stream output, or produce an API response while managing agent steps.
How it works
Experimental_Agent packages a model, instructions, tools, and loop behavior into a reusable agent. Calling generate runs the agent and returns generated output; configure stopWhen when the agent must continue through multiple tool calls.
Syntax
new Experimental_Agent({ model, system, tools, stopWhen })Parameters
| Name | Type | Description |
|---|---|---|
model | LanguageModel | Language model used for generation and tool decisions. |
system | string | Instructions that define the agent's behavior. |
tools | Record<string, Tool> | Tools available to the model during agent execution. |
stopWhen | StopCondition | Condition controlling when the agent loop stops. |
Returns
An agent instance whose generate, stream, and respond methods execute the configured agent loop.
Key points
- Use the class to define an agent once and reuse its model, tools, and behavior across an application.
- The class orchestrates repeated model and tool steps rather than requiring manual loop management.
- Agent execution includes conversation context handling and a configurable completion condition.
- Each iteration produces text or requests a tool execution, after which the loop can continue.
- Call generate when the application needs a single completed result instead of a streamed response.
- Call stream to deliver output incrementally while the agent runs.
Common mistakes
- The default permits only one step, so configure stopWhen explicitly for multi-step tool workflows.
- Choose the Agent class for managed loops; use core generation functions when each step requires application-controlled orchestration.
Example: Create and run an agent
import { Experimental_Agent as Agent, stepCountIs } from 'ai';
const agent = new Agent({
model: 'openai/gpt-4o',
system: 'You are a helpful assistant.',
tools: {},
stopWhen: stepCountIs(5),
});
const result = await agent.generate({
prompt: 'Explain tool calling briefly.',
});
console.log(result.text);Creates an agent with model instructions and tools, permits several loop steps, then generates a response.
When to use it
Multi-step tool workflows
Let a model complete tasks that require several sequential tool calls.
Streaming agent responses
Deliver incremental model output to an interactive client.
Interview questions
QWhat problem does Experimental_Agent solve?
Experimental_Agent is a reusable class that combines model configuration, tools, and agent behavior. It manages the loop, context management, and stopping conditions while the model decides whether to generate text or call a tool.
Follow-up: When would you avoid it? Use generateText or streamText when the workflow requires explicit control over each step.
QHow is an Experimental_Agent used?
Instantiate the class with a model and optional system instructions and tools. Then call generate for one-time generation, stream for streaming, or respond to create an API response for a client application.
Follow-up: How do you enable multiple tool calls? Set stopWhen to a condition that allows more than one step.
QWhat is the default stopping behavior?
The default stopping condition is stepCountIs(1), so the agent stops after its first model or tool step. Configure stopWhen, such as stepCountIs(5), when a task needs sequential tool use.
Follow-up: What is the trade-off? A higher limit enables longer workflows but can increase execution time and resource use.
Related
stepCountIsgeneratestreamrespondtoolgenerateTextstreamText