第十一章: Function Calling和Agent Skills两种方案获取天气信息对比

0 阅读14分钟

  现在让我们通过一个真实的代码示例,直观感受 Function Calling 和 Agent Skills 的区别。我们选择一个经典任务:获取天气信息。

  这个任务看似简单,但足以体现两种技术的核心差异:代码量、灵活性、维护成本、执行确定性。

任务说明

  我们要实现一个能力:根据用户的请求,获取指定城市的天气信息。用户可能会这样问:

  • "北京今天天气怎么样?"

  • "帮我查一下上海的天气"

  • "明天适合出门吗?"(需要根据当前位置获取天气)

  让我们分别用 Function Calling 和 Agent Skills 来实现,然后对比它们的差异。

方案一:Function Calling 实现

  使用 Function Calling,我们需要完成四个步骤:定义函数签名、实现函数逻辑、调用 OpenAI API、处理返回结果。

步骤一:定义函数签名

  首先,我们需要用 JSON Schema 定义函数的签名,告诉 AI 这个函数接受什么参数、返回什么结果。

定义 get_weather 函数的签名

weather_function = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称,例如:北京、上海"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "温度单位"
                }
            },
            "required": ["location"]
        }
    }
}

  这个定义看起来很严谨,但也很繁琐。每个参数都需要明确类型、描述、是否必需。如果需求变化(比如增加"空气质量"参数),你需要修改这个 Schema。

步骤二:实现函数逻辑

  接下来,我们需要实现真正获取天气的函数。这里我们用一个简化的实现(实际项目中需要调用真实的天气 API)。

import json
import random

def get_weather(location, unit="celsius"):
    """
    获取指定城市的天气信息

    Args:
        location: 城市名称
        unit: 温度单位(celsius 或 fahrenheit)

    Returns:
        JSON 格式的天气信息
    """
    # 模拟天气数据(实际应该调用真实的天气 API)
    weather_data = {
        "location": location,
        "temperature": random.randint(15, 30),
        "unit": unit,
        "condition": random.choice(["晴天", "多云", "小雨", "阴天"]),
        "humidity": random.randint(40, 80),
        "wind_speed": random.randint(5, 20)
    }

    return json.dumps(weather_data, ensure_ascii=False)

  这段代码很标准,但也很"工程化"。你需要处理参数验证、错误处理、返回格式等细节。

步骤三:调用 OpenAI API

  现在,我们需要将函数注册到 OpenAI API,并处理用户请求。

import os
from dotenv import load_dotenv
from openai import OpenAI

# 从项目根目录的 .env 文件加载环境变量(DEEPSEEK_API_KEY 等)
load_dotenv()

# 测试连接
client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)
model="deepseek-chat"

def chat_with_weather(user_message):
    """
    处理用户的天气查询请求
    """
    # 第一次调用:让 AI 决定是否需要调用函数
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": user_message}],
        tools=[weather_function],
        tool_choice="auto"
    )

    # 检查 AI 是否决定调用函数
    if response.choices[0].message.tool_calls:
        tool_call = response.choices[0].message.tool_calls[0]
        function_args = json.loads(tool_call.function.arguments)

        # 调用我们的函数
        function_response = get_weather(
            location=function_args.get("location"),
            unit=function_args.get("unit", "celsius")
        )

        # 第二次调用:将函数结果传回给 AI
        second_response = client.chat.completions.create(
            model=model,
            messages=[
                {"role": "user", "content": user_message},
                response.choices[0].message,
                {
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": function_response
                }
            ]
        )

        return second_response.choices[0].message.content
    else:
        return response.choices[0].message.content

  注意这里的复杂度:我们需要调用 API 两次(第一次让 AI 决定调用函数,第二次将结果传回),需要处理 tool_calls、解析参数、构造消息历史。这些都是"必要的复杂度",但也增加了维护成本。

步骤四:测试运行

测试

user_query = "北京今天天气怎么样?"
result = chat_with_weather(user_query)
print(result)
根据查询结果,北京今天的天气情况如下:
**天气状况:** 晴天
**温度:** 25°C 
**湿度:** 59% 
**风速:** 13 km/h 
今天北京天气晴朗,温度适中,是个不错的天气。
如果您要外出,建议可以适当防晒,因为晴天紫外线可能较强。这样的温度和湿度也比较舒适,适合户外活动。

  Function Calling 的优势在于:执行是确定性的,给定相同的输入,一定会调用相同的函数,返回结构化的数据。但代价是:需要写大量的代码,需要处理很多技术细节。

方案二:Agent Skill 实现

  现在让我们看看用 Agent Skills 如何实现同样的功能。你会发现,代码量大幅减少,而且更容易理解和维护。

步骤一:创建 SKILL.md

  我们只需要创建一个 Markdown 文件,用自然语言描述这个能力。

---
name: get-weather
description: 获取指定城市的天气信息。在用户询问当地的天气、实时气温或出门户外状况时使用(触发)。
---

# 获取天气信息 (Get Weather Information)

## Goal
针对用户询问的任何城市天气,提取其诉求从而提供能够给到帮助信息的准确天气预报结果集。

## Workflow
1. **提取位置信息 (Extract location)**: 从用户的请求大意中识别出城市名称
   - 如果用户说"今天"或"这里",尝试从对话上下文中推断出其具体地理位置
   - 如果用户输入的位置包含歧义或不明确,请主动向用户询问以确认精准地点

2. **获取天气数据 (Fetch weather data)**: 调取当地当前最新的天气气象信息
   - 温度情况数据 (若无指定,默认使用摄氏度展示)
   - 天气云图与降水状况 (晴天、多云天气、下雨等)
   - 气象局播报的相对湿度和风速数据
   - 实时空气质量指数信息 (前提是调用的数据源支持呈现)

3. **格式化响应 (Format response)**: 以自然人说话、易读亲和的对话口吻展示综合天气信息
   - 对于一般简单的查询:只提供极度核心的基础信息 (气温 + 天气基本状况)
   - 对于相对细节的查询:向用户进一步补充湿度走势、风速以及相关的外出建议
   - 被问及户外相关问题时:结合当前恶劣或良好天气,主动给出户外活动的可行性与意见

4. **异常边界处理 (Handle edge cases)**:
   - 若系统内外部因素导致天气数据无法获取:向用户解释无果的客观原因,并建议其他获取方法
   - 若用户询问关于未来的长远天气预测:及时澄清当前服务能力仅包含提供实时的天气数据
   - 若用户正在比对多个不同城市环境:分别为每个不同城市分头拉取数据,随后整合给出一份横向对比报告

## Constraints
- 除非用户在请求中明确要求使用"华氏度"为口径,否则强制一律默认使用摄氏度呈现
- 严格保证只对外提供该需求时间的最新天气数据,绝对不做未经授权的长时间未来预测
- 遇到诸如强沙尘暴/大雾等代表空气环境非常差的天气,即便用户没查,强制要求主动发声提醒
- 全局把控输出的结果文字量,务必保证回复内容高度精炼而不失关键数据信息量

## Examples

**Example 1: 简单的单次查询**
User: "北京今天天气怎么样?"
Response: "北京今天晴天,温度 25°C,空气质量良好,适合外出活动。"

**Example 2: 多城市对比查询**
User: "帮我对比一下北京和上海的天气"
Response: "北京:晴天,25°C;上海:多云,28°C。上海温度更高一些,但两地都适合出行。"

**Example 3: 带有隐喻场景意图的延伸活动建议**
User: "明天适合出门旅游吗?"
Response: "根据当前天气(明天晴天,25°C),这应该是一个非常棒的天气,很适合出远门呼吸新鲜空气。不过中午时分紫外线偏强,建议临走前带上一顶鸭舌帽或者防晒霜。"

  就这样,我们完成了!整个 Skill 只有一个 Markdown 文件,大约 50 行,而且全部是自然语言描述。

步骤二:自然语言调用

  使用这个 Skill 非常简单,用户只需要自然地提问:

用户:"北京今天天气怎么样?"
Agent:识别到 get-weather Skill
Agent:按照 Workflow 执行
Agent:返回结果

openai的框架调用

# 导入的本地的agent_skills_engine.py文件里面的逻辑
from agent_skills_engine import AgentSkillsEngine

# 初始化引擎(指向你的 Skills 目录)
engine = AgentSkillsEngine(skills_dir="./skills")

# 测试 1: 天气查询
print("=" * 60)
print("测试 1: 天气查询")
print("=" * 60)
result, skill = engine.process("北京今天天气怎么样?")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 2: 多城市对比
print("=" * 60)
print("测试 2: 多城市对比")
print("=" * 60)
result, skill = engine.process("帮我对比一下北京和上海的天气")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 3: 无法匹配的请求
print("=" * 60)
print("测试 3: 无法匹配的请求")
print("=" * 60)
result, skill = engine.process("帮我写一首诗")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 列出所有可用的 Skills
print("=" * 60)
print("所有可用的 Skills:")
print("=" * 60)
for skill_name in engine.list_skills():
    print(f"- {skill_name}")
初始化 Agent Skills Engine... 📂 

扫描 Skills 目录: skills 🔍 
找到 2 个 Skill 文件 

加载 Skill: code-explainer 
描述: 解释代码的功能和实现逻辑。在用户询问代码含义、代码分析、代码理解时使用(触发)。... 
触发条件: 用户询问代码含义、代码分析、代码理解 

加载 Skill: get-weather 
描述: 获取指定城市的天气信息。在用户询问当地的天气、实时气温或出门户外状况时使用(触发)。... 
触发条件: 用户询问当地的天气、实时气温或出门户外状况 🎉 

成功加载 2 个 Skills 

Agent Skills Engine 初始化完成 ============================================================ 
测试 1: 天气查询 
============================================================ 
用户输入: 北京今天天气怎么样? 
正在路由到合适的 Skill... 
🔍 模型返回的原始内容: 'get-weather' 
🔍 注册表中的 Skills: ['code-explainer', 'get-weather'] 
选择 Skill: get-weather
...

所有可用的 Skills: ============================================================
- code-explainer
- get-weather

langchain的框架调用

# 导入的本地的agent_skills_engine_langchain.py文件里面的逻辑
from agent_skills_engine_langchain import AgentSkillsEngine

# 初始化引擎(指向你的 Skills 目录)
engine = AgentSkillsEngine(skills_dir="./skills")

# 测试 1: 天气查询
print("=" * 60)
print("测试 1: 天气查询")
print("=" * 60)
result, skill = engine.process("北京今天天气怎么样?")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 2: 多城市对比
print("=" * 60)
print("测试 2: 多城市对比")
print("=" * 60)
result, skill = engine.process("帮我对比一下北京和上海的天气")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 测试 3: 无法匹配的请求
print("=" * 60)
print("测试 3: 无法匹配的请求")
print("=" * 60)
result, skill = engine.process("帮我写一首诗")
print(f" AI 回复: {result}")
print(f" 使用的 Skill: {skill}\n")

# 列出所有可用的 Skills
print("=" * 60)
print("所有可用的 Skills:")
print("=" * 60)
for skill_name in engine.list_skills():
    print(f"- {skill_name}")
初始化 Agent Skills Engine (LangChain 1.0)...

扫描 Skills 目录: skills
找到 7 个 Skill 文件

加载 Skill: code-explainer
   描述: 解释代码的功能和实现逻辑。在用户询问代码含义、代码分析、代码理解时使用(触发)。...
   触发条件: 用户询问代码含义、代码分析、代码理解

加载 Skill: get-weather
   描述: 获取指定城市的天气信息。在用户询问当地的天气、实时气温或出门户外状况时使用(触发)。...
   触发条件: 用户询问当地的天气、实时气温或出门户外状况

加载 Skill: skill-creator-pro
   描述: Design, create, review, and iteratively improve high-quality...
   触发条件: Design, create, review, and iteratively improve high-quality AI skills with strong trigger definitions, progressive disclosure, reusable scripts/references/assets planning, validation rules, and anti-pattern avoidance. Use when asked to create a new skill, upgrade an existing skill, turn a repeated workflow into a reusable skill, review skill quality, or define skill design best practices.

加载 Skill: learning-path-architect
   描述: Design systematic learning paths for technical topics. Use w...
   触发条件: Design systematic learning paths for technical topics. Use when asked to create a learning roadmap, design a course structure, plan a study path, or organize knowledge from beginner to mastery. Analyzes topics through three perspectives (foundation, advanced cases, project practice) and produces sequenced learning plans with checkpoints and resources.

加载 Skill: get-weather
   描述: Get weather information for specified cities. Use this skill...
   触发条件: Get weather information for specified cities. Use this skill when the user asks about local weather, real-time temperature, or outdoor conditions (e.g., "What's the weather like?", "Is it raining?", "Should I bring an umbrella?").

加载 Skill: frontend-design
   描述: Create distinctive, production-grade frontend interfaces wit...
   触发条件: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

加载 Skill: verification-before-completion
   描述: Use when about to claim work is complete, fixed, or passing,...
   触发条件: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

成功加载 6 个 Skills

Agent Skills Engine 初始化完成

============================================================
测试 1: 天气查询
============================================================
用户输入: 北京今天天气怎么样?
正在路由到合适的 Skill...
路由结果: skill_name='get-weather'
注册表中的 Skills: ['code-explainer', 'get-weather', 'skill-creator-pro', 'learning-path-architect', 'frontend-design', 'verification-before-completion']
选择 Skill: get-weather

正在执行 Skill: get-weather...
执行完成

 AI 回复: 北京今天天气晴朗,气温为22°C,空气质量良好,适合户外活动。
 使用的 Skill: get-weather

============================================================
测试 2: 多城市对比
============================================================
用户输入: 帮我对比一下北京和上海的天气
正在路由到合适的 Skill...
路由结果: skill_name='get-weather'
注册表中的 Skills: ['code-explainer', 'get-weather', 'skill-creator-pro', 'learning-path-architect', 'frontend-design', 'verification-before-completion']
选择 Skill: get-weather

正在执行 Skill: get-weather...
执行完成

 AI 回复: 北京:晴朗,温度 25°C,空气质量良好,适合户外活动。

上海:多云,温度 28°C,湿度 65%,有微风。天气温暖舒适。

对比来看,上海比北京稍暖一些,湿度也更高,但两地目前的天气都非常适合出行。
 使用的 Skill: get-weather

============================================================
测试 3: 无法匹配的请求
============================================================
用户输入: 帮我写一首诗
正在路由到合适的 Skill...
路由结果: skill_name='NONE'
注册表中的 Skills: ['code-explainer', 'get-weather', 'skill-creator-pro', 'learning-path-architect', 'frontend-design', 'verification-before-completion']
路由失败: skill_name='NONE', 是否在注册表=False
没有找到合适的 Skill

 AI 回复: 抱歉,我无法处理这个请求。
 使用的 Skill: None

============================================================
所有可用的 Skills:
============================================================
- code-explainer
- get-weather
- skill-creator-pro
- learning-path-architect
- frontend-design
- verification-before-completion

对比总结

  现在让我们对比一下两种实现方式的关键差异:

Function Calling vs Agent Skills 实现成本对比

维度Function CallingAgent Skills差异说明
代码量~80 行 Python 代码~50 行 MarkdownSkill 代码量减少 40%
技术门槛需要熟悉 OpenAI SDK、JSON Schema只需要会写 MarkdownSkill 门槛低,非技术人员也能创建
修改成本需要改函数签名、代码、测试只需要改 Workflow 描述Skill 修改成本低 10 倍
灵活性固定的参数和返回格式可以处理模糊请求和多种场景Skill 更灵活
确定性高(相同输入→相同输出)中(依赖 AI 理解)Function Calling 更确定
调试难度需要调试代码和 API 调用主要调试 Workflow 逻辑Skill 调试更简单
扩展性增加功能需要改代码增加功能只需加 Workflow 步骤Skill 扩展更容易

  通过这个实战对比,我们可以清晰地看到:

  Function Calling 的优势: 执行确定性高,适合关键业务逻辑;返回结构化数据,便于后续处理;性能可控,可以精确优化。

  Agent Skills 的优势: 开发速度快,代码量少;维护成本低,易于迭代;灵活性高,可以处理多种场景;门槛低,非技术人员也能创建。

  选型建议: 如果你的任务需要精确控制(如金融交易、数据库操作),选择 Function Calling。如果你的任务需要灵活处理(如信息查询、内容生成),选择 Agent Skills。如果你的团队包括非技术人员,优先考虑 Agent Skills。如果你处于快速迭代阶段,先用 Agent Skills 验证,稳定后再考虑是否需要 Function Calling。

  记住:这两种技术不是互斥的,而是互补的。在实际项目中,你可以用 Agent Skills 处理高层工作流,用 Function Calling 处理底层精确操作,发挥各自的优势。