AI Agent 设计原则与最佳实践

Agent 设计准则

三大准则：

• 透明：让用户感知 Agent 的存在，以及其行为
• 可控：用户可以设置 agent的偏好，并对 Agent 进行指令，以及监控其行为
• 一致性：Agent 行为保持一致，避免用户对 Agent 行为产生困惑

透明性设计

透明性要求 Agent 在交互过程中清晰表达其意图、能力和限制：

• 身份标识：Agent 应该明确告知用户其 AI 身份，避免误导
• 能力边界：清楚说明 Agent 能做什么，不能做什么
• 决策解释：在做出重要决策时，提供简要的推理过程
• 状态反馈：及时告知用户当前正在执行的操作和进度

可控性实现

可控性确保用户能够有效指导和干预 Agent 的行为：

• 偏好设置：允许用户设置个人偏好，如语言风格、详细程度等
• 指令覆盖：用户指令应优先于 Agent 的默认行为
• 中断机制：提供暂停、撤销、重置等控制选项
• 监控面板：展示 Agent 的执行历史和决策依据

一致性保障

一致性避免用户产生困惑，建立可预期的交互体验：

• 行为模式：保持相似场景下的一致响应模式
• 语言风格：维持统一的沟通语气和专业程度
• 决策逻辑：避免自相矛盾的决策和建议
• 错误处理：统一优雅的错误提示和恢复机制

工具使用设计模式

工具使用分类：

• 动态信息检索
• 代码执行
• workflow 自动流
• 内容生成和编辑

agent 工具使用中需要实现的内容包括：

• function/tool schema 定义
• tool 执行逻辑实现
• 消息处理
• 工具集成框架
• 错误处理
• 状态管理

工具设计原则

Schema 设计最佳实践

schema 定义：告诉大模型工具的用途和用法：

# Function description for the model to read
tools = [
    {
   
   
        "type": "function",
        "function": {
   
   
            "name": "get_current_time",
            "description": "Get the current time in a given location",
            "parameters": {
   
   
                "type": "object",
                "properties": {
   
   
                    "location": {
   
   
                        "type": "string",
                        "description": "The city name, e.g. San Francisco",
                    },
                },
                "required": ["location"],
            },
        }
    }
]

工具命名规范

• 语义化命名：函数名应准确反映其功能，如 calculate_mortgage_payment
• 动词开头：使用动词+名词的结构，如 get_weather_data
• 避免歧义：避免使用可能产生多种理解的名称
• 保持一致：相似功能保持命名风格一致

参数设计原则

• 最小必要：只包含完成任务必需的参数
• 类型明确：明确定义每个参数的数据类型
• 默认值：为非必需参数提供合理的默认值
• 验证规则：在描述中说明参数的取值范围和格式要求

工具执行架构

tool 执行逻辑

def get_current_time(location):
    """Get the current time for a given location"""
    print(f"get_current_time called with location: {
     
     location}")  
    location_lower = location.lower()
    
    for key, timezone in TIMEZONE_DATA.items():
        if key in location_lower:
            print(f"Timezone found for {
     
     key}")  
            current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
            return json.dumps({
   
   
                "location": location,
                "current_time": current_time
            })
  
    print(f"No timezone data found for {
     
     location_lower}")  
    return json.dumps({
   
   "location": location, "current_time": "unknown"})

# Handle function calls
 if response_message.tool_calls:
     for tool_call in response_message.tool_calls:
         if tool_call.function.name == "get_current_time":

             function_args = json.loads(tool_call.function.arguments)

             time_response = get_current_time(
                 location=function_args.get("location")
             )

             messages.append({
   
   
                 "tool_call_id": tool_call.id,
                 "role": "tool",
                 "name": "get_current_time",
                 "content": time_response,
             })
 else:
     print("No tool calls were made by the model.")  

 # Second API call: Get the final response from the model
 final_response = client.chat.completions.create(
     model=deployment_name,
     messages=messages,
 )

 return final_response.choices[0].message.