Call オプションは、型安全な構造化入力をエージェントに渡すことを可能にします。これらを使用して、特定のリクエストに基づいてエージェント設定を動的に変更できます。

Vercel AI SDK 6.x : エージェント – Call オプションの設定

作成 : Masashi Okumura (@classcat.com)
作成日時 : 01/19/2026
バージョン : ai@6.0.39

* 本記事は ai-sdk.dev/docs の以下のページを参考にしています :

• Agents – Configuring Call Options

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

 

 

 

Vercel AI SDK 6.x : エージェント – Call オプションの設定

Call オプションは、型安全な構造化入力をエージェントに渡すことを可能にします。これらを使用して、特定のリクエストに基づいてエージェント設定を動的に変更できます。

 

Why Use Call Options?

実行時コンテキストに基づいてエージェントの動作を変更する必要がある場合 :

• 動的コンテキストの追加 – 取得したドキュメント、ユーア設定、セッションデータをプロンプトに注入します。

• モデルを動的に選択 – リクエストの複雑さに基づいてより高速、あるいはより高性能なモデルを選択します。

• リクエスト毎にツールを設定 – 検索ツールにユーザの位置情報を渡したり、ツールの動作を調整します。

• プロバイダーオプションのカスタマイズ – 推論量 (reasoning effort)、温度 (ランダム性)、その他のプロバイダー固有設定を設定します。

call オプションがないと、複数のエージェントを作成したり、エージェントの外側で設定ロジックを処理する必要があるでしょう。

 

How It Works

call オプションを 3 つのステップで定義します :

1. スキーマを定義する – callOptionsSchema を使用して、受け取る入力を指定します

2. prepareCall による設定 – これらの入力を使用してエージェント設定を変更します

3. 実行時にオプションを渡す – generate() や stream() を呼び出すときにオプションを提供します

 

基本的な例

実行時にユーザコンテキストをエージェントのプロンプトに追加します :

Gateway

import { ToolLoopAgent } from 'ai';
import { z } from 'zod';

const supportAgent = new ToolLoopAgent({
  model: "openai/gpt-4o-mini",
  callOptionsSchema: z.object({
    userId: z.string(),
    accountType: z.enum(['free', 'pro', 'enterprise']),
  }),
  instructions: 'You are a helpful customer support agent.',
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    instructions:
      settings.instructions +
      `\nUser context:
- Account type: ${options.accountType}
- User ID: ${options.userId}

Adjust your response based on the user's account level.`,
  }),
});

// Call the agent with specific user context
const result = await supportAgent.generate({
  prompt: 'How do I upgrade my account?',
  options: {
    userId: 'user_123',
    accountType: 'free',
  },
});

options パラメータが必要となり型チェックが行われます。それを提供しないか、間違った型を渡した場合、TypeScript はエラーになります。

 

エージェント設定の変更

prepareCall を使用してエージェントの設定を変更します。変更したい設定のみ返します。

 

動的モデル選択

リクエストの特性に基づいてモデルを選択します :

Gateway

import { ToolLoopAgent } from 'ai';
import { z } from 'zod';

const agent = new ToolLoopAgent({
  model: "openai/gpt-4o-mini", // Default model
  callOptionsSchema: z.object({
    complexity: z.enum(['simple', 'complex']),
  }),
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    model:
      options.complexity === 'simple' ? 'openai/gpt-4o-mini' : 'openai/o1-mini',
  }),
});

// Use faster model for simple queries
await agent.generate({
  prompt: 'What is 2+2?',
  options: { complexity: 'simple' },
});

// Use more capable model for complex reasoning
await agent.generate({
  prompt: 'Explain quantum entanglement',
  options: { complexity: 'complex' },
});

 

動的ツール構成

実行時コンテキストに基づいてツールを構成します :

Gateway

import { openai } from '@ai-sdk/openai';
import { ToolLoopAgent } from 'ai';
import { z } from 'zod';

const newsAgent = new ToolLoopAgent({
  model: "openai/gpt-4o-mini",
  callOptionsSchema: z.object({
    userCity: z.string().optional(),
    userRegion: z.string().optional(),
  }),
  tools: {
    web_search: openai.tools.webSearch(),
  },
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    tools: {
      web_search: openai.tools.webSearch({
        searchContextSize: 'low',
        userLocation: {
          type: 'approximate',
          city: options.userCity,
          region: options.userRegion,
          country: 'US',
        },
      }),
    },
  }),
});

await newsAgent.generate({
  prompt: 'What are the top local news stories?',
  options: {
    userCity: 'San Francisco',
    userRegion: 'California',
  },
});

 

プロバイダー固有のオプション

プロバイダー設定を動的に構成します :

Gateway

import { openai, OpenAIProviderOptions } from '@ai-sdk/openai';
import { ToolLoopAgent } from 'ai';
import { z } from 'zod';

const agent = new ToolLoopAgent({
  model: 'openai/o3',
  callOptionsSchema: z.object({
    taskDifficulty: z.enum(['low', 'medium', 'high']),
  }),
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    providerOptions: {
      openai: {
        reasoningEffort: options.taskDifficulty,
      } satisfies OpenAIProviderOptions,
    },
  }),
});

await agent.generate({
  prompt: 'Analyze this complex scenario...',
  options: { taskDifficulty: 'high' },
});

 

高度なパターン

検索拡張生成 (RAG)

関連コンテキストを取得して、プロンプトに注入します :

Gateway

import { ToolLoopAgent } from 'ai';
import { z } from 'zod';

const ragAgent = new ToolLoopAgent({
  model: "openai/gpt-4o-mini",
  callOptionsSchema: z.object({
    query: z.string(),
  }),
  prepareCall: async ({ options, ...settings }) => {
    // Fetch relevant documents (this can be async)
    const documents = await vectorSearch(options.query);

    return {
      ...settings,
      instructions: `Answer questions using the following context:

${documents.map(doc => doc.content).join('\n\n')}`,
    };
  },
});

await ragAgent.generate({
  prompt: 'What is our refund policy?',
  options: { query: 'refund policy' },
});

prepareCall 関数は非同期であることも可能で、エージェントを構成する前にデータを取得することを可能にします。

以上