Agentic TASK04 Practical Tips for Building Agentic AI

详细总结：代理式 AI 系统开发流程与迭代循环（ Development process summary ）编写软件和代码来改进系统。决定下一步将构建精力集中在哪里的过程，其重要性与构建相当。显然，开发是一个非线性的过程，需要在调整系统、错误分析、改进组件和调整评估之间反复横跳。许多经验不足的团队往往花太多时间在构建上，而太少时间在分析上，导致工作重点不集中，效率低下。在早期，市面上有许多工具可以

speoki

725人浏览 · 2025-11-19 20:58:55

speoki · 2025-11-19 20:58:55 发布

评估

在构建Agentflow/Workflow时，如何提升效果是个重要问题。而想提升效果，就要研究到底是哪个环节导致了效果变差——此时，就要请出我们的评估系统了。

构建评估测试集可以让你的Agent系统拥有客观的，可溯源的，易于扩展的评估方式。

【快速构建评估的方法论】此时，快速原型和迭代是关键。推荐采用快速而粗糙的迭代方法：

先构建一个非常简易，但功能完整的原型系统。
试运行并观察输出，找出表现不佳的地方。
利用观察结果来确定后续开发工作的优先级和方向，避免脱离实际过度空想。

案例一：发票处理工作流程（提取到期日）
在这里插入图片描述

本系统想要从发票中提取四个必填字段并保存，特别是到期日，用于及时付款。

通过手动测试并检查 10-20 张发票的输出，发现一个常见的出错点是系统混淆了发票的开具日期和到期日。

在这里插入图片描述

进而，我们需要改进系统以更好地提取到期日，并编写一个评估（Eval）来衡量日期提取的准确性。

具体怎么构建这个评估呢？

测试集： 找到 10-20 张发票，人工记录每个发票的正确到期日，作为正确对照。
标准化格式： 在提示词中要求 LLM 始终以固定的年-月-日格式输出到期日，便于代码自动检查。
评估方式： 编写代码（如正则表达式）提取日期，然后测试提取出的日期是否等于基本事实日期。
用途： 调整提示或其他系统组件后，用这个指标的变化来衡量准确率是否有提升。
总结一下我们的改进流程：构建系统 - 查看输出 - 发现错误 - 针对重要错误建立小型评估 - 调整系统以提高评估指标。

案例二：营销文案助理（限制字数）

本系统希望实现为 Instagram 图片生成标题，要求标题最多 10 个词。
通过观察输出，发现生成的文案内容还不错，但经常超过 10 个词的长度限制。
在这里插入图片描述

于是很显然的，我们就可以这样构建评估：

测试集： 准备 10-20 个测试任务，如太阳镜、咖啡机图片和对应的提示词。
评估方式： 编写代码计算输出的词数。
判断标准： 将生成的文本长度与 10 个词的目标限制进行比较。
与案例一的区别： 这个评估没有每个例子的基本事实，因为目标（10 个词）对所有例子都是一样的。

上面两个案例比较好做，因为AI输出可以被代码格式化，比如判断日期，判断长度。但是如果是“内容讲的对不对”这种比较抽象的评估，如何构建呢？我们来看下一个例子：

案例三：研究智能体（捕捉重要观点）

我们希望Agent能够根据用户输入的主题，如黑洞、机器人采摘，撰写研究文章。

通过检查输出，我们发现对于人类专家撰稿人会捕捉到的高知名度或重要观点，Agent生成的文章有时会遗漏。
在这里插入图片描述

所以我们可以这样构建评估：

测试集：针对每个场景，人工准备 3 到 5 个黄金标准讨论点作为每个例子的正确范例。
评估方式：由于提及这些观点的方式多种多样，简单的代码匹配不可行，因此使用 LLM 作为裁判员。
LLM 提示词：要求评判 LLM 统计文章中提到了多少个黄金标准点，并返回得分和解释。

以及重申一下本节提到过的技巧：

从快速而粗糙的评估开始： 不要因为觉得评估是一个大型项目，就不敢轻易建立，或者花漫长的时间去做理论调研。先用 10-20 个例子开始，快速获得一些指标来辅助人工观察。
迭代改进评估：
- 随着系统和评估的成熟，可以增加评估集的规模。
- 如果系统改进了但评估分数没有提高，意味着该改进评估本身了。
以专业人士的行为为灵感： 对于自动化人类任务的系统，观察系统在哪些方面性能不如人类专家，以此作为下一阶段工作的重点。

错误分析与制定下一步优先级

【错误分析的重要性】
但是，当Agent系统已经MVP，或者即将投入生产时，系统可能已经变得十分复杂。这时候如果仍像Demo阶段依赖直觉，就对直觉准度提出了极大的考验——到底是哪一环节出了影响效果的问题，或者还有提升空间？要不要单独拆出来跑？如果拆出来按单元跑，要不要Mock数据？如果系统需要经常更换底层LLM，风险就更大了。

所以，从一开始就将错误分析纳入计划，有利于在项目复杂化，工程化后仍能很好地管理。比如在多次测试后，发现总有一些组件或步骤很稳定，而另一些很容易受模型或输入格式的影响，这就帮助了我们深入理解系统，也能锻炼我们的Agent直觉。

【如何进行错误分析】

错误分析的核心是观察和量化，以找出工作流程中表现最差的组件。

检查追踪 (Traces) 和中间输出

定义： 代理在运行过程中，每一步产生的中间输出的整体集合被称为追踪 (【trace】)。单个步骤的输出有时被称为【span】。
方法： 查看追踪，观察每个步骤的输出质量，先笼统了解哪个组件出了问题。
示例： 比如针对一个科研资料查询的Agent
- 步骤 1： 生成搜索词 - 请人类专家判断搜索词是否合理。如果合理，则搜索关键字生成组件没问题。
- 步骤 2： 网页搜索结果 - 检查返回的 URL 和文章质量。如果返回了太多非科学的博客或大众媒体文章，则搜索引擎是问题所在。
- 步骤 3： 信息筛选 - 如果提供给LLM的文章有好有坏，但LLM选择了其中比较夺人眼球的水文，而不是严肃的科研文章，那LLM的型号或提示词就是问题所在。

聚焦错误案例并量化

聚焦错误：将精力集中在最终输出不令人满意的少数案例上，而不是那些运行良好的案例。
建立电子表格进行量化：为了更严谨地分析，可以建立一个电子表格，明确地统计每个组件出现“错误”的频率。
- 错误的定义：某一步的输出明显差于一个人类专家在给定相同输入时会给出的结果。
- 统计示例：记录在所有被分析的错误案例中，搜索词不佳的比例、搜索结果不佳的比例等。
- 指导决策：如果发现对搜索结果不满意的频率远高于对搜索词不满意的频率（如 45% vs 5%），那么工作重点就应放在改进网页搜索引擎或调整其参数上，而不是更改搜索词的生成逻辑。

组件级评估

端到端评估和组件级评估的关系有些类似端到端测试/集成测试与单元测试：

端到端评估成本高昂，即使是更换搜索引擎这样的小改动，都需要重新运行整个复杂的工作流程进行端到端评估，时间和金钱成本很高。同时，其他组件的随机性或噪声可能会掩盖被改进组件带来的微小、增量改进。
组件级评估更高效，信号更清晰，避免了整体系统的复杂性带来的噪声。还适用于团队分工：如果有多个团队分别负责不同组件，每个团队可以自行维护指标。

在这里插入图片描述

问题： 错误分析表明研究代理遗漏关键点的问题主要出在网页搜索组件上。
构建评估方法：
- 创建测试样例： 针对少数几个查询，请人类专家提供一份黄金标准网页资源列表，即最权威、最应该找到的网页。
- 编写评估代码： 使用信息检索领域的标准指标（如 F1 分数），编写代码来衡量网页搜索的输出列表与黄金标准列表之间的重叠程度。
用途：
- 利用这个指标，开发者可以快速高效地调整网页搜索组件的参数或超参数，如【更换搜索引擎、更改结果数量、调整日期范围】。
- 快速实现增量改进：在调优过程中，可以快速判断网页搜索质量是否提高。

组件级评估与端到端评估的关系与顺序如下：

通过【错误分析】确定一个问题组件（如网页搜索）。
构建和使用【组件级评估】来高效地进行调优和增量改进。
在调优后，运行最终的端到端评估，以验证组件的改进确实提升了整个系统的整体性能。

组件级评估

你将设计一个组件级评估，用于检查研究步骤返回的来源质量。

该评估会将代理检索到的 URL 与一份预定义的优选域名列表进行对比（例如：arxiv.org、nature.com、nasa.gov）。

该评估将以一个函数实现，执行客观的、按示例的检查：

解析 Tavily 的输出（我们的网页搜索工具）。
识别哪些 URL 属于优选域名列表。
计算优选来源占已检索来源的比例。
返回一个布尔标志（通过/未通过），以及可直接嵌入报告的 Markdown 格式摘要。

在这里插入图片描述

编写一个函数，检查网页搜索 API 的结果是否来自优选来源。
创建一个评估，用于验证你的来源是否来自优选域名。
将一个组件级评估加入网页搜索函数。

环境设置：导入库并加载环境

from datetime import datetime
import json
import re

# --- 第三方 ---
from aisuite import Client

# --- 本地 / 项目 ---
import research_tools
import utils

client = Client()

研究步骤：-find_references

在评分实验中，你实现的函数在同一步中同时完成了网页搜索与草稿报告撰写。

这里我们将网页搜索拆分为一个名为 find_references 的独立函数。这样你可以在不考虑撰写和反思步骤的情况下，单独评估搜索结果；本实验只关注网页搜索步骤的输出。
与评分实验的实现相比，这里有两个【关键差异】：

新函数使用 AISuite，它会为你自动管理工具调用（而不是用 OpenAI SDK 手写工具调用代码）。
该函数还会告知 LLM 当前日期，这有助于提升时间敏感查询的相关性。

find_references 的角色是从 Arxiv、Tavily 和 Wikipedia 等工具中收集外部信息。
由于这些结果的质量将直接影响评分实验的输出，因此这是可以应用评估方法的阶段——例如，检查返回的 URL 是否来自你的优选域名列表。

def find_references(task: str, model: str = "openai:gpt-4o", return_messages: bool = False):
    """使用外部工具（arxiv、tavily、wikipedia）执行研究任务。"""

    prompt = f"""
    你是一个研究函数，可以访问：
    - arxiv_tool：学术论文
    - tavily_tool：通用网页搜索（需要时返回 JSON）
    - wikipedia_tool：百科式摘要

    任务：
    {task}

    今天是 {datetime.now().strftime('%Y-%m-%d')}。
    """.strip()

    messages = [{"role": "user", "content": prompt}]
    tools = [
        research_tools.arxiv_search_tool,
        research_tools.tavily_search_tool,
        research_tools.wikipedia_search_tool,
    ]

    try:
        response = client.chat.completions.create(
            model=model,
            messages=messages,
            tools=tools,
            tool_choice="auto",
            max_turns=5,
        )
        content = response.choices[0].message.content
        return (content, messages) if return_messages else content
    except Exception as e:
        return f"[模型错误: {e}]"

client.chat.completions.create(
# │     │          └── 创建补全的方法
# │     └── 聊天补全的接口类别  
# └── aisuite客户端实例

completions是文本补全的意思，表示：

你给模型一段文本（messages）
模型补全剩下的内容
返回完整的对话结果

运行下面的单元以测试研究函数
该任务将检索两篇关于黑洞科学最新进展的论文，并显示结果。
主要是将tools注册到chat.completion.create这里。

response.choices[0].message.content
#        │        │ │       └── 实际文本内容
#        │        │ └── message对象（包含role和content）
#        │        └── 第一个（也是唯一一个）选择
#        └── 选择列表（通常只有1个元素）

choices[0]表示第一个（也是默认的唯一一个）响应
99%的情况下choices[0]就是你要的响应
只有当设置n>1参数时才会返回多个选择

response = {
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "这是助手的回复内容..."
            },
            "finish_reason": "stop"
        }
    ],
    "model": "gpt-4o",
    "usage": {...}
}

测试研究函数

research_task = "查找2篇关于黑洞科学最新进展的近期论文"
research_result = find_references(research_task)

评估步骤——优选域名

并非所有网页搜索检索到的来源都同样可靠
在本实验中，我们聚焦于上一份评分实验中的一个步骤——find_references 研究步骤——并展示如何设计一个组件级评估，用于检查返回的域名是否属于预定义的优选域名列表。

为什么需要组件评估？
这里的评估是客观的，因此可以用代码进行评估。它具有示例特定的真实标准——本次黑洞主题的优选来源列表。要构建该评估，你将：

提取 Tavily 返回的 URL。
将其与预定义的优选域名列表对比（例如 arxiv.org、nature.com、nasa.gov）。
计算优选结果与总结果的比例。
返回一个通过/未通过标志，并附带 Markdown 格式摘要。

# Tavily 结果的首选域名列表
TOP_DOMAINS = {
    # 通用参考 / 机构 / 出版方
    "wikipedia.org", "nature.com", "science.org", "sciencemag.org", "cell.com",
    "mit.edu", "stanford.edu", "harvard.edu", "nasa.gov", "noaa.gov", "europa.eu",

    # 计算机科学 / 人工智能领域会议与索引
    "arxiv.org", "acm.org", "ieee.org", "neurips.cc", "icml.cc", "openreview.net",

    # 其他权威出版源
    "elifesciences.org", "pnas.org", "jmlr.org", "springer.com", "sciencedirect.com",

    # 额外域名（针对特定情况）
    "pbs.org", "nova.edu", "nvcc.edu", "cccco.edu",

    # 知名编程网站
    "codecademy.com", "datacamp.com"
}

def evaluate_tavily_results(TOP_DOMAINS, raw: str, min_ratio=0.4):
    """
    评估纯文本研究结果是否主要来自首选域名。

    Args:
        TOP_DOMAINS (set[str]): 首选域名集合（例如 'arxiv.org', 'nature.com'）。
        raw (str): 包含 URL 的纯文本或 Markdown。
        min_ratio (float): 通过评估所需的最小首选比例（例如 0.4 = 40%）。

    Returns:
        tuple[bool, str]: (flag, markdown_report)
            flag -> True 表示通过，False 表示未通过
            markdown_report -> Markdown 格式的评估摘要
    """

    # 从文本中提取 URL
    url_pattern = re.compile(r'https?://[^\s\]\)>\}]+', flags=re.IGNORECASE)
    urls = url_pattern.findall(raw)

    if not urls:
        return False, """### Evaluation — Tavily Preferred Domains
未检测到任何 URL。
请在研究结果中包含链接。
"""

    # 统计首选域名与总数
    total = len(urls)
    preferred_count = 0
    details = []

    for url in urls:
        domain = url.split("/")[2]
        preferred = any(td in domain for td in TOP_DOMAINS)
        if preferred:
            preferred_count += 1
        details.append(f"- {url} → {'✅ 首选域名' if preferred else '❌ 非首选域名'}")

    ratio = preferred_count / total if total > 0 else 0.0
    flag = ratio >= min_ratio #判断是否到达最低阈值的要求
#评估指标：
	#总链接数: 检测到的URL总数
	#首选链接数: 来自权威域名的URL数量
	#比例: 权威链接占比
	#状态: 是否达到最低阈值要求

  # 生成 Markdown 格式的评估报告
    report = f"""
### 评估结果 — Tavily 首选域名
- 总链接数: {total}
- 首选链接数: {preferred_count}
- 比例: {ratio:.2%}
- 阈值: {min_ratio:.0%}
- 状态: {"✅ 通过" if flag else "❌ 未通过"}

**详细结果：**
{chr(10).join(details)}
"""
#chr(10)返回的是换行符\n
#将details列表中的每个URL评估结果用换行符连接起来
#生成格式化的列表输出，每个URL占一行
#确保Markdown报告的正确换行格式

    return flag, report

正则表达式：https?://: 匹配http://或https://
[^\s\]\)>\}]+：匹配非空白字符，非右括号、非右尖括号等
re.IGNORECASE：忽略大小写

域名质量评估逻辑

for url in urls:
    domain = url.split("/")[2]  # 提取域名部分
    preferred = any(td in domain for td in TOP_DOMAINS)
    if preferred:
        preferred_count += 1
    details.append(f"- {url} → {'✅ 首选域名' if preferred else '❌ 非首选域名'}")

域名提取：

url.split("/")[2]: 从https://arxiv.org/abs/1234提取arxiv.org
质量判断：
any(td in domain for td in TOP_DOMAINS)：检查域名是否包含任何首选域名片段

为什么这是客观评估：
从 Tavily 检索到的每个 URL 都会与预定义的优选域名(TOP_DOMAINS)进行对比:

若域名匹配 → ✓优选
否则 →x 非优选

是否通过取决于优选来源的比例是否超过设定阈值，因此会产生清晰的通过/未通过信号。由于每个示例的真实标准（优选 vs 非优选）都被明确定义，评估既客观又可复现。

解决识别到的问题

在跑了评估，找到问题后，就要开始着手修改了。本节介绍的正是如何改善系统中不同组件的效果。

对于非 LLM 组件，比如网页搜索、RAG 检索、代码执行、传统 ML 模型来说，改进方式非常多样。

调整参数或超参数：
- 网页搜索：调整结果数量、日期范围等。
- RAG 检索：更改相似度阈值、文本分块大小等。
- 人物检测：调整检测阈值，以权衡误报和漏报。
替换组件： 尝试更换不同的服务提供商，如不同的 RAG 搜索引擎、不同的 Web 搜索 API找到最适合系统的一个。按笔者经验，在国内查询企业营收报表和财务信息，使用百度搜索的效果就远超Bing或Google，但查询学术资源却完全相反。

对于LLM 组件，改进主要围绕【输入、模型本身和工作流程结构】展开。

**改进提示词：**增加明确指令（在提示词中指明一些资源和任务应有的规划路径，而不是让LLM自己猜）；使用少样本提示 (添加具体的输入和期望输出示例)
尝试不同的 LLM： 不要嫌麻烦，多测试几款 LLM，并使用评估 (Evals) 来选择最适合特定应用的最佳模型。
**任务分解：**如果单个步骤的指令过于复杂，导致 LLM 难以准确执行，考虑将任务分解为更小的、更易于管理的步骤，比如拆成生成步骤 + 反思步骤，或连续多次调用。
**微调模型：**这是最复杂、成本最高的选项。只有在穷尽所有其他方法后，仍需要挤出最后几个百分点的性能改进时才考虑。它适用于更成熟且性能要求极高的应用。

比如笔者对于当前时间节点（2025年11月初）的模型，就认为

Qwen比较嘴硬
Gemini2.5比较逆来顺受
GPT比较言简意赅，
DeepSeek比较有创意和鬼点子。不同模型擅长的领域也不一样，
【Gemini对一口气生成上千行代码非常在行】
【Claude对在现有系统里做小范围修改更有心得】
如果谈到具体任务，那么嘴硬的Qwen就更适合用作一些比较【严谨的】，比如数据报表查询场景。又比如非常有逻辑但容易过度自信的KimiK2，就能在【中低难度场景】以简短而有信服力的输出大放异彩，但在比较复杂的场景要做好它过于自信而出错的心理准备。

在模型层面以外，还有其他类型的直觉，比如在笔者感受中，大参数模型通常比小参数模型的【情商更高，对模糊指令的理解能力更强】。最典型的例子是今年年初发布的昂贵的GPT-4.5，甚至可以在时下流行的“山东饭局”风格高情商场景下讲出让人眼前一亮的回复。

又比如，新架构+大参数量的模型，一般在多步骤复杂指令的任务中，能够完美地列出并编辑所有敏感信息，而较小的模型容易出错或遗漏信息。

拥有对不同 LLM 能力的直觉，能使开发者更高效地选择模型和编写提示词。这样的直觉要如何培养？

频繁试玩不同模型： 经常测试新的闭源和开源模型，观察它们在不同查询上的表现。

笔者对自己的要求是，至少有3~5种主力使用的模型（同一提供商只计算一次），并保持一个月内至少使用过10种以上模型，并能报出20种以上模型的型号。

建立个人评估集： 使用一套固定的评估任务来校准不同模型的能力。
阅读他人的提示词： 大量阅读从业者、专家或开源框架中的提示词，了解不同任务/模型/场景下的最佳实践，提高自己编写提示词的能力。
在工作流程中尝试： 实际在Agent工作流程中尝试不同的模型，查看追踪 (【Traces】) 和【组件/端到端】评估，观察它们在特定任务中的性能、价格和速度的权衡。

代理式AI工作流程的成本与延迟优化(latency,cost optimization)

在系统输出质量达到要求后，下一个优化重点是：优化工作流程的延迟和成本。

需要强调的是，对于早期团队而言，[高质量的输出]，比延迟与价格重要得多，不应该首先把时间花在延迟与价格优化上。等系统已经运行良好之后，才应该将精力转向延迟优化；只有当系统有了大量用户，成本成了问题之后，才是开始集中优化成本的理想时机。

优化延迟与速度的方法

优化延迟的关键在于进行计时基准测试，找出工作流程中的瓶颈

在这里插入图片描述

计时分析： 详细记录工作流程中每个步骤所花费的时间（例如：LLM 1 耗时 7 秒，LLM 3 耗时 18 秒）。
定位瓶颈： 通过时间线分析，确定耗时最长的组件，从而确定最大的提速空间。
优化手段：
- 并行化： 考虑将一些像是网页抓取之类的，可以独立进行的步骤并行执行。
- 更换 LLM： 尝试使用更小、更快（尽管可能稍不智能）的模型，或者测试不同的 LLM 提供商，以找到返回 token 最快的服务。

优化成本的方法

优化成本的关键在于进行成本基准测试，找出最昂贵的步骤。
在这里插入图片描述

成本计算：计算工作流程中每个步骤的平均成本：
- LLM： 按输入和输出的 Token 长度收费。
- API： 按调用次数收费。
- 计算/服务：根据服务器容量、服务费等计算。
定位瓶颈：确定成本贡献最大的组件。
优化手段：寻找更便宜的组件或 LLM 来替代高成本的组件，以最大化成本优化机会。