Loading pattern preview
TemplatesAgent Patterns
Structured Agent Output: Output.array
Structured Agent Output: Output.array
Demonstrate structured agent outputs using ToolLoopAgent with Output.array. Returns structured array output with element schema for predictable, type-safe responses.
Loading pattern preview
Problems solved
Technical challenges this implementation handles out of the box.
- Return structured arrays from ToolLoopAgent with Output.array
- Validate each array element against a Zod object schema
- Combine list-shaped outputs with tool-calling agents
Use cases
Products and workflows this pattern is designed to support.
- Multi-location aggregation agents
- Checklist generators with typed items
- Batch recommendation responses
- API agents that must return object lists
Setup
Requirements, wiring steps, and what this pattern adds to your project.
Getting started
Pick how you want to pull this pattern in. Then wire env vars and routes the same way.
- 1
Download → Next.js app
Use Download → Next.js app in the preview toolbar. You get a zip scaffold (Pro downloads rewrite preview `/view/.../api/*` paths to `/api/*` automatically).
- 2
Extract the zip and install dependencies
Unzip the archive, then run `pnpm install` (or npm / yarn) in the project folder.
- 3
Fill .env.local
The download includes .env.local placeholders when needed. Add real values for: OPENAI_API_KEY.
- 4
Customize the agent and tool files
Adapt prompts, tools, and stop conditions in the generated project for your product.
- 5
Run the app and open the pattern route
Run `pnpm dev`, open the setup/checklist page if present, then navigate to the generated pattern route and verify responses.
Environment variables
OPENAI_API_KEYGet key
Capabilities
AI SDK APIs
ToolLoopAgentOutput.arrayagent.generatetoolProviders
OpenAI
Files added
7 filesapp/page.tsxapp/layout.tsxapp/api/array/route.tscomponents/structured-array-demo.tsxcomponents/output-display.tsxlib/array-agent.tstools/weather.ts
Dependencies
10 totalnpm packages
5AISDKlucide-reactNext.jsReactZod
Registry components
alertbadgebuttoncardcollapsible
Critical files
lib/array-agent.tsCore agent definition using ToolLoopAgent with Output.array() and a z.object element schema for structured array output.
tools/weather.tsTool definition providing weather data that the array agent collects across multiple locations.
array/route.tsAPI route showing ToolLoopAgent.generate() for non-streaming structured array output.
Requirements
- Complexity
- Intermediate
- Setup time
- ~5 minutes
- Node
- 24+
- Memory
- 512MB
