Canopy

Connect Vercel AI SDK

The Vercel AI SDK (v3+) accepts tools as an object keyed by name with description, parameters, and execute. canopy.vercel.tools() returns exactly that. Vercel runs the dispatch loop itself, so no dispatch() helper is needed.

Fast path: after Step 1, run npx @canopy-ai/sdk connect in your project root. It opens a consent page in your browser, then writes credentials to ~/.config/canopy/credentials and merges a canopy MCP server entry into any installed Claude Code, Cursor, Claude Desktop, Windsurf, Cline, VS Code, or Zed. Skip Steps 2 and 4 below.

Step 1 — Connect your agent in the dashboard

Canopy is bring-your-own-agent. This step doesn't create the agent itself — you've already built that, or are about to. It registers a Canopy-side record that pairs your agent with a spending policy and gives you an agt_… ID to use in your code.

Sign in at trycanopy.ai and go to Agents → Connect agent. Give the agent a name and pick (or create) a policy. The policy controls the spend cap, recipient allowlist, and approval threshold every payment from this agent will be evaluated against.

Step 2 — Copy your credentials

You need two values in your code:

  • Org API key (ak_live_… or ak_test_…) — from Settings → API Keys. Copy it the moment you create it; the plaintext is shown only once.
  • Agent ID (agt_…) — from the agent's detail page in /dashboard/agents.

Step 3 — Install the package

npm install @canopy-ai/sdk ai @ai-sdk/openai

Step 4 — Set your environment variables

CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx
CANOPY_AGENT_ID=agt_xxxxxxxx

Use a .env file locally and your platform's secret manager in production. Never commit credentials.

Step 5 — Connect in your agent code

Paste the snippet below into your existing Vercel AI agent.

// 1. Add to your .env:
// CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx

// 2. In your agent code:
import { Canopy } from '@canopy-ai/sdk';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const canopy = new Canopy({
  apiKey: process.env.CANOPY_API_KEY,
  agentId: 'agt_xxxxxxxx',
});

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: canopy.vercel.tools(),
  prompt: 'Send 10 cents to 0x1234...',
});

Step 6 — Verify the connection

Run your agent once. As soon as Canopy receives a request from it, the dashboard flips the agent to connected and shows the first event captured. If nothing happens after a minute, see Troubleshooting.

Notes

  • canopy.vercel.tools() returns the five canonical tools: canopy_pay, canopy_check_url, canopy_discover_services, canopy_approve, canopy_deny.
  • To narrow the set, filter the result before passing to generateText: Object.fromEntries(Object.entries(canopy.vercel.tools()).filter(([name]) => name === "canopy_pay")).
  • The vercel namespace is a method on the core Canopy class — no additional imports or peer deps required.

Where to go next