ADK-Samples项目实战：实现Agent欢迎消息的两种技术方案

在基于ADK框架开发智能助手应用时，为Agent添加欢迎消息是提升用户体验的重要环节。本文将深入探讨两种不同的实现方案，帮助开发者根据实际需求选择最适合的技术路径。

方案一：回调函数实现法

这种方案利用ADK框架提供的回调机制，通过before_agent_callback参数实现欢迎消息。核心思路是：

1. 状态管理：通过检查state字典中的标记位，确保欢迎消息只显示一次
2. 消息构建：使用types.Content对象构造符合ADK规范的消息内容
3. 时机控制：在Agent初始化前触发回调函数

典型实现代码示例：

def welcome_callback(callback_context):
    state = callback_context.state  
    if not state.get("has_greeted"):
        state["has_greeted"] = True 
        return types.Content(
            role="assistant",
            parts=[types.Part(text="欢迎消息内容")]
        )
    return None

技术要点：

• 需要正确处理状态持久化
• 回调函数必须返回符合ADK内容规范的对象
• 适用于简单的静态欢迎消息场景

方案二：工具调用实现法

这是一种更灵活的实现方式，通过自定义Tool结合系统提示词来实现动态欢迎消息。该方案的优势在于：

1. 内容动态化：可以通过参数传递动态生成欢迎内容
2. 格式丰富：支持HTML等富文本格式
3. 流程可控：通过系统提示精确控制触发时机

实现包含三个关键部分：

1. 系统提示设计

# PROCESS FLOW
## PHASE 1 - FIRST USER ITERATION
1. **重要**：首次响应必须调用welcome_message_tool

2. Tool定义

def welcome_message_tool(desc, count, questions):
    # 构建HTML格式消息
    return {
        "html_response": formatted_message,
        "status": "ok"
    }

3. Agent配置

Agent(
    tools=[welcome_message_tool],
    instruction=SYSTEM_PROMPT
)

技术优势：

• 支持复杂的消息模板
• 可集成动态数据
• 便于维护和修改
• 适合需要本地化/国际化的场景

方案选型建议

对于简单场景，回调函数方案实现快速直接；当需要以下特性时，建议采用工具调用方案：

1. 欢迎消息需要包含动态内容
2. 要求特殊的消息格式（如HTML卡片）
3. 需要严格控制的触发逻辑
4. 未来可能扩展的复杂需求

无论采用哪种方案，都应注意消息的幂等性处理，避免重复显示问题。在ADK框架下，合理利用其提供的状态管理和回调机制，可以构建出既美观又实用的欢迎交互体验。