[AI]Agent开发——ADK框架使用

$AI$ Agent开发------ADK框架使用

AI时代，越来越多的Skill、MCP、Agent被创建出来。那么Agent是如何开发的，企业级Agent的开发流程是如何的，目前业内Agent开发框架比较多，主流的主要是Google ADK、OpenAI Agents SDK等。

与其他框架相比，ADK 的优势在于与 Google AI 基础设施的深度集成，提供企业级的上下文绑定（Grounding）、数据访问和监控能力。同时 ADK 注重互操作性，支持工具封装器和用于智能体间通信的 A2A（Agent2Agent）协议。

Thoughtworks 技术雷达已将 ADK 从"评估"阶段推进到"试用"阶段，认为其生态系统和运营能力已显著成熟。

一、概念

**基础概念：**Agent Development Kit（ADK）是 Google 开源的一个灵活、模块化的 AI Agent 开发框架。它的核心理念是让 Agent 开发更接近传统软件开发------通过代码优先（Code-First）的方式，将 Agent 的逻辑、工具和编排直接定义在代码中，从而支持版本控制、自动化测试和 CI/CD 集成。

ADK 官方文档：https://google.github.io/adk-docs/

ADK Python 快速入门：https://adk.wiki/get-started/python/

ADK GitHub（Python）：https://github.com/google/adk-python

ADK 示例：https://github.com/google/adk-samples

核心术语：

核心特征：

多智能体架构（Multi-Agent by Design）：支持将多个专用 Agent 组合成层次化结构，实现复杂的协调与任务委派。
模型无关（Model-Agnostic）：虽然针对 Gemini 和 Google 生态做了优化，但 ADK 支持多种模型------可通过 Vertex AI Model Garden 接入各类模型，也通过 LiteLLM 集成支持 Anthropic、Meta、Mistral AI、AI21 Labs 等第三方模型。
丰富的工具生态：可使用预置工具（Search、Code Exec）、MCP 工具、集成 LangChain/LlamaIndex 等第三方库，甚至可将其他 Agent（如 LangGraph、CrewAI 构建的 Agent）作为工具使用。
灵活编排：支持工作流 Agent（顺序、并行、循环）用于可预测的流水线，也支持 LLM 驱动的动态路由（LlmAgent transfer）实现自适应行为。
内置流式能力：支持双向音频和视频流式传输，实现低延迟、类人的多模态对话交互。
一体化开发体验：提供强大的 CLI 和可视化 Web UI，支持本地开发、测试和调试。
内置评估与部署：支持系统化评估 Agent 的响应质量和执行轨迹，可容器化部署到任意环境。

目前 ADK 已支持 Python、TypeScript/JavaScript、Java、Go、Kotlin 等多种语言。Python ADK 已发布 2.0 GA 版本。

二、实战

这里选择Python版本进行演示。

环境要求：

Python 3.10 或更高版本
pip 用于安装包依赖

1. 安装ADK

bash 复制代码

pip install google-adk

# 如需安装可选扩展集成，可使用：
# pip install "google-adk[extensions]"

# adk模型支持Gemini模型，如果想要使用国产模型，可安装litellm库
# pip install litellm

# 验证安装
adk --version

2. 创建智能体项目

bash 复制代码

# 创建项目
adk create ziyi_agent

创建后的项目结构如下，其中 agent.py 文件包含智能体的主要控制代码：

bash 复制代码

ziyi_agent/
├── agent.py          # 智能体主要控制代码
├── __init__.py       # 标识为 Python 包[reference:35]
└── ...

3. 更新智能体代码

agent.py 文件包含一个 root_agent 定义，这是 ADK 智能体所需的唯一元素。你可以定义工具供智能体使用，例如添加获取当前时间的工具。

4. 设置 API 密钥

adk默认接入的是Gemini模型，腾讯TokenHub最近有免费额度，为了方便，我这里演示国产deepseek模型。所以会用到litellm库，需要提前安装。

TokenHub免费刻度：https://console.cloud.tencent.com/tokenhub

安装litellm库，用于接入其他模型，如果前面已安装，则忽略

bash 复制代码

pip install litellm

复制自己的API Key

https://console.cloud.tencent.com/tokenhub/inference/detail/basic?id=deepseek-v4-flash\&regionId=1\&serviceType=TEXT_GENERATION

在终端中将 API 密钥写入 .env 文件：

bash 复制代码

echo "TENCENT_API_KEY=your_api_key_here" > .env

然后修改agent.py代码：

具体模型提供方可查看llm官网：https://docs.litellm.ai/docs/providers

main.py

python 复制代码

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from dotenv import load_dotenv
import os

# 加载 .env 文件
load_dotenv()

# 创建 LiteLlm 实例，并把 api_key 和 api_base 传给它
my_model = LiteLlm(
    model="tencent/deepseek-v4-flash",
    api_key=os.getenv("TENCENT_API_KEY"),          # 显式传递
    api_base="https://tokenhub.tencentmaas.com/v1" # 基础 URL，去掉 /chat/completions
)

# 定义 Agent，只传入 model
root_agent = LlmAgent(
    model=my_model,
    name="my_openai_agent",
    instruction="You are a helpful assistant powered by OpenAI.",
    # 不再写 api_key 和 api_base，因为已在 model 中配置
)

5. 运行智能体

ADK 提供两种运行方式：

**方式一：**命令行界面（CLI）

bash 复制代码

adk run ziyi_agent

**方式二：**Web 用户界面

bash 复制代码

adk web --port 8000

然后在浏览器访问 http://localhost:8000，在界面中选择智能体并输入请求进行交互。

⚠️ 注意：ADK Web 仅限开发使用，不适用于生产部署。

测试效果：

三、进阶

工业级 Agent 应用通常是多个 Agent 协作完成复杂任务。本节以 AI 渗透测试辅助为例，演示如何构建一个多 Agent 协同系统。

完整代码地址：https://github.com/ziyifast/Demo/tree/main/1-AI/ADK-Agent-Framework/penetration_agent

欢迎大家star⭐️~

部分代码为了方便，并未严格遵守企业级开发要求，主要是为了让大家知道完整Agent的开发流程。

1. 场景设计

Agent	职责	输入	输出
规划 Agent（Planner）	接收测试目标，拆解子任务，制定测试计划	目标 URL/IP	测试计划（子任务列表）
漏洞挖掘 Agent（Scanner）	执行具体的漏洞扫描任务	子任务描述	漏洞发现报告
评审 Agent（Reviewer）	验证漏洞真实性，评估风险等级	扫描报告	验证后的漏洞清单
报告 Agent（Reporter）	生成最终报告，包括修复建议	已验证漏洞	完整报告 + 修复建议

2. 实现

bash 复制代码

# 创建项目
adk create hack_agent


# 配置 .env 文件。在项目根目录创建 .env，填入你的API Key。如：腾讯 TokenHub API Key
TENCENT_API_KEY=sk-你的真实密钥

Step 1：定义工具函数

在 tools/ 目录下创建各个工具，比如我这里就创建出了漏洞报告、扫描工具，供AI进行渗透测试以及将渗透测试报告落地。

report_tool.py：渗透报告持久化落地

python 复制代码

import os
import datetime

def save_report(content: str) -> str:
    """
    将渗透测试报告保存到本地文件
    
    参数:
        content: 报告内容
        
    返回:
        保存结果信息
    """
    os.makedirs("reports", exist_ok=True)
    
    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
    report_file = f"reports/pen_test_report_{timestamp}.md"
    
    with open(report_file, "w", encoding="utf-8") as f:
        f.write(content)
    
    return f"报告已成功保存到: {report_file}"

scan_tool.py：执行渗透

python 复制代码

import requests
import re
from typing import Dict, List

def port_scan(target: str) -> str:
    """
    模拟端口扫描（真实环境中可使用nmap）
    
    参数:
        target: 目标地址（URL或IP）
    
    返回:
        扫描结果字符串
    """
    ports = [80, 443, 8080]
    result = f"端口扫描结果 - {target}\n"
    result += "=" * 50 + "\n"
    result += f"{'端口':<8} {'状态':<10} {'服务':<20}\n"
    result += "-" * 50 + "\n"
    
    for port in ports:
        try:
            if port == 443:
                url = f"https://{target.replace('http://', '').replace('https://', '').rstrip('/')}:{port}"
            else:
                url = f"http://{target.replace('http://', '').replace('https://', '').rstrip('/')}:{port}"
            
            response = requests.get(url, timeout=3)
            if response.status_code == 200:
                server = response.headers.get('Server', 'Unknown')
                result += f"{port:<8} {'开放':<10} {server:<20}\n"
            else:
                result += f"{port:<8} {'开放':<10} {'HTTP响应:'+str(response.status_code):<20}\n"
        except:
            result += f"{port:<8} {'关闭':<10} {'连接失败':<20}\n"
    
    return result

def detect_sqli(target: str) -> str:
    """
    检测SQL注入漏洞
    
    参数:
        target: 目标地址（URL）
    
    返回:
        漏洞检测结果
    """
    result = ""
    payloads = ["'", "' OR 1=1--", "' UNION SELECT 1,2,3--"]
    
    for payload in payloads:
        try:
            test_url = target + "?id=1" + payload
            response = requests.get(test_url, timeout=5)
            
            if response.status_code == 500:
                result += f"✓ 发现SQL注入漏洞！Payload: {payload}\n"
                result += f"   URL: {test_url}\n"
                result += f"   状态码: {response.status_code}\n"
                error_patterns = ["MySQL", "SQL syntax", "database error", "Warning:", "error in your SQL syntax"]
                for pattern in error_patterns:
                    if pattern.lower() in response.text.lower():
                        result += f"   检测到数据库错误信息: {pattern}\n"
                return result
            elif "mysql" in response.text.lower() or "error" in response.text.lower():
                result += f"✓ 可能存在SQL注入漏洞！Payload: {payload}\n"
                result += f"   URL: {test_url}\n"
                result += f"   状态码: {response.status_code}\n"
                return result
        except Exception as e:
            result += f"✗ 测试失败: {str(e)}\n"
    
    if not result:
        result = "未检测到SQL注入漏洞\n"
    
    return result
....

def detect_server_info(target: str) -> str:
    """
    检测服务器信息泄露
    
    参数:
        target: 目标地址（URL）
    
    返回:
        服务器信息
    """
    result = f"服务器信息检测 - {target}\n"
    result += "=" * 60 + "\n"
    
    try:
        response = requests.get(target, timeout=5)
        
        headers_to_check = ['Server', 'X-Powered-By', 'X-AspNet-Version', 'X-Cache']
        for header in headers_to_check:
            if header in response.headers:
                result += f"{header}: {response.headers[header]}\n"
        
        if 'Server' in response.headers:
            server = response.headers['Server']
            if 'Apache' in server or 'Nginx' in server or 'IIS' in server:
                result += f"\n警告: 服务器信息暴露可能被用于针对性攻击\n"
        
        result += f"\n页面标题: {re.search(r'<title>(.*?)</title>', response.text, re.IGNORECASE).group(1) if re.search(r'<title>(.*?)</title>', response.text, re.IGNORECASE) else '未找到'}\n"
        result += f"页面大小: {len(response.text)} 字节\n"
        
    except Exception as e:
        result += f"检测失败: {str(e)}\n"
    
    return result

def run_comprehensive_scan(target: str) -> str:
    """
    执行综合扫描，包含端口扫描、漏洞检测和信息收集
    
    参数:
        target: 目标地址（URL）
    
    返回:
        综合扫描结果字符串
    """
    result = f"{'='*70}\n"
    result += f"综合安全扫描报告 - {target}\n"
    result += f"{'='*70}\n\n"
    
    result += "[阶段1] 服务器信息收集\n"
    result += "-" * 40 + "\n"
    result += detect_server_info(target) + "\n"
    
    result += "[阶段2] 端口扫描\n"
    result += "-" * 40 + "\n"
    result += port_scan(target) + "\n"
    
    result += "[阶段3] SQL注入检测\n"
    result += "-" * 40 + "\n"
    result += detect_sqli(target) + "\n"
    
    result += "[阶段4] XSS检测\n"
    result += "-" * 40 + "\n"
    result += detect_xss(target) + "\n"
    
    result += "[阶段5] 目录枚举\n"
    result += "-" * 40 + "\n"
    result += directory_enumeration(target) + "\n"
    
    result += f"{'='*70}\n"
    result += "扫描完成\n"
    result += f"{'='*70}\n"
    
    return result

Step 2：创建各个子Agent

在 sub_agent 目录下创建各个子Agent，我这里暂时划分了四种，任务规划、报告输出、漏洞验证、渗透扫描。这里根据自己的需求来，Agent不应该太粗也不要太细，太粗体现不出分Agent的优势，幻觉概率较高，太细会导致整个项目比较复杂。下面给出planner_agen、scanner_agent代码示例：

planner_agent.py：

python 复制代码

from google.adk.agents import LlmAgent

def create_planner_agent(model):
    return LlmAgent(
        name="planner_agent",
        model=model,
        description="分析测试目标，制定渗透测试计划",
        instruction="""你是一名专业的渗透测试规划师。

**任务：**
根据用户提供的测试目标，分析目标系统的特点，制定详细的渗透测试计划。

**输入信息：**
用户消息中包含测试目标，请从中提取目标URL。

**测试计划应包含以下阶段：**
1. 信息收集阶段：识别目标系统的技术栈、端口、服务版本等信息
2. 漏洞扫描阶段：使用扫描工具检测已知漏洞
3. 漏洞验证阶段：对发现的潜在漏洞进行手动验证
4. 报告输出阶段：汇总测试结果，生成安全报告

**输出格式要求：**
请以结构化方式输出测试计划，包括：
- 目标分析摘要
- 测试阶段划分
- 每个阶段的具体任务
- 预计耗时

**重要：**
输出的测试计划中必须包含一个明确的 `target_url` 字段，格式为：`target_url: <目标URL>`
这个字段将被后续的扫描工具使用。

输出示例：
```
## 渗透测试计划

### 目标分析
目标系统：http://example.com
技术栈预测：Web应用（HTTP/HTTPS）
潜在攻击面：Web漏洞、服务器配置、API安全

target_url: http://example.com

### 测试阶段
1. 信息收集（预计15分钟）
   - 端口扫描
   - 服务指纹识别
   - 目录枚举
   - 子域名发现

2. 漏洞扫描（预计30分钟）
   - Web漏洞扫描（SQL注入、XSS、CSRF等）
   - 配置安全检查
   - 敏感文件检测

3. 漏洞验证（预计20分钟）
   - 手工验证高危漏洞
   - 确认漏洞可利用性
   - 评估漏洞影响范围

4. 报告输出（预计10分钟）
   - 汇总漏洞信息
   - 生成修复建议
   - 输出安全报告
```
""",
        output_key="test_plan",
        include_contents="default"
    )

output_key：将Agent的输出存储到Session State中，供后续Agent通过 {key} 引用。例如 scanner_agent 的 instruction 中使用了 {test_plan}，就是从 output_key="test_plan" 读取的。
include_contents：控制Agent在调用时包含哪些上下文内容（如对话历史、用户消息等）。主要有两类：
- default：包含完整对话历史，当前轮次及之前所有的对话、工具调用及其结果。
- none：仅包含当前轮次内容，仅当前用户输入、当前的工具调用及响应，不包含任何历史对话。

scanner_agent.py：

python 复制代码

import sys
import os

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from google.adk.agents import LlmAgent
from tools.scan_tool import run_comprehensive_scan

def create_scanner_agent(model):
    return LlmAgent(
        name="scanner_agent",
        model=model,
        description="执行漏洞扫描，检测目标系统安全漏洞",
        instruction="""你是一名专业的渗透测试工程师。

**任务：**
根据测试计划执行漏洞扫描，使用提供的扫描工具检测目标系统的安全漏洞。

**输入信息：**
测试计划：{test_plan}

**从测试计划中提取信息：**
请从测试计划中查找 `target_url:` 字段获取目标URL。

**可用工具：**
- run_comprehensive_scan(target): 执行综合扫描，包含端口扫描、Web漏洞扫描和目录枚举

**输出要求：**
1. 使用 run_comprehensive_scan 工具对目标进行扫描
2. 分析扫描结果，提取关键发现
3. 将扫描结果整理成结构化格式，包含：
   - 开放端口列表
   - 发现的漏洞清单（按严重程度排序）
   - 敏感目录和文件
   - 初步风险评估

**输出格式示例：**
```
## 扫描结果汇总

### 开放端口
| 端口 | 服务 | 版本 |
|------|------|------|
| 80 | HTTP | Apache/2.4.41 |
| 443 | HTTPS | Nginx/1.21.0 |

### 漏洞发现
1. [高危] SQL注入漏洞 - http://example.com/api/users?id= (CVSS: 8.5)
2. [高危] 路径遍历漏洞 - http://example.com/download?file=../../etc/passwd (CVSS: 7.5)
3. [中危] 跨站脚本攻击 - http://example.com/search?q= (CVSS: 6.1)

### 敏感路径
- /admin - 管理后台入口
- /backup - 备份文件目录
- /.git - Git版本控制目录

### 风险评估
综合风险等级：高
建议优先修复：SQL注入、路径遍历漏洞
```
""",
        tools=[run_comprehensive_scan],
        output_key="scan_results",
        include_contents="default"
    )

PS:此处仅展示部分子Agent，剩下的子Agent，大家可下载完整代码查看。

Step 3：编排工作流

ADK提供多种工作流，串行、并行、自定义流程等，渗透测试场景采用串行更合理。

参考资料：https://adk.wiki/workflows/

agent.py：

python 复制代码

from google.adk.agents import SequentialAgent

model = LiteLlm(
    model="tencent/deepseek-v4-flash",
    api_key=api_key,
    api_base="https://tokenhub.tencentmaas.com/v1"
)

logger.info("Model initialized successfully")

planner_agent = create_planner_agent(model)
scanner_agent = create_scanner_agent(model)
reviewer_agent = create_reviewer_agent(model)
reporter_agent = create_reporter_agent(model)

logger.info("All sub-agents created successfully")

root_agent = SequentialAgent(
    name="penetration_test_orchestrator",
    sub_agents=[
        planner_agent,
        scanner_agent,
        reviewer_agent,
        reporter_agent,
    ],
    description="渗透测试工作流编排器，按顺序执行任务规划、漏洞扫描、漏洞验证和报告输出"
)
    ......

Step 4：传递上下文数据

多 Agent 间需要通过 Session State 传递数据

agent.py：

python 复制代码

    ......
    
async def main():
    session_service = InMemorySessionService()
    runner = Runner(agent=root_agent, session_service=session_service, app_name="pen_test")
    
    print("=" * 60)
    print("          ADK 渗透测试 Agent")
    print("=" * 60)
    print()
    
    target = input("请输入测试目标URL（如 http://localhost/Less-1/）：").strip()
    
    while not target:
        print("错误：目标URL不能为空！")
        target = input("请输入测试目标URL：").strip()
    
    if not target.startswith(('http://', 'https://')):
        target = "http://" + target
    
    print(f"\n========== 渗透测试开始 ==========")
    print(f"测试目标: {target}")
    print()
    
    _ = await session_service.create_session(
        app_name="pen_test",
        user_id="test_user",
        session_id="test_session",
        state={}
    )
    
    user_message = Content(parts=[Part(text=f"请对 {target} 进行安全测试")])
    
    async for event in runner.run_async(
        user_id="test_user",
        session_id="test_session",
        new_message=user_message
    ):
        if event.content and event.content.parts:
            for part in event.content.parts:
                if part.text:
                    print(f"[{event.author}]:")
                    print(part.text)
                    print("-" * 80)
    
    print(f"\n========== 渗透测试结束 ==========")

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

3. 测试

方式一：命令行运行

bash 复制代码

# 进入hack_agent的父目录，然后执行
adk run hack_agent

# 输入目标
测试一下http://localhost/Less-2/网站是否存在漏洞

方式二：web方式执行

bash 复制代码

adk web --port 8000

# web页面输入（这个网址是我搭建的SQL靶场）
测试一下http://localhost/Less-2/网站是否存在漏洞

效果：

4. 完整代码

部分代码为了方便，并未严格遵守企业级开发要求，主要是为了让大家知道完整Agent的开发流程。

完整项目结构：

bash 复制代码

hack_agent/
├── .env
├── requirements.txt
├── agent.py                 # 主入口，编排所有Agent
├── tools/
│   ├── __init__.py
│   ├── scan_tool.py         # 扫描工具
│   └── report_tool.py       # 报告工具
├── sub_agents/
│   ├── __init__.py
│   ├── planner.py           # 规划Agent定义
│   ├── scanner.py           # 扫描Agent定义
│   ├── reviewer.py          # 评审Agent定义
│   └── reporter.py          # 报告Agent定义
└── reports/                 # 报告输出目录

完整代码地址：https://github.com/ziyifast/Demo/tree/main/1-AI/ADK-Agent-Framework/penetration_agent

欢迎大家star⭐️~

[AI]Agent开发——ADK框架使用