Agent入门-Agent实战(skills\tools\prompt\subagents)

1.Agent背景知识

简单来说，开发 AI Agent 就像是雇佣了一个"懂操作手册的智能实习生"：我们通过Tool(工具) 给它安装了联网或读写文件的"手脚"，让它能够主动获取外部信息；通过 Skill(技能) 给它挂载了专业的"SOP操作手册"，让它遇到复杂问题时知道先查目录再按步骤执行，而不是胡乱猜测；而 Memory（记忆） 则像是一个随时翻阅的"书包"，让它能记住过往任务的背景和项目资料，从而不仅能"聊天"，更能结合你的特定需求去"做事"。这种将大脑（模型）、手脚（工具）、手册（技能）和书包（记忆）整合在一起的机制，它让 AI 从一个只会翻译文字的"书呆子"，进化成了能帮你查资料、写代码、跑测试的自动化执行者。

---

2.Agent小实战

在深入探讨原理之前，我们先通过一个简短的 Python 代码，直观感受一下什么是 Agent 。下面的代码展示了一个具备联网能力的 Agent：它在面对问题时，会自动触发 internet_search 工具，并像研究员一样撰写报告。

import os
import re
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent
from dotenv import load_dotenv

# 1. 初始化
load_dotenv()
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


# 2. 定义搜索工具 (增加了直观的控制台打印反馈)
def internet_search(
        query: str,
        max_results: int = 5,   #最大结果数
        topic: Literal["general", "news", "finance"] = "general",  #定义了搜索的范围，限制只能选 "general"（通用）、"news"（新闻）或 "finance"（金融）。这是为了让搜索引擎返回的内容更精准
        #决定是否下载网页的原始完整内容
        include_raw_content: bool = False,
):
    """
    当需要获取实时信息、技术文档或无法通过模型训练知识回答的问题时，使用此工具进行联网搜索。

    参数:
    query: 搜索关键词。
    max_results: 返回结果条数。
    """
    # 【直观感知点】：当 Agent 决定调用工具时，控制台会立刻打印这一行
    print(f"\n[🛠️ 工具调用触发] 正在向 Tavily 搜索引擎发起请求...")
    print(f"[🔍 搜索关键词]: {query}")

    result = tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

    print(f"[✅ 工具调用结束] 已获取 {len(result.get('results', []))} 条参考信息。")
    return result


# 3. 增强版系统提示词 (强制中文且要求报告深度)
research_instructions = """你是一名专家研究员，只能采用中会回答问题。你的工作是进行彻底的研究，然后撰写一份完善的报告。
你可以使用互联网搜索工具作为获取信息的主要手段。
## `internet_search`
使用此工具对给定查询进行互联网搜索。你可以指定返回的最大结果数、主题，以及是否包含原始内容。
"""

# 4. 创建 Agent (增加递归深度，给它更多空间完成搜索任务)
agent = create_deep_agent(
    model="ollama:qwen3:8b",
    tools=[internet_search],
    system_prompt=research_instructions,
)

# 5. 执行任务 (使用 config 参数增加运行上限)
print("🚀 Agent 正在启动...")
result = agent.invoke(
    {"messages": [{"role": "user", "content": "今天是几号？"}]},
    config={"recursion_limit": 15}
)


# 6. 清洗并展示结果
def get_clean_response(result):
    content = result["messages"][-1].content
    # 移除 <think> 标签
    clean_content = re.sub(r'<think>.*?</think>', '', content, flags=re.DOTALL).strip()
    return clean_content


print("\n" + "=" * 50)
print("📊 调研报告生成如下：")
print("=" * 50 + "\n")
print(get_clean_response(result))

运行后可以看到输出：

🚀 Agent 正在启动...

[🛠️ 工具调用触发] 正在向 Tavily 搜索引擎发起请求...
[🔍 搜索关键词]: 今天几号
[✅ 工具调用结束] 已获取 1 条参考信息。

==================================================
📊 调研报告生成如下：
==================================================

今天是2026年3月25日，星期三，农历二月初七，属马，星座为白羊座。需要了解当天的黄历信息或节日安排吗？

当你运行这段代码时，你会看到控制台跳出 [🛠️ 工具调用触发]------这一瞬间，你的 AI 不再仅仅是一个只会回复文本的"聊天机器人"，它已经进化成了一个会自主决策、会主动调用插件、会从互联网获取实时信息的"智能执行者"。

---

3.Tool（工具）是 Agent 的"可执行能力"

在 AI Agent 的开发中，Tool （工具） 是模型与外部世界交互的"接口" 。为了让新手快速理解，我们可以把 Tool 看作是 AI 的"外挂能力"。如果不给 AI 配置 Tool，它只能基于训练数据进行"闭门造车"，一旦遇到实时性问题（如"今天是几号？"），它往往会产生幻觉。通过下面的代码，我们能直观看到 AI 是如何感知并使用工具的：

# 工具的核心逻辑：定义一个函数，并用文档字符串 (Docstring) 告诉 AI 它的用途
def internet_search(
        query: str,                # 搜索内容
        max_results: int = 5,      # 限制结果数，防止 AI 吞掉太多 Token
        topic: str = "general",    # 搜索主题，让模型调用更精准
):
    """
    当需要获取实时信息或模型训练数据缺失时，使用此工具进行联网搜索。
    AI 通过读取此段文字（Docstring）来决定是否调用该函数。
    """
    # 【开发者视角】：监控 AI 的决策过程
    print(f"\n[🛠️ 工具调用触发] AI 决定使用互联网搜索: {query}")
    
    # 实际调用外部接口
    result = tavily_client.search(query, max_results=max_results, topic=topic)
    
    print(f"[✅ 工具调用结束] 已获取 {len(result.get('results', []))} 条参考信息。")
    return result

---

4.Prompt（系统提示词）如何影响 Agent 行为

如果说 Tool 是 Agent 的"工具箱"，那么 Prompt 就是定义它如何使用这些工具的"行为准则"。

research_instructions = """你是一名专家研究员，只能采用中文回答问题。你的工作是进行彻底的研究，然后撰写一份完善的报告。
你可以使用互联网搜索工具作为获取信息的主要手段。
## `internet_search`
使用此工具对给定查询进行互联网搜索。你可以指定返回的最大结果数、主题，以及是否包含原始内容。
"""

写好 Prompt 个人觉得有三个核心原则，这段代码全部涵盖了：

• 角色定义：明确角色能给模型设定"基调"。如果定义为"专家"，模型会倾向于使用逻辑严密、客观的语言；如果定义为"实习生"，模型可能会更谦虚、甚至带点求助色彩。
• 规则约束：AI 倾向于根据输入语言（通常是英文）输出。如果不强制约束，它可能在搜索结果是英文时，顺手直接回复英文。通过强力限制，你能保证 Agent 输出的稳定性
• 任务驱动的"工具说明书"(tool):尽管你在 Python 代码里定义了函数，但 Agent 的"大脑"是通过阅读这一段文本来理解"我手里有什么工具，什么情况下用哪把刷子"。你给工具的描述越详尽（包含参数说明、使用时机），Agent 就能越准确地决定在什么时候发起 internet_search

---

5.Skill（技能）机制

Skill 可以理解成**"操作手册 (SOP)"**，定义了完成一件事的流程：

from deepagents import create_deep_agent
from deepagents.backends.utils import create_file_data

# 1. 准备你的"技能手册" (内容就是一份 Markdown 文件)
skill_content = "# langgraph-docs \n 在回答问题时，必须查阅官方文档..."
skills_files = {"/skills/langgraph-docs/SKILL.md": create_file_data(skill_content)}

# 2. 创建 Agent，并把技能目录"插"进去
agent = create_deep_agent(
    skills=["/skills/"],  # 告诉 Agent：读取这个目录，自动习得里面的技能
)

# 3. 运行：Agent 会自动扫描并加载上面的 SKILL.md
result = agent.invoke({"files": skills_files}, ...)

随便展示一个skill的文档，便于理解：

---
name: tech-news-summarizer
description: 当用户询问最新的科技动态或新闻时，必须激活此技能。
---

# 科技新闻摘要技能

## 核心指令 (Instructions)

当你执行此技能时，请严格遵守以下步骤：

### 1. 精准搜索
使用 `internet_search` 工具，搜索词必须包含"2026 最新"以及用户提到的关键词。

### 2. 信息筛选
从搜索结果中挑选出最相关的 3 条内容。如果结果过多，优先选择发布时间最近的。

### 3. 固定格式输出
你必须按以下格式返回结果，严禁自行发挥：
- **标题**：[新闻标题]
- **核心点**：[用一句话概括]
- **传送门**：[链接地址]
---

上面的代码中，能体现skill优势：

• 没有这个 Skill，AI 可能会随便搜搜，然后回你一大段废话。有了 Skill，它被强制要求必须只给 3 条，且必须带链接。
• 所有的业务逻辑（步骤、格式、筛选规则）都写在 Markdown 文件里。这意味着，如果你想把"3 条新闻"改成"5 条"，你不需要改一行 Python 代码，只需要改一下那个 .md 文件。

工具（Tool）给它能力，技能（Skill）给它规矩，当你发现你的 Agent 总是"不听话"或者回答格式乱七八糟时，别急着改 Python 代码，试着给它写一个 SKILL.md，效果往往立竿见影。

---

6.Subagent（子 Agent）：把复杂任务拆给"专职助手"

我们习惯让一个 Agent 做所有事。但随着任务变复杂，Agent 的"脑容量"会不够用。Sub-agent 的核心逻辑就是"任务委派"。

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "openai:gpt-5.2",  # Optional override, defaults to main agent model
}
subagents = [research_subagent]

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    subagents=subagents
)

• 首先我们需要为每个特定的任务定义一个代理：

research_subagent = {
    "name": "research-agent",       # 它的工号
    "description": "用于深入研究复杂问题", # 关键！总经理根据这个描述决定什么时候派它出场
    "system_prompt": "你是一名伟大的研究员", # 它的性格和专业度
    "tools": [internet_search],      # 它的专业工具（主 Agent 不需要这把工具）
    "model": "openai:gpt-5.2",       # 给这个下属配一个专门的脑子
}

description 非常重要。如果用户问"今天天气"，主 Agent 发现你的描述是"研究复杂问题"，它可能就不会调用这个下属；但如果你问"量子计算的最新进展"，主 Agent 就会立刻把任务转交给 research-agent。

• 其次开始组件整个团队：

agent = create_deep_agent(
    model="claude-sonnet-4-6", # 大脑
    subagents=[research_subagent] # 子代理
)

当你发现一个任务需要好几步搜索、对比、总结才能完成时，不要再写一堆复杂的 Tool 了，试着给你的 Agent 雇佣一个"子代理"。

---

待更新...