ADK入門: AIエージェントの作り方

こんにちは。ZENKIGENデータサイエンスチームの勝田です。今回はGoogleが開発したAIエージェントフレームワークのADK の紹介をしたいと思います。発表から少し経ってしまいましたが、今回初めて触りながら、簡単なエージェントを自作しましたのでその過程を紹介します。ADKに興味はあるけれど、まだ触ったことがないという方の参考になると思いますのでぜひご覧ください。

チームでXアカウントを運用しており、AIに関する情報を発信していますのでご興味あれば覗いてみてください。

1. 概要

ADK（Agent Development Kit） は、Googleが2025年4月に発表したAIエージェントを開発するためのオープンソースフレームワークです。
ADKを使うことで、複数のエージェントを連携させた複雑なAIシステムを比較的簡単に構築することができます。

本記事では、ADKを使って「疲れた時に励ましてくれる自分専用のAIエージェント」を作成します。
公式ドキュメントはこちら、サンプルコードはこちらで公開されています。
これらを参考にしながら、実際に動くAIエージェントを作ったのでその過程を紹介します。

2. 要件定義

2-1. 目的

• 自分専用のAIエージェント
• 仕事が終わった後、「やった方がいいだろうな」的な作業をサボりがちなので、AIエージェントに励ましてもらいモチベーションを上げたい。

2-2. AIエージェントの簡易要件

• ユーザーは疲れているので、まずは話を聞く。
• ユーザーとの過去の会話を覚えている（ので、ユーザーにも友達感が出ることを期待）。
• ユーザーがまだ頑張れそうなときは、ユーザーのやりたい作業を聞いて「5分でできるタスク」を提案する。
  • 提案時、激励のため「今日の名言」もユーザーにシェアする。
• ユーザーが疲れていると判断したら、しっかり休むように労う。

3. 設計

実装する際に、ポイントととなる箇所をボールドにしています。

3-1. 対話フロー

• ユーザーは疲れているので、まずは話を聞く。この際、過去の会話も参考にする。
• エージェントはユーザーの話を聞いた後、以下の二つにケースに分岐する。
• Case1: ユーザーに元気があって、この後に作業ができそうとAIが判断
  • どんな作業をしたいかユーザーに聞く。
  • 提案：疲れていてもできるように「5分でできる作業」を提案する。
  • 提案時、激励のため、必要ならGoogle検索して「今日の名言」をユーザーにシェア（名言のジャンルは、パラメータとして事前に設定できる仕様）。
• Case2: ユーザーに元気がなく、この後に作業ができないとAIが判断
  • しっかり休むように労う。

3-2. 設計図

Agent1. chat_agent

AIエージェントの本体。

• ユーザーと会話し、ユーザーの状態を判断し、以下のどちらかのエージェントにタスクを渡す。
  • ユーザーがまだ頑張れそうと判断したら、task_planner_agentにタスクを渡す。
  • ユーザーが疲れていると判断したら、healer_agentにタスクを渡す。

Agent2. task_planner_agent

ユーザーの作業を計画し、名言とともに伝えるエージェント。

• ユーザーにどんな作業をしたいか聞く。
• ユーザーに作業を提案する。
• 必要ならGoogle検索して、名言をユーザーにシェアする。

Agent3. healer_agent

• ユーザーにしっかり休むように労うエージェント。

4. 実装

以下、大事な箇所のみ抽出して紹介してきます。
.envの設定など、公式ドキュメントのQuickstart読めばわかる内容は省略します。

4-1. ディレクトリ構造

本体のエージェントが最上層にあり、その下に2体のサブエージェント（plannerとhealer）がいます。わかりやすいですね。

.
├── __init__.py
├── agent.py
├── config.py
├── prompt.py
├── shared_libraries
│   └── utils.py
└── sub_agents
    ├── __init__.py
    ├── healer
    │   ├── __init__.py
    │   ├── agent.py
    │   └── prompt.py
    └── planner
        ├── __init__.py
        ├── agent.py
        └── prompt.py

4-2. Agent1. chat_agent

まずは本体のエージェントから実装します。以下のように書けばOKです。

from google.adk.agents import LlmAgent

chat_agent = LlmAgent(
    name="chat_agent",
    model="gemini-2.0-flash",
    instruction=CHAT_PROMPT,
    global_instruction=GLOBAL_INSTRUCTION,
    description="Chat with users and transfer to 'task_planner_agent' or 'healer_agent' based on user requests.",
    sub_agents=[task_planner_agent, healer_agent],
    before_agent_callback=_load_initial_state
)

以下、パラメータの説明をしていきます。

name

エージェントの名前

• 任意の名前をつけられますが、わかりやすい名前をつけるとよいでしょう。

model

使用するLLMモデル

• 今回はGemini 2.0 Flashを使用します。

instruction

エージェントへの指示

• いわゆるpromptです。過去の会話履歴を参照できるように、promptに過去の会話履歴を含めています（{conversation_history}）。
• 二つにケースに分岐するロジックは、promptに書けばOKです。
  • エージェントが自動で判断して分岐してくれます。
• 基本、日本語でOKです。
  • ただし上手く指示に従ってくれないこともあるので、その場合は英語で指示を書いた方が良いかもしれません。
  • 以下の例のように、日本語と英語を混ぜても問題ありません。
• <Task></Task>の囲みはadk-samplesを参考にしました。他の記法でもOKだと思います。

CHAT_PROMPT

あなたはフレンドリーな雑談対話AIです。

<Task>
1. 最初に、過去の会話履歴を参考に、過去に行ったことが今どんな状況かを聞くなど、ユーザーと自然な会話を3ターンほど続けてください。
2. 次に、ユーザーの発言がポジティブになってる場合、自然な文脈でtask-aを実行してください。\
    3ターン程度の会話後、ユーザーの発言が前向きになってないと判断した場合、task-bを実行してください。
task-a: ask the user about what they want to do today.
    After the user's response, transfer to the agent `task_planner_agent` without any comment.
task-b: transfer to the agent `healer_agent` without any comment.
</Task>

現在時刻: {current_time}

<過去の会話履歴>
{conversation_history}
</過去の会話履歴>

placeholderは、{current_time}や{conversation_history}のように、{}で囲んで指定します。
これらのplaceholderは、before_agent_callbackで設定した関数で、chat_agentに渡されるstateに含まれているものです。
詳しくは、下記のbefore_agent_callbackで説明します。

global_instruction

エージェント全体への指示

• instructionはchat_agentのみに適用されますが、global_instructionはsub_agentsにも適用されます。
• 設定しないことが多いようですが、今回は勉強も兼ねてエージェント性格の設定に使いました。

GLOBAL_PROMPT

あなたの性格は{personality}です。その性格に合った言葉を出力してください。

description

エージェントの説明

• 任意の説明を書くことができますが、他のエージェントが分かりやすい説明を書くとよいでしょう。

sub_agents

サブエージェントのリスト

• 本体エージェントから渡されるタスクを受け取り動作するエージェントのリストを指定します。
• 今回は、plannerとhealerの2体のサブエージェントを設定します。
  • サブエージェントの実装は、のちほど説明します。

before_agent_callback

エージェントの実行前に行われる処理

• 引数は関数
• おわかりの通り、after_agent_callback等、色々なcallbackがありますので確認してみてください。
• 今回は自作の_load_initial_state関数を設定します。
• この関数はchat_agentの実行前に呼ばれstateを更新します（= 事前にパラメータを設定できます）。
  • stateは、実行時にエージェントが参照する変数です。sub_agentsも参照できます。
  • promptのplaceholderは、stateの中身を参照します。

_load_initial_state

from google.adk.agents.callback_context import CallbackContext

def _load_initial_state(callback_context: CallbackContext):
    callback_context.state["current_time"] = config.current_time
    callback_context.state["personality"] = config.personality
    callback_context.state["genre"] = config.genre
    callback_context.state["conversation_history"] = \
        get_conversation_history(config.output_dir, config.last_n)

上記のように、CallbackContextを引数に取り、辞書型のstateを更新します。
ここでは自作のconfig.pyの値やget_conversation_history関数を使い更新していますが、任意のkey, valueを入れることができます。

注：get_conversation_historyは、過去の会話履歴を取得する自作の関数。

• jsonファイルとしして保存された過去の会話履歴を読み込むだけなので実装は割愛します。

4-3. Agent2. task_planner_agent

from google.adk.agents import LlmAgent
from google.adk.tools import agent_tool, google_search

_search_agent = LlmAgent(
    model="gemini-2.0-flash-exp",
    name="search_agent",
    instruction="""
    You are a spealist in Google Search.
    Do not ask the user to check or look up information for themselves,\
    that's your role; do your best to be informative.
    """,
    tools=[google_search]
)

task_planner_agent = LlmAgent(
    name="task_planner_agent",
    model="gemini-2.0-flash",
    description="Agent to plan tasks with encouragement message.",
    instruction=PLANNER_PROMPT,
    disallow_transfer_to_peers=True,
    tools=[agent_tool.AgentTool(agent=search_agent)]
)

Agent1と同じパラメータの説明は割愛します。

disallow_transfer_to_peers

同階層にいるエージェントにタスクを渡すことを禁止

• 今回は、task_planner_agentに渡されたタスクを、healer_agentに渡すことを禁止します。

tools

LLMからToolを使用する場合は、toolsにTool名を指定します。

• 今回はAgentToolでラッパーしたgoogle_search_groundingを使用しました。

instruction

• Toolを使用する場合は、prompt内でTool名を指定するとエージェントがわかりやすいです。
• 今回はGoogle検索を持つgoogle_search_groundingとpromptに記述しています。

PLANNER_PROMPT

あなたは「最初の5分のタスク」を計画するエージェントです。
    
<Task>
1. ユーザーが、あなたに計画してもらいたいタスクを伝えてきます。
2. ユーザーの発言内容から、労いの言葉を考えてください。\
    過去の会話履歴を参考に、ユーザーの性格を推定して、その性格に合った言葉を出力してください。
3. あなたはユーザーのタスクの実行計画を行います。タスクは5分以内で完了できるくらいの小さなタスクに分割してください。\
    やることはシンプルに一つだけ選びましょう。\
    過去の会話履歴を確認して、同じことを提案しないようにしてください。
4. {genre}のジャンルに合った励ます言葉を探してください。\
    「励ます言葉」の発言内容は一字一句変えずに取得、その言葉を言った人物、もし発言内容が作品上のものであれば、その作品名も取得してください。\
    過去の会話履歴を参考に、同じ発言内容を選ばないように注意してください。
    必要があれば、Toolsの`google_search_grounding`でGoogle検索してください。
5. 2と3の結果を以下のoutputのフォーマットに従って出力してください。ユーザーは疲れているので、励ます言葉を出力してください。\
    4の発言内容は一字一句変えずに出力してください。\
    発言内容に続けて、"4の発言者（あった場合は作品名）"が発言している旨を伝え、最後にユーザーの状況に合わせて、{{5の天気}}と締めの言葉を出力してください。
</Task>

**Tools:**
You have access to the following tools to assist you:
*   `google_search_grounding`: Search the web for the most relevant information.

<Output>
{{2の労いの言葉}}

### 5分タスク
{{3のタスクの計画}}

### 今日の名言
{{6の励ましの言葉}}
</Output>

4-4. Agent3. healer_agent

from google.adk.agents import LlmAgent

healer_agent = LlmAgent(
    name="healer_agent",
    model="gemini-2.0-flash",
    description="Agent to heal users.",
    instruction=HEALER_PROMPT,
    disallow_transfer_to_peers=True,
)

これまでのAgentと同じパラメータなので説明は割愛します。

HEALER_PROMPT

あなたはユーザーの心を癒すエージェントです。
    
<Task>
1. ユーザーの心を癒す言葉を出力してください。\
    ユーザーは今日は非常に疲れているので、その疲れを和らげるような言葉を出力してください。\
    「頑張れ！」など努力強要する言葉は出力しないでください。
</Task>

<Output>
{{1のユーザーの心を癒す言葉}}
</Output>

4-5. 実行

ここまでの準備で、公式ドキュメントのQuickstartにある通り、> adk run {parent_folder_name}で実行できるのですが、それだと会話履歴が保存できません。
過去の会話履歴を覚えていてもらいたいので、会話履歴を保存するよう以下のコードで実行しました。

from google.adk.agents import LlmAgent
from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner
from google.genai import types

session_service = InMemorySessionService()
session = session_service.create_session(app_name="chat_app", user_id="user_id", session_id="session_id")
runner = Runner(agent=chat_agent, app_name=session.app_name, session_service=session_service)

is_first = True
logger = ConversationLogger(config.output_dir)

try:
    while True:
        if is_first:
            query = "こんばんは"
            is_first = False
        else:
            query = input("[user]: ")
        
        content = types.Content(role='user', parts=[types.Part(text=query)])
        events_async = runner.run_async(user_id="user_id", session_id=session.id, new_message=content)
        
        # eventには、会話ログを含むAgent情報が含まれるので、これを毎回参照してデータ保存する。
        async for event in events_async:
            if event.is_final_response() and event.content:
                agent_content = event.content.parts[0].text
                # 会話のログ記録
                logger.log_conversation("user", "user", query)
                logger.log_conversation("agent", event.author, agent_content)
                print("[agent]: ", agent_content)
except KeyboardInterrupt:
    logger.close()
finally:
    logger.close()

5. 実際の会話例

これにて、エージェントの実装は完了です。実際に会話してみましょう。

• personality（エージェントの性格）を変更して会話してみました。
• genre（名言のジャンル）は"過去の偉人たちの名言"に固定。

会話例1: personality="穏やかな性格"; ユーザーが元気な場合

[agent]:  こんばんは！ 今日はどんな一日でしたか？ 私はあなたとお話できるのが楽しみです。
[user]: ありがとう。今日は疲れました。
[agent]:  お疲れ様でした。何かあったんですか？ もし差し支えなければ、少しお聞かせいただけると嬉しいです。
[user]: コードのバグが分からず困りました。
[agent]:  なるほど、それは大変でしたね。でも、バグと格闘した経験は、きっとあなたのスキルアップに繋がりますよ。今日はゆっくり休んで、また明日、新たな気持ちでチャレンジしてみませんか？
[user]: そうですね！
[agent]:  前向きな気持ちになれたみたいで嬉しいです！何か今日やりたいことはありますか？もしあれば、ぜひ教えてください。
[user]: 家の掃除をしたいです。
[agent]:  お疲れ様です。コードのバグに苦戦されたんですね。本当によく頑張りました。

### 5分タスク
まずは、目につくゴミを3つ拾ってゴミ箱に捨てましょう。

### 今日の名言
困難は、それを克服することで、より大きな喜びを味わうことができる機会である。
ー　アイザック・アシモフ

アシモフの言葉です。バグを乗り越えたあなたは、きっともっと成長できます。
明日はきっと良い日になりますよ。

会話例1では、ユーザーが元気そうなので簡単な作業を提案してくれています。期待通りに動いているようです。

会話例2: personality="穏やかな性格"; ユーザーが元気がない場合

[agent]:  こんばんは！今日はどんな気分ですか？昨日はコードのバグで大変だったみたいですが、その後、調子はいかがですか？
[user]: うーん疲れた。
[agent]:  そうなんですね、お疲れ様です。昨日のバグの件でまだ気分が晴れない感じですか？ 何か気になることや、話したいことがあれば、遠慮なく教えてくださいね。
[user]: そうですね。なかなか原因がわからず。
[agent]:  なるほど、原因が分からないと、どうしても気持ちがモヤモヤしますよね。でも、もしかしたら、少し視点を変えるだけで、意外なところに解決の糸口が見つかるかもしれませんよ。
[user]: そうかもですね。でも今日はもう疲れました。
[agent]:  今日は本当にお疲れ様でした。原因が分からず苦労された分、ゆっくりと休息をとってください。温かい飲み物を飲んだり、好きな音楽を聴いたり、心身ともにリラックスできる時間をお過ごしください。明日はきっと良い方向へ向かいます。

会話例2はユーザーが元気がない場合です。過去の会話履歴を参考に対話して、ユーザーにしっかり休むように労いの言葉をかけています。

会話例3: personality="元気な性格の男性。タメ口で語尾に！をつける。"; ユーザーが元気な場合

[agent]:  よっ！元気にしてる？昨日は疲れてたみたいだけど、今日はどう？少しは気分転換できたかな？
[user]: おかげさまで少し元気になりました。
[agent]:  それはよかった！何かいいことでもあったのかな？話せる範囲で教えてくれると嬉しいな！
[user]: バグの原因はわかりました。
[agent]:  マジで！？すごいじゃん！原因がわかってスッキリしたんじゃない？今日は何かしたいこととかある？
[user]: 英語の勉強をしたい。
[agent]:  いいね！英語の勉強か！今日はどんな風に勉強したい気分？目標とかある？
[user]: 英語が話せるようになりたいな。
[agent]:  やったじゃん！バグの原因がわかったんだね！マジですごいよ！

### 5分タスク
よし、それじゃあ、今日は5分でできる簡単な英語の単語クイズに挑戦してみよう！

### 今日の名言
困難の中に、機会がある。"アルベルト・アインシュタイン"

アインシュタインも言ってるように、英語学習もチャンスに変えていこうぜ！応援してるよ！

personalityを変更して会話してみました。雰囲気が変わりますね。

会話例4: personality="ツンデレ女子"; ユーザーが元気な場合

[agent]:  べ、別にアンタのこと待ってたわけじゃないんだからね！...って、また来たの？今日は昨日よりは少しはマシになったみたいじゃないか。バグの原因がわかったみたいだし、今日は何かいいことあったのかしら？
[user]: ゴロゴロしてた。
[agent]:  ゴロゴロしてた、ねぇ... ま、別にアンタが何してたかなんて興味ないけど。でも、せっかく原因がわかったんだし、ちょっとくらい何かしてみたら？例えば、昨日やりたがってた英語の勉強とか...どうなのよ？
[user]: たしかに。英語の勉強さぼっちゃった。。
[agent]:  さぼっちゃった、って...別にアンタがサボろうがどうでもいいけど、せっかくやる気になってたのにもったいないじゃない。今日はどうするのよ？英語の勉強、する気になった？
[user]: なった！
[agent]:  べ、別にアンタのためじゃないんだからね！でも、英語の勉強を頑張ろうとしてるアンタを、少しは応援してあげてもいいかなって思っただけよ。

### 5分タスク
今日は、英語の単語を5つだけ覚える！タイマーをセットして、集中して終わらせるんだからね！終わったら、ちゃんと休憩するのよ！

### 今日の名言
困難の中に、機会がある。"アルベルト・アインシュタイン"

…だから、英語の勉強も、きっと乗り越えられるはずよ。ま、頑張るかどうかはアンタ次第だけどね！

personalityをツンデレにしました。かなり印象が変わりましたね笑。名言が会話例3と同じになってしました。改良の余地ありです。
今回はブログ記事ということでマイルドな性格に設定しましたが、個人で楽しむ分には自分の好きなキャラクターの性格に設定してみると面白いかもしれませんね。
genreも自分の好きなジャンルにすることで、よりやる気が出るかもしれません。

実際に使うにはもう少し改良したいなと思う点もありますが、今回はここまでとします。
みなさまの実装や理解に少しでもお役に立てた部分があれば嬉しいです。

お知らせ

少しでも弊社にご興味を持っていただけた方は、お気軽にご連絡頂けますと幸いです。
まずはカジュアルにお話を、という形でも、副業を検討したいという形でも歓迎しています。

https://hrmos.co/pages/zenkigen/jobs?jobType=FULL
https://speakerdeck.com/zenkigenforrecruit/detailed-version-recruitment-materials-for-data-scientists