ADK-Python Hello World：入门示例与快速开始

【免费下载链接】adk-python 一款开源、代码优先的Python工具包，用于构建、评估和部署灵活可控的复杂 AI agents 项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python

还在为构建复杂的AI Agent（智能体）而头疼吗？想快速上手Google的Agent Development Kit（ADK）却不知从何开始？本文将带你通过一个完整的Hello World示例，快速掌握ADK-Python的核心概念和使用方法。

🎯 读完本文你将获得

• ADK-Python环境搭建与安装指南
• 第一个AI Agent的完整实现代码
• 工具函数定义与集成方法
• 会话管理与状态保持机制
• 异步运行与事件处理技巧
• 实际运行效果与调试方法

📦 环境准备与安装

首先确保你的Python环境版本在3.9以上，然后通过pip安装ADK：

pip install google-adk

对于开发版本，可以直接从GitHub安装：

pip install git+https://github.com/google/adk-python.git@main

🎲 Hello World示例：骰子与质数检查Agent

下面是一个完整的Hello World示例，创建一个能够掷骰子和检查质数的AI Agent。

项目结构

核心代码实现

agent.py - Agent定义与工具函数

import random
from google.adk import Agent
from google.adk.tools.tool_context import ToolContext
from google.genai import types

def roll_die(sides: int, tool_context: ToolContext) -> int:
    """掷骰子并返回结果
    
    Args:
        sides: 骰子的面数
        
    Returns:
        骰子掷出的结果
    """
    result = random.randint(1, sides)
    if 'rolls' not in tool_context.state:
        tool_context.state['rolls'] = []
    tool_context.state['rolls'].append(result)
    return result

async def check_prime(nums: list[int]) -> str:
    """检查数字是否为质数
    
    Args:
        nums: 要检查的数字列表
        
    Returns:
        质数检查结果字符串
    """
    primes = set()
    for number in nums:
        number = int(number)
        if number <= 1:
            continue
        is_prime = True
        for i in range(2, int(number**0.5) + 1):
            if number % i == 0:
                is_prime = False
                break
        if is_prime:
            primes.add(number)
    return (
        '未找到质数。'
        if not primes
        else f"{', '.join(str(num) for num in primes)} 是质数。"
    )

root_agent = Agent(
    model='gemini-2.0-flash',
    name='hello_world_agent',
    description='能够掷8面骰子和检查质数的Hello World Agent',
    instruction="""
    你负责掷骰子并回答关于骰子结果的问题。
    你可以掷不同面数的骰子。
    你可以在一个请求中并行调用多个工具函数。
    可以讨论之前的骰子掷出结果，并对掷骰结果进行评论。
    当要求掷骰子时，必须调用roll_die工具并传入面数整数。
    当检查质数时，调用check_prime工具并传入整数列表。
    当要求掷骰子并检查质数时，按以下步骤执行：
    1. 首先调用roll_die工具获取掷骰结果
    2. 获得roll_die结果后，调用check_prime工具检查该结果
    3. 在响应中必须包含第一步的掷骰结果
    """,
    tools=[roll_die, check_prime],
    generate_content_config=types.GenerateContentConfig(
        safety_settings=[
            types.SafetySetting(
                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
                threshold=types.HarmBlockThreshold.OFF,
            ),
        ]
    ),
)

main.py - 运行与测试

import asyncio
import time
import agent
from dotenv import load_dotenv
from google.adk.agents.run_config import RunConfig
from google.adk.cli.utils import logs
from google.adk.runners import InMemoryRunner
from google.adk.sessions.session import Session
from google.genai import types

load_dotenv(override=True)
logs.log_to_tmp_folder()

async def main():
    app_name = 'my_app'
    user_id_1 = 'user1'
    runner = InMemoryRunner(
        agent=agent.root_agent,
        app_name=app_name,
    )
    session_11 = await runner.session_service.create_session(
        app_name=app_name, user_id=user_id_1
    )

    async def run_prompt(session: Session, new_message: str):
        content = types.Content(
            role='user', parts=[types.Part.from_text(text=new_message)]
        )
        print('** 用户说:', new_message)
        async for event in runner.run_async(
            user_id=user_id_1,
            session_id=session.id,
            new_message=content,
        ):
            if event.content.parts and event.content.parts[0].text:
                print(f'** {event.author}: {event.content.parts[0].text}')

    start_time = time.time()
    print('开始时间:', start_time)
    print('------------------------------------')
    
    await run_prompt(session_11, '你好')
    await run_prompt(session_11, '掷一个100面的骰子')
    await run_prompt(session_11, '再掷一次100面的骰子')
    await run_prompt(session_11, '我掷出了什么数字？')
    
    end_time = time.time()
    print('------------------------------------')
    print('结束时间:', end_time)
    print('总耗时:', end_time - start_time)

if __name__ == '__main__':
    asyncio.run(main())

🔧 核心概念解析

1. Agent（智能体）结构

ADK中的Agent包含以下核心组件：

组件	说明	示例
model	使用的AI模型	gemini-2.0-flash
name	Agent名称	hello_world_agent
instruction	系统指令	详细的行为指导
tools	可用工具列表	[roll_die, check_prime]
description	Agent描述	功能说明

2. 工具函数设计

工具函数是Agent能力的扩展，需要遵循特定的签名规范：

def tool_function(param: type, tool_context: ToolContext) -> return_type:
    # 函数实现
    # 可以通过tool_context.state维护会话状态

3. 会话管理

ADK提供了完整的会话管理机制：

🚀 运行与测试

运行示例代码：

python -m contributing.samples.hello_world.main

预期输出示例：

开始时间: 1735530999.123456
------------------------------------
** 用户说: 你好
** hello_world_agent: 你好！我是一个能够掷骰子和检查质数的助手。
** 用户说: 掷一个100面的骰子
** hello_world_agent: 我掷出了数字42。
** 用户说: 再掷一次100面的骰子  
** hello_world_agent: 这次掷出了数字17。
** 用户说: 我掷出了什么数字？
** hello_world_agent: 你掷出的数字是42和17。
------------------------------------
结束时间: 1735531002.654321
总耗时: 3.530865

💡 进阶特性

状态管理

Agent可以通过tool_context.state维护会话状态：

def example_tool(param, tool_context):
    # 初始化状态
    if 'counter' not in tool_context.state:
        tool_context.state['counter'] = 0
    
    # 更新状态
    tool_context.state['counter'] += 1
    
    return f"调用次数: {tool_context.state['counter']}"

异步工具支持

ADK支持异步工具函数，适合处理IO密集型操作：

async def async_tool(param):
    # 模拟异步操作
    await asyncio.sleep(1)
    return "异步操作完成"

🎯 总结与下一步

通过这个Hello World示例，你已经掌握了ADK-Python的核心概念：

1. 环境搭建 - 使用pip安装ADK
2. Agent定义 - 创建具有特定能力的AI智能体
3. 工具集成 - 为Agent添加自定义功能
4. 会话管理 - 维护用户会话状态
5. 异步运行 - 使用异步模式处理请求

下一步建议：

• 探索多Agent系统架构
• 学习集成外部API工具
• 了解Agent评估和部署流程
• 尝试不同的AI模型配置

ADK-Python为构建复杂的AI应用提供了强大的基础框架，从这个简单的Hello World开始，你可以逐步构建出功能丰富的智能体系统。

Happy Agent Building！

【免费下载链接】adk-python 一款开源、代码优先的Python工具包，用于构建、评估和部署灵活可控的复杂 AI agents 项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python