DeepSeek‑V4‑Flash 正式版 API 解析：Agent 工具调用原理与多场景落地

import os
import json
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),   # 推荐通过环境变量管理
    base_url="https://api.deepseek.com"        # DeepSeek API端点
)

# ========== 第一步：定义工具函数 ==========
def get_weather(city: str, units: str = "metric") -> str:
    """
    查询指定城市的天气信息。
    参数:
        city: 城市名称（如 "北京"）
        units: 温度单位，metric=摄氏度，imperial=华氏度
    """
    # 实际项目中这里调用真实天气API（如和风天气、高德天气）
    return f"{city}今天晴朗，气温25°C，湿度60%。"

# ========== 第二步：定义工具描述（供模型理解） ==========
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的当前天气信息，包括温度、天气状况和湿度。",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，使用中文，如 '北京'、'上海'、'广州'"
                    },
                    "units": {
                        "type": "string",
                        "description": "温度单位，'metric' 表示摄氏度，'imperial' 表示华氏度",
                        "enum": ["metric", "imperial"]
                    }
                },
                "required": ["city"]
            }
        }
    }
]

# ========== 第三步：发送请求，启用工具调用 ==========
messages = [
    {"role": "system", "content": "你是一个智能助手，可以根据需要调用工具来回答用户问题。"}
]

user_question = "北京今天天气怎么样？需要穿外套吗？"
messages.append({"role": "user", "content": user_question})

response = client.chat.completions.create(
    model="deepseek-v4-flash",     # V4-Flash正式版模型名
    messages=messages,
    tools=tools,
    tool_choice="auto",            # auto: 模型自主决定是否调用工具
    temperature=0.3,
)

assistant_message = response.choices[0].message
print(f"模型回复: {assistant_message}")
print(f"finish_reason: {response.choices[0].finish_reason}")

# ========== 第四步：解析工具调用 ==========
if assistant_message.tool_calls:
    print(f"\n检测到工具调用请求，共 {len(assistant_message.tool_calls)} 个")
    for tool_call in assistant_message.tool_calls:
        func_name = tool_call.function.name
        func_args = json.loads(tool_call.function.arguments)
        print(f"函数名: {func_name}")
        print(f"参数: {func_args}")

        # 执行工具
        if func_name == "get_weather":
            result = get_weather(**func_args)
            print(f"执行结果: {result}")

        # 将工具执行结果追加到消息历史（关键步骤！）
        messages.append({
            "role": "assistant",
            "content": None,
            "tool_calls": assistant_message.tool_calls
        })
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,    # 工具调用ID，必须与上面保持一致
            "name": func_name,
            "content": result
        })

    # ========== 第五步：将结果回传模型，生成最终回答 ==========
    final_response = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,
        tools=tools,
        temperature=0.3,
    )
    print(f"\n最终回答:\n{final_response.choices[0].message.content}")

import os
import json
from datetime import datetime
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

# 定义多个工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询城市天气",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string", "description": "城市名"}},
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_date",
            "description": "获取当前日期和时间",
            "parameters": {"type": "object", "properties": {}}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "搜索互联网获取最新信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "搜索关键词"}
                },
                "required": ["query"]
            }
        }
    }
]

# 工具执行映射
def execute_tool(func_name: str, args: dict) -> str:
    if func_name == "get_weather":
        return get_weather(**args)
    elif func_name == "get_current_date":
        now = datetime.now()
        return now.strftime(f"%Y年%m月%d日 %H:%M:%S")
    elif func_name == "web_search":
        # 实际项目中调用搜索API（DuckDuckGo/Bing等）
        return f"搜索结果：关于「{args['query']}」的最相关信息..."
    return "未知工具"

# Agentic Loop 主循环
def agent_loop(user_message: str, max_turns: int = 10):
    messages = [
        {"role": "system", "content": "你是一个有用的AI助手，可以调用工具来完成任务。"}
    ]
    messages.append({"role": "user", "content": user_message})

    for turn in range(max_turns):
        response = client.chat.completions.create(
            model="deepseek-v4-flash",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            temperature=0.3,
        )

        msg = response.choices[0].message

        # 直接回答（无需工具调用）
        if not msg.tool_calls:
            print(f"最终回答: {msg.content}")
            return msg.content

        # 执行所有工具调用
        messages.append({"role": "assistant", "content": None, "tool_calls": msg.tool_calls})

        for tc in msg.tool_calls:
            result = execute_tool(tc.function.name, json.loads(tc.function.arguments))
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "name": tc.function.name,
                "content": result
            })
        print(f"第 {turn+1} 轮：执行了 {len(msg.tool_calls)} 个工具调用")

# 使用示例
agent_loop("北京现在天气如何？今天几号？顺便查一下DeepSeek最新消息。")

{
  "cline": {
    "customProviders": {
      "deepseek-v4-flash": {
        "apiBaseUrl": "https://api.deepseek.com",
        "modelId": "deepseek-v4-flash",
        "apiKeyEnvVar": "DEEPSEEK_API_KEY",
        "supportsTools": true,
        "toolCallEnabled": true
      }
    },
    "defaultProvider": "deepseek-v4-flash"
  }
}

# 深度思考 + 工具调用组合配置
response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "user", "content": "帮我分析一下最近的AI大模型技术进展，并给出代码示例"}
    ],
    tools=tools,
    tool_choice="auto",
    # 深度思考参数（V4系列专用）
    extra_body={
        "thinking": {
            "reasoning_effort": "high"    # low / high / max
        }
    },
    temperature=0.3,
    max_tokens=4096,
)

print(f"回答: {response.choices[0].message.content}")
print(f"实际使用: 输入={response.usage.prompt_tokens}, 输出={response.usage.completion_tokens}")

# 研究助手：联网搜索 → 提取数据 → 生成报告
def research_agent(topic: str):
    """自动完成：搜索 → 整理 → 报告"""
    messages = [
        {"role": "system", "content": "你是专业研究助手，可以搜索互联网获取最新信息并整理成报告。"}
    ]
    messages.append({"role": "user", "content": f"帮我研究「{topic}」，包括：1）最新进展 2）主要玩家 3）发展趋势"})

    # 工具集
    tools = [
        {
            "type": "function",
            "function": {
                "name": "web_search",
                "description": "搜索互联网获取最新信息",
                "parameters": {
                    "type": "object",
                    "properties": {"query": {"type": "string"}},
                    "required": ["query"]
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "save_to_file",
                "description": "将内容保存到文件",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "filename": {"type": "string"},
                        "content": {"type": "string"}
                    },
                    "required": ["filename", "content"]
                }
            }
        }
    ]

    for turn in range(8):
        resp = client.chat.completions.create(
            model="deepseek-v4-flash",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            temperature=0.3,
        )
        msg = resp.choices[0].message

        if not msg.tool_calls:
            print(f"\n=== 最终研究报告 ===\n{msg.content}")
            return msg.content

        messages.append({"role": "assistant", "content": None, "tool_calls": msg.tool_calls})

        for tc in msg.tool_calls:
            args = json.loads(tc.function.arguments)
            # 实际项目中替换为真实工具实现
            result = f"[模拟执行 {tc.function.name}] 参数: {args}"
            messages.append({
                "role": "tool", "tool_call_id": tc.id,
                "name": tc.function.name, "content": result
            })
            print(f"执行: {tc.function.name}({args})")

research_agent("DeepSeek V4-Flash最新动态")

# 代码审查Agent：读取文件 → 分析代码 → 给出建议
def code_review_agent(repo_path: str):
    """对指定代码仓库进行自动化审查"""
    messages = [
        {"role": "system", "content": "你是一个专业的代码审查助手，可以读取代码文件并给出改进建议。"}
    ]
    messages.append({"role": "user", "content": f"请审查代码仓库：{repo_path}"})

    tools = [
        {
            "type": "function",
            "function": {
                "name": "read_file",
                "description": "读取代码文件内容",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string", "description": "文件路径"},
                        "max_lines": {"type": "integer", "description": "最多读取行数"}
                    },
                    "required": ["path"]
                }
            }
        },
        {
            "type": "function",
            "function": {
                "name": "run_command",
                "description": "在终端执行命令",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "cmd": {"type": "string"},
                        "cwd": {"type": "string"}
                    },
                    "required": ["cmd"]
                }
            }
        }
    ]

    # Agentic Loop
    for turn in range(20):
        resp = client.chat.completions.create(
            model="deepseek-v4-flash",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            temperature=0.3,
        )
        msg = resp.choices[0].message

        if not msg.tool_calls:
            print(f"\n=== 审查报告 ===\n{msg.content}")
            return msg.content

        messages.append({"role": "assistant", "content": None, "tool_calls": msg.tool_calls})

        for tc in msg.tool_calls:
            args = json.loads(tc.function.arguments)
            if tc.function.name == "read_file":
                result = f"已读取文件 {args.get('path')}"
            elif tc.function.name == "run_command":
                result = f"命令执行完成: {args.get('cmd')}"
            else:
                result = f"[未知工具: {tc.function.name}]"
            messages.append({
                "role": "tool", "tool_call_id": tc.id,
                "name": tc.function.name, "content": result
            })

code_review_agent("/path/to/your/project")