Structured Agent Output: Output.choice

Demonstrate structured agent outputs using ToolLoopAgent with Output.choice. Constrain agent outputs to predefined choices for predictable, type-safe responses.

Loading preview…

Problems solved

Technical challenges this implementation handles out of the box.

Constrain ToolLoopAgent output to Output.choice options
Return predictable enum-like agent answers
Combine constrained outputs with tool-calling agents

Use cases

Products and workflows this pattern is designed to support.

Recommendation agents with fixed option sets
Triage bots that must pick from known labels
Form-like agent decisions
Guaranteed-format agent API responses

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
Install from the preview toolbar
Copy the install command above and run it in your project — Pro patterns include a short-lived token.
2
Add environment variables to .env.local
OPENAI_API_KEY
3
Point client fetches at your API routes
Replace preview `/view/.../api/...` paths with `/api/...` in the installed files.
4
Customize the agent and tool files
Adapt prompts, tools, and stop conditions for your product — Copy for AI in the toolbar helps seed that work.
5
Run your dev server and open the pattern route
Install dependencies if needed, then start the app and verify responses.

Environment variables

OPENAI_API_KEYGet key

Capabilities

AI SDK APIs

ToolLoopAgentOutput.choiceagent.generatetool

Providers

OpenAI

Files added

7 files

app/page.tsx
app/layout.tsx
app/api/choice/route.ts
components/structured-choice-demo.tsx
components/output-display.tsx
lib/choice-agent.ts
tools/weather.ts

Dependencies

10 total

npm packages

AISDKlucide-reactNext.jsReactZod

Registry components

alertbadgebuttoncardcollapsible

Critical files

lib/choice-agent.ts
Core agent definition using ToolLoopAgent with Output.choice() to constrain LLM output to predefined string options.
tools/weather.ts
Tool definition using ai SDK tool() with zod inputSchema and execute function. Provides the tool the agent calls before producing its constrained choice output.
choice/route.ts
API route showing how to call ToolLoopAgent.generate() for non-streaming structured output and extract the result.