AI Sdk Plugin Patterns

AI SDK Plugin Patterns

AI SDK plugin patterns using You.com API utilities from @youdotcom-oss/api package.

For end users: See packages/ai-sdk-plugin/README.md
For universal patterns: See .agents/rules/core.md

When to Use

• Contributing to @youdotcom-oss/ai-sdk-plugin package
• Implementing AI SDK tools
• Debugging AI SDK integration

Architecture

AI SDK wraps API utilities as native tools:

@youdotcom-oss/api (Foundation)
├── fetchSearchResults()
├── SearchQuerySchema
├── callResearch()
├── ResearchQuerySchema
├── fetchContents()
└── ContentsQuerySchema
         ↓
@youdotcom-oss/ai-sdk-plugin (AI SDK Wrapper)
├── youSearch()   - Wraps API utility as AI SDK tool
├── youResearch() - Wraps API utility as AI SDK tool
└── youContents() - Wraps API utility as AI SDK tool

Tech Stack

• AI SDK: Vercel AI SDK ^6.0.0
• API Utilities: @youdotcom-oss/api ^0.1.0
• Testing: Bun test

Quick Start

cd packages/ai-sdk-plugin
bun test
bun run check

AI SDK-Specific Patterns

Tool Function Pattern

Each tool wraps API utility:

export const youSearch = (config: YouToolsConfig = {}) => {
  const apiKey = config.apiKey ?? process.env.YDC_API_KEY;

  return tool({
    description: 'Search the web for current information...',
    inputSchema: SearchQuerySchema,  // From API package
    execute: async (params) => {
      if (!apiKey) throw new Error('YDC_API_KEY required');
      
      const response = await fetchSearchResults({ params, YDC_API_KEY: apiKey, getUserAgent });
      
      return {
        text: formatSearchResults(response),  // For AI model
        data: response                         // For inspection
      };
    },
  });
};

Verify: Each tool imports from @youdotcom-oss/api
Fix: Use API package utilities, don't duplicate logic

Tool Descriptions for AI Models

Write for AI decision-making, not humans:

// ✅ Clear, actionable, includes use cases
description: 'Search the web for current information. Use for news, facts, weather, recent events, or any query requiring up-to-date data from the internet.'

// ❌ Too technical
description: 'Executes HTTP GET request to You.com Search API'

// ❌ Too generic
description: 'Web search tool'

Verify: Descriptions mention use cases
Fix: Add when/why to use the tool

API Key Handling

Validate before API calls:

// ✅ Check API key in execute
execute: async (params) => {
  if (!apiKey) {
    throw new Error('YDC_API_KEY is required');
  }
  const response = await fetchSearchResults(...);
}

// ❌ Don't skip validation
execute: async (params) => {
  const response = await fetchSearchResults(...);  // May fail unclearly
}

Verify: All tools check apiKey before calls
Fix: Add API key validation

Response Format

Always return text and data:

// ✅ Both formats
return {
  text: formatSearchResults(response),  // Human-readable
  data: response                         // Structured
};

// ❌ Only text
return formatSearchResults(response);

// ❌ Only data
return response;

Verify: All tools return { text, data }
Fix: Add both return formats

Schema Import from API Package

Import schemas, don't duplicate:

// ✅ Import from API package
import { SearchQuerySchema, fetchSearchResults, formatSearchResults } from '@youdotcom-oss/api';

export const youSearch = (config: YouToolsConfig = {}) => {
  return tool({
    inputSchema: SearchQuerySchema,  // Reuse
    execute: async (params) => { /* ... */ }
  });
};

// ❌ Don't redefine schemas
const SearchQuerySchema = z.object({ /* ... */ });  // Wrong

Verify: No z.object definitions in tool files
Fix: Import from @youdotcom-oss/api

Available Tools

Testing

bun test                              # All tests
bun test src/tests/integration.spec.ts  # Integration tests

Prerequisites: YDC_API_KEY and ANTHROPIC_API_KEY in .env

Troubleshooting

Missing API key:

echo "export YDC_API_KEY=your-key" > .env
source .env

Type errors with tool.execute():

// ✅ Provide toolCallId and messages
await tool.execute?.({ query: 'test' }, { toolCallId: 'test', messages: [] });

// ❌ Missing second parameter
await tool.execute?.({ query: 'test' });

Test failures with 429:
Wait before re-running, tests use retry: 2

Publishing

See root AGENTS.md

Workflow: .github/workflows/publish-ai-sdk-plugin.yml

Related Skills

• .claude/skills/api-patterns - Foundation API utilities
• .agents/rules/core.md - Code patterns
• .agents/rules/testing.md - Test patterns

Contributing

Package scope: ai-sdk-plugin in commits

feat(ai-sdk-plugin): add image search
fix(ai-sdk-plugin): handle empty results

Converted and distributed by TomeVault — claim your Tome and manage your conversions.