PrepareStep: Trim Message History

Demonstrate ToolLoopAgent prepareStep for trimming long message history. Pre-seeded 24-message conversation shows context compression on the first run with per-step trim telemetry.

Loading preview…

Problems solved

Technical challenges this implementation handles out of the box.

Trim long message histories before each agent step
Keep recent tool results while dropping stale turns
Observe prepareStep compression with per-step telemetry
Prevent unbounded context growth in ToolLoopAgent loops

Use cases

Products and workflows this pattern is designed to support.

Long-running agents with many tool calls
Context-window budget management
Debugging what the model sees each step
Production agents that must cap history size

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

ToolLoopAgentprepareStepstepCountIstoolgateway

Providers

OpenAI

Files added

11 files

app/page.tsx
app/layout.tsx
app/api/trim/route.ts
components/trim-demo.tsx
components/trim-timeline.tsx
components/seed-preview.tsx
lib/trim-config.ts
lib/seed-conversation.ts
lib/trim-agent.ts
tools/append-note.ts
README.md

Dependencies

14 total

npm packages

AISDKlucide-reactNext.jsReactZod

Registry components

alertbadgebuttoncardcollapsiblelabelscroll-areaskeletonswitch

Critical files

lib/trim-agent.ts
ToolLoopAgent with prepareStep that returns messages.slice(-KEEP_RECENT) when over MAX_MESSAGES. Logs trim events per step in a collector array.
lib/seed-conversation.ts
Static 24-message ModelMessage[] fixture so the demo shows trimming immediately without user-built history.
trim/route.ts
Runs agent.generate({ messages: [...seeded, finalUser] }) and returns trimEvents, hero metrics, and optional compare run without trim.
tools/append-note.ts
Single demo tool for the agent to call once before summarizing.