Tool Context: experimental_context

Inject request-scoped context (user identity, database handles, session) into ToolLoopAgent tools via experimental_context, so the model never supplies sensitive identity in tool inputs.

Loading preview…

Problems solved

Technical challenges this implementation handles out of the box.

Keep user identity out of model-controlled tool inputs
Share database or service handles across tools via experimental_context
Scope tool execution to the authenticated request
Reduce prompt-injection risk around cross-user data access

Use cases

Products and workflows this pattern is designed to support.

Per-user account assistants
Multi-tenant agent tools
Injecting DB or session into isolated tool calls
Identity-scoped agent backends

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

ToolLoopAgentexperimental_contexttoolstepCountIsgateway

Providers

OpenAI

Files added

11 files

app/page.tsx
app/layout.tsx
app/api/context/route.ts
components/context-demo.tsx
components/tool-call-trace.tsx
lib/context-agent.ts
lib/request-context.ts
lib/demo-users.ts
tools/get-orders.ts
tools/get-profile.ts
README.md

Dependencies

13 total

npm packages

AISDKlucide-reactNext.jsReactZod

Registry components

alertbadgebuttoncardcollapsibleinputskeletontabs

Critical files

tools/get-orders.ts
Core pattern: tool whose inputSchema omits userId; execute reads identity and db from the second arg's experimental_context, casting to a RequestContext type.
context/route.ts
Resolves identity server-side and passes it to agent.generate({ prompt, experimental_context }). Returns tool calls and results for inspection.
lib/request-context.ts
Defines the RequestContext type (userId, user, db) and a fake database. Replace with your real session + data layer.