Google ADK で店番AIを動かす

Google AI Studio でAPIキーを発行します。ADKが読むのは GEMINI_API_KEY か GOOGLE_GENAI_API_KEY だけです。

npm i @google/adk zod

ADKは express や OpenTelemetry を含むので、Nextのバンドルに載せずに実行時読み込みにします。

// next.config.ts
const nextConfig = {
  serverExternalPackages: ["@google/adk"],
};

モデルに渡す道具は、経路ごとに書かず1つの配列にまとめます。 こうしておくと、チャット・MCP・ADKで二重管理になりません。chat と agent の 旗で、どこに出すかを分けています。

// src/lib/ai-tools.ts
export type AiTool = {
  name: string;
  description: string;
  inputSchema: Record<string, unknown>; // JSON Schema
  chat: boolean;   // 接客チャットに出すか
  agent: boolean;  // 外部AIエージェント(MCP)に出すか
  run: (input: Record<string, unknown>) => Promise<unknown>;
};

export const AI_TOOLS: AiTool[] = [
  {
    name: "search_products",
    description: "取扱商品を検索する。お客さんの要望を聞いたらまずこれを呼ぶこと。",
    chat: true,
    agent: true,
    inputSchema: {
      type: "object",
      properties: {
        q: { type: "string", description: "キーワード" },
        max_price: { type: "number", description: "上限価格（円・税込）" },
      },
      additionalProperties: false,
    },
    run: async (input) => searchProducts({ q: str(input.q), maxPrice: num(input.max_price) }),
  },
];

ADKの FunctionTool は Zod スキーマを取ります。 道具の定義はMCPと共有したいのでJSON Schemaのまま持ち、機械的に変換します。 実際に使う範囲だけ対応すれば十分です。

// src/lib/ai/json-schema-to-zod.ts
export function jsonSchemaToZod(schema: JsonSchema): z.ZodObject<z.ZodRawShape> {
  if (schema.type !== "object") throw new Error("道具の引数はオブジェクトで定義すること");
  const required = new Set(schema.required ?? []);

  const shape = Object.fromEntries(
    Object.entries(schema.properties ?? {}).map(([key, value]) => {
      const field = toZod(value);
      return [key, required.has(key) ? field : field.optional()];
    }),
  );
  return z.object(shape);
}

道具をADKの FunctionTool に写して、LlmAgent に渡します。instruction が接客方針（システムプロンプト）です。

// src/lib/ai/adk.ts
import { LlmAgent, FunctionTool, InMemoryRunner } from "@google/adk";

function buildTools(trace: AdkTrace): FunctionTool[] {
  return chatTools().map(
    (tool) =>
      new FunctionTool({
        name: tool.name,
        description: tool.description,
        parameters: jsonSchemaToZod(tool.inputSchema),
        execute: async (input) => {
          const output = await tool.run(input ?? {});
          collect(trace, tool.name, input ?? {}, output); // 副作用を回収する
          return output;
        },
      }),
  );
}

export function createAgent(system: string, trace: AdkTrace): LlmAgent {
  return new LlmAgent({
    name: "tenban",
    // env() は空文字列を「未設定」として扱う。詳しくは下の「つまずきやすい点」
    model: env("GEMINI_MODEL") ?? "gemini-flash-latest",
    description: "ひびのば STORE の店番",
    instruction: system,
    tools: buildTools(trace),
  });
}

過去のやりとりはセッションに積み、最後の発言だけを新規メッセージとして渡します。 道具の往復（tool ロール）は積み直しません。

const runner = new InMemoryRunner({ agent, appName: "hibinoba" });
const session = await runner.sessionService.createSession({ appName: "hibinoba", userId });

const history = [...messages];
const latest = history.pop();

for (const message of history) {
  if (message.role === "tool") continue;
  await runner.sessionService.appendEvent({
    session,
    event: {
      author: message.role === "user" ? "user" : agent.name,
      content: {
        role: message.role === "user" ? "user" : "model",
        parts: [{ text: message.text }],
      },
    },
  });
}

let text = "";
for await (const event of runner.runAsync({
  userId,
  sessionId: session.id,
  newMessage: { role: "user", parts: [{ text: latest.text }] },
})) {
  for (const part of event.content?.parts ?? []) {
    if (part.text) text += part.text;
  }
}

ADKが返すのは最終的な文章だけです。 「どの商品に触れたか」「かごに何を入れる提案をしたか」はexecute の中で自分で拾っておきます。 このストアではカートの提案カードをこれで組み立てています。

export type AdkTrace = {
  touchedSlugs: Set<string>;
  proposal: { lines: CartLine[]; reason: string; total: number; itemCount: number } | null;
};

// execute の中で
if (tool.name === "propose_cart") {
  const q = await quote(toCartLines(input?.lines)); // 金額はサーバで確定させる
  trace.proposal = {
    lines: q.lines.map((l) => ({ slug: l.slug, qty: l.qty })),
    reason: String(input?.reason ?? ""),
    total: q.total,
    itemCount: q.itemCount,
  };
}

ADKは鍵が不正でも例外を投げず、空文字を返すことがあります。 空の返答をそのまま店の言葉として出さないよう、明示的に落とします。

const { text, trace, model } = await runWithAdk(system, messages);

// 空の返答を店の言葉として出さない
if (!text) throw new Error("ADK から本文が返りませんでした");

呼び出し側では、例外を検索ベースの応答に退避させます。 キーが未設定でも、モデルが落ちていても、店として黙り込まない状態を作ります。

if (selected === "adk") {
  try {
    return await converseWithAdk(messages, shopper);
  } catch (e) {
    console.error("[concierge] adk", e);
    return fallbackConcierge(messages); // キーワード検索で答える
  }
}