Convex Agents Tools

目的

エージェントがテキスト生成以外の操作を実行できるようにします。ツールを使うと、エージェントは Convex 関数や外部 API を呼び出したり、複雑な操作を実行したりできます。

このスキルを使用する場面

• エージェントがデータベースのデータを照会または変更する必要がある場合
• 外部 API と連携する場合
• 人間が介在するワークフローを作成する場合
• エージェントが実行する操作を自律的に決定する場合
• 複数ステップの操作でツール呼び出しを連鎖させる場合

ツールを定義する

Convex 対応のツールを作成します。

import { createTool } from "@convex-dev/agent";
import { z } from "zod";

export const getUserDataTool = createTool({
  description: "Fetch user information by email",
  args: z.object({
    email: z.string().email().describe("The user's email address"),
  }),
  handler: async (ctx, { email }): Promise<string> => {
    const user = await ctx.runQuery(api.users.getUserByEmail, { email });
    return user ? JSON.stringify(user) : "User not found";
  },
});

エージェントにツールを設定する

const agentWithTools = new Agent(components.agent, {
  name: "Database Agent",
  languageModel: openai.chat("gpt-4o-mini"),
  tools: {
    getUserData: getUserDataTool,
  },
  maxSteps: 5, // Allow tool calls
});

ツールの自動呼び出しを有効にする

export const autonomousAgent = action({
  args: { threadId: v.string(), request: v.string() },
  handler: async (ctx, { threadId, request }) => {
    const { thread } = await agentWithTools.continueThread(ctx, { threadId });

    const result = await thread.generateText(
      { prompt: request },
      { maxSteps: 10 } // Allow up to 10 tool calls
    );

    return result.text;
  },
});

主な原則

• 検証には Zod を使用する：フィールドに .describe() を指定すると、LLM がパラメーターを理解しやすくなります
• 戻り値の型を明示する：ハンドラーの戻り値の型は必ず注釈してください
• 履歴を自動的に保存する：ツールの呼び出しと結果はスレッドに自動的に保存されます
• コンテキストをバインドする：userId などにアクセスできるアクション内でツールを作成してください

次のステップ

• エージェントのセットアップについては fundamentals をご覧ください
• 複数ステップの操作のオーケストレーションについては workflows をご覧ください
• ツールを考慮したコンテキスト管理については context をご覧ください