PatternsSDK API

HIL Needs Approval

Loading pattern preview

Loading preview…

Problems solved

Technical challenges this implementation handles out of the box.
  • Pause Experimental_Agent tool calls until the user approves
  • Handle approval denial gracefully in agent instructions
  • Visualize pending and completed tool execution states
  • Stream approval UI updates during the agent loop

Use cases

Products and workflows this pattern is designed to support.
  • Sensitive tool actions that need sign-off
  • Admin agents gating writes and deletes
  • Customer-support agents requiring human approval
  • Educational demos of needsApproval agent flows

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. 1

    Install from the preview toolbar

    Shadcn Icon

    Copy the install command above and run it in your project — Pro patterns include a short-lived token.

  2. 2

    Add environment variables to .env.local

    GOOGLE_AI_API_KEY

  3. 3

    Point client fetches at your API routes

    Replace preview `/view/.../api/...` paths with `/api/...` in the installed files.

  4. 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. 5

    Run your dev server and open the pattern route

    Install dependencies if needed, then start the app and verify responses.

Environment variables

Capabilities

AI SDK APIs

AgenttoolstepCountIsExperimental_AgentgatewayUIToolInvocation

Providers

Gemini

External services

Upstash

Files added

11 files
  • app/page.tsx
  • app/layout.tsx
  • app/api/tool-approval/route.ts
  • lib/tool-approval-agent.ts
  • lib/tool-approval-types.ts
  • lib/tools/weather-tool.ts
  • lib/tools/schema.ts
  • components/tool-approval-chat.tsx
  • components/tool-views/weather-with-approval-view.tsx
  • README.md
  • AGENT_FLOW.md

Dependencies

8 total

npm packages

6
AISDKlucide-reactNext.jsReactsonnerZod

Shadcn IconRegistry components

2
buttonempty

Critical files

  • lib/tool-approval-agent.ts

    Agent definition using Experimental_Agent with tool approval pattern. Configures instructions to handle approval denial gracefully.

  • tools/weather-tool.ts

    Weather tool with needsApproval: true — the key pattern for human-in-the-loop tool approval. Uses generator pattern with yield for loading/ready states.

Requirements

Complexity
Intermediate
Setup time
~15 minutes
Node
24+
Memory
512MB
Upstash Redis