LiteLlm 是 Google ADK 提供的一個 model wrapper，讓你用統一的介面來呼叫多種 LLM provider。

執行需要在 agent folder ，否則啟用後會找不到 agent 

# 僅能在開發環境執行
adk web
 
# 如果有使用 .venv 則需要使用 uv run （在虛擬環境中執行）
uv run adk web

Agent 是什麼?

Agent 是一個自主執行的單元，可以做到

• 理解使用者需求
• 決定使用哪些工具
• 與其他 Agent 協作（A2A）
• 回應並完成任務

Agent 基本組成

agent = LlmAgent(
    model="{YOUR_MODEL}",     # 使用的 AI 模型
    name="my_agent",               # 唯一識別名稱
    description="這個 Agent 做什麼", # 供其他 Agent 辨識用
    instruction="你是一個...",       # 行為指引（最重要！）
    tools=[tool1, tool2],           # 可用工具列表
)

Instruction 撰寫技巧

動態插入狀態變數

# {var} -> 必填，找不到會報錯
# {var?} -> 選填，找不到則忽略
instruction="目前使用者 {user_name} 正在詢問{topic?}"

Instruction 中引用工具

instruction="""
當使用者詢問天氣時：
1. 使用 `get_weather_report` 工具取得天氣資料
2. 如果工具回傳 error，請向使用者道歉並詢問是否換個城市
3. 成功後使用 `analyze_sentiment` 分析天氣對心情的影響
"""

Agent 類型

LLM Agent （智慧型）

利用 LLM 進行推理、決策，適合自然語言處理、動態工具選擇

from google.adk.agents import LlmAgent
 
agent = LlmAgent(
    model="{YOUR_MODEL}",
    name="smart_agent",
    instruction="...",
    tools=[...],
)

Workflow Agent（流程控制型）

不使用 LLM 控制流程，執行確定性、可預測的流程

SequentialAgent（循序）執行

step1 → step2 → step3

from google.adk.agents import SequentialAgent
 
pipeline = SequentialAgent(
    name="data_pipeline",
    sub_agents=[fetch_agent, process_agent, report_agent],
)

ParallelAgent（平行）執行

多個 sub agent 同時執行，適合可平行化的資料搜集任務

from google.adk.agents import ParallelAgent
 
parallel = ParallelAgent(
    name="parallel_research",
    sub_agents=[search_agent, database_agent],
)

LoopAgent（迴圈）執行

持續執行 sub-agent 直到條件成立

from google.adk.agents import LoopAgent
 
loop = LoopAgent(
    name="retry_loop",
    sub_agents=[check_agent],
    max_iterations=5,  # 最多執行幾次
)

Custom Agent（自定義型）

繼承 BaseAgent，完全自訂執行邏輯：

from google.adk.agents import BaseAgent
 
class MyCustomAgent(BaseAgent):
    async def _run_async_impl(self, ctx):
        # 完全自訂的執行邏輯
        yield some_event

三種類型比較

Tools 工具系統

Tools 讓 Agent 能夠與外部世界互動

工具的執行流程

Function Tool（自訂函式）

最常用的工具類型，ADK 會自動讀取函式的 docstring 和型別提示來告知 LLM 如何使用這個工具，因此寫好文件非常重要

def search_database(query: str, limit: int = 10) -> dict:
    """
    在資料庫中搜尋指定關鍵字。
     
    Args:
        query: 搜尋關鍵字
        limit: 最多返回幾筆結果
     
    Returns:
        dict: 包含 status 和 results 的字典
    """
    # 實作搜尋邏輯
    results = db.search(query, limit=limit)
    return {"status": "success", "results": results}
 
agent = LlmAgent(
    ...,
    tools=[search_database],  # 直接傳函式
)

Agent as Tool（Agent 作為工具）

把另一個 Agent 包裝成工具呼叫，與 sub_agents 的差異在於可以取得子 Agent 的回傳值：

from google.adk.tools import AgentTool
 
specialist_agent = LlmAgent(name="specialist", ...)
 
main_agent = LlmAgent(
    ...,
    tools=[AgentTool(agent=specialist_agent)],
)

Agent 間的溝通方式

1. LLM 動態路由：父 Agent 的 LLM 決定轉給哪個 sub-agent
2. Workflow 控制：由 SequentialAgent / ParallelAgent 決定執行順序
3. Agent as Tool：將 sub-agent 當作工具呼叫

什麼是 Multi-Agent

由多個 AI Agent 組成，每個 Agent 負責特定職責，透過協調者（Orchestrator）統一調度

為何需要使用 Multi-Agent?

• 分工明確：每個 Agent 只做一件事情，易維護
• 可擴充性：新增功能只需要加入新的 Agent 即可
• 容錯性：單一 Agent 失敗不影響整體
• 重用性：相同 Agent 可在不同流程中複用

MCP 工具整合

MCP（Model Context Protocol）讓 Agent 透過標準協定呼叫外部服務（Confluence、JIRA、GitHub 等），無需自己實作 API Client。

概念說明

Agent ──呼叫──> MCPToolset ──stdio──> MCP Server（子行程）(e.g., mcp-atlassian)


基本設定（mcp-atlassian）

# Install
pip install mcp-atlassian
 
# Or
uv add mcp-altassian

import os
from mcp import StdioServerParameters
from google.adk.tools.mcp_tool import StdioConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
 
atlassian_toolset = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="mcp-atlassian",
            args=[],
            env={
                "CONFLUENCE_URL": os.getenv("CONFLUENCE_URL"),
                "CONFLUENCE_PERSONAL_TOKEN": os.getenv("CONFLUENCE_PERSONAL_TOKEN"),
                "CONFLUENCE_SPACES_FILTER": "{CONFLUENCE_SPACE_NAME}",   # 限縮搜尋範圍
                "JIRA_URL": os.getenv("JIRA_URL"),
                "JIRA_PERSONAL_TOKEN": os.getenv("JIRA_PERSONAL_TOKEN"),
                "JIRA_PROJECTS_FILTER": "{JIRA_PROJECT_NAME}",
                "READ_ONLY_MODE": "true",              # 安全設定：唯讀
            },
        ),
        timeout=60,   # 複雜查詢可調高至 180–300
    )
)
 
root_agent = LlmAgent(
    name="wiki_agent",
    model=LiteLlm("{YOUR_MODEL}"),
    tools=[atlassian_toolset],
    instruction="Use MCP tools to search Confluence before answering.",
)

指令說明

• MCPToolset: 這是 ADK 中的關鍵類別。它代表的不是單一工具，而是一整套由外部 MCP 伺服器提供的工具。
• StdioConnectionParams: 我們告訴 ADK，要透過標準輸入/輸出 (Stdio) 的方式與這些外部伺服器溝通。
• StdioServerParameters: 我們在這裡定義了如何啟動這些外部伺服器。ADK 會在幕後為我們管理這些子進程 (sub-processes)。

範例

Sample 1. Confluence + Jira tools

Agent.py

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
 
# noah_mcp 可替換成上方的 mcp-atlassian
from common import agent_config, noah_mcp, prompt
 
root_agent = Agent(
  name="main_agent",
  model=LiteLlm(model=agent_config.MODEL),
  description="AI Modular for jira and confluence",
  instruction=(prompt.mcp_agent() + prompt.mcp_jira() + prompt.mcp_confluence()),
  tools=[noah_mcp.noahs_mcp_jira, noah_mcp.noahs_mcp_wiki]
)

Sample 2. 使用 multi-agent 做 personal 績效表

Agent.py

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm
 
from common import agent_config, prompt
from mcp_agent.agent import root_agent as mcp_root_agent
 
root_agent = Agent(
  name="review_agent",
  model=LiteLlm(agent_config.MODEL),
  description="動態提取 Jira 資料並生成工作總結的 AI 助手。",
  instruction=prompt.review_prompt(),
  sub_agents=[mcp_root_agent]
)

Q&A

為何需要使用 uv & pyproject.toml

如需進行 Python 套件版本管控，可使用 uv + pyproject.toml 處理。

uv 是由 Astral 開發的 Python 套件管理工具（比 pip / poetry 快 10-100x)

# 安裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# 初始化專案
uv init my-project
cd my-project
 
# 現有專案初始化
# uv init

pyproject.toml 結構範例 

[project]
name = "my-project"
version = "0.1.0"
description = "My Python project"
requires-python = ">=3.11"
dependencies = [
    "google-adk>=0.1.0",
    "httpx>=0.27",
]

常用指令

相關資源

• 官方文件：https://google.github.io/adk-docs/