构建可靠的 AI Agent：结构化工作流与验证网关实战

从实验性的 LLM 封装器向生产级 AI Agent 的转变，标志着软件工程的一次重大范式转移。在 2024 年初，许多开发者还依赖于所谓的“玄学工程”——即简单地将提示词（Prompts）串联起来，并寄希望于输出结果能保持一致。然而，随着业务复杂度的增加，这种脆弱的提示词链（Prompt Chains）不可避免地会崩溃。本文将深入探讨如何通过结构化工作流、类型化 Schema 和严密的验证网关（Guardrails）来替代隐式的提示词链，从而构建不产生幻觉的可靠 Agent。

脆弱提示词链的失败逻辑

以一个标准的“研究型 Agent”为例。典型的实现可能包含 12 个顺序步骤：分解问题、规划搜索、执行工具、提取事实、合成答案等。当这些步骤以简单的链式结构运行时，系统往往只能达到 60% 左右的任务成功率。失败的原因通常是系统性的：

1. Schema 漂移：第 3 步返回了一个不符合预期格式的 JSON 对象，导致第 4 步直接崩溃。
2. 幻觉传播：如果第 5 步产生了一个虚假事实，第 6 步（事实检查）可能因为缺乏原始上下文而无法识别它。
3. 观测性缺失：当最终输出错误时，如果不手动检查 12 个步骤的所有日志，几乎无法确定是哪个环节出了问题。

为了解决这些问题，我们必须转向一种结构化架构，让每一次交互都受到“契约”的约束。使用像 n1n.ai 这样高性能的 API 聚合器，开发者可以根据每个具体步骤的需求，在 Claude 3.5 Sonnet 或 DeepSeek-V3 等不同模型之间灵活切换，从而找到性能与成本的最佳平衡点。

核心架构：结构化工作流

结构化 Agent 用显式的状态机（State Machine）取代了隐式的状态传递。每个步骤都由 Pydantic Schema 定义其输入和输出。这确保了在 LLM 调用之间流动的数据始终是经过验证且具有明确类型的。

1. 定义类型化 Schema

通过 Pydantic，我们可以强制执行 LLM 必须遵循的约束。这比简单地要求模型“返回 JSON”要健壮得多。

from pydantic import BaseModel, Field
from typing import Literal, Any

class DecomposeOutput(BaseModel):
    sub_questions: list[str] = Field(min_length=1, max_length=5)
    requires_tools: bool
    reasoning: str

class Fact(BaseModel):
    claim: str
    evidence: str
    source_url: str
    confidence: float = Field(ge=0, le=1)

通过定义这些 Schema，我们为 Agent 创造了一个“契约”。如果 LLM 的输出未能通过验证，我们可以立即捕获错误并触发自动重试或回退机制。对于需要高可用性来支持这些重试请求的开发者，n1n.ai 提供了统一的接口连接多个顶级模型，确保单一模型的停机不会导致整个 Agent 管线的瘫痪。

实现验证网关（Guardrails）

验证网关是阻塞性的检查点。如果当前步骤不符合特定标准，它将阻止 Agent 进入下一步。与提示词不同，验证网关通常是基于代码的，或者是使用更小、更专业的模型来验证主 Agent 的工作。

引用验证（Citation Validation）

在 RAG（检索增强生成）中，最常见的问题之一是虚假引用。引用验证网关会手动检查 LLM 引用的文本是否确实存在于检索到的文档中。

class CitationValidator(Guardrail):
    async def check(self, output: SynthesizeOutput, context: dict) -> bool:
        retrieved_docs = context.get("retrieved_docs", [])
        doc_text = " ".join(d.text for d in retrieved_docs)

        for citation in output.citations:
            if citation["text"] not in doc_text:
                return False  # 发现幻觉引用
        return True

安全与政策强制执行

通过 n1n.ai 调用专门的模型（如 GPT-4o-mini），你可以实现“安全网关”，在输出到达用户之前扫描其中的 PII（个人身份信息）或政策违规内容。

分步评估（LLM-as-a-Judge）

要实现 90% 以上的成功率，不能只评估最终结果，必须评估每一个中间步骤。这通常涉及使用一个“裁判”模型（通常是像 Claude 3.5 Sonnet 这样逻辑能力极强的模型）来对中间步骤的质量进行打分。

常见的评估维度：

• 忠实度 (Faithfulness)：事实是否由来源支撑？
• 完整性 (Completeness)：问题分解是否涵盖了用户查询的所有方面？
• 相关性 (Relevance)：规划的路径是否高效且具有针对性？

性能对比分析

从提示词链转向结构化 Agent 后，各维度指标都有了显著提升：

生产级 Agent 的专业建议 (Pro Tips)

1. 模型特化策略：使用“重型”模型（如 OpenAI o3）进行复杂规划，而使用“快速”模型（如 DeepSeek-V3）进行事实提取。你可以通过 n1n.ai 轻松管理这些多样化的 API 需求。
2. 确定性重试：当 Schema 验证失败时，将具体的错误信息传回给 LLM。现代模型在被告知 JSON 错误的具体原因后，通常能够自我修正。
3. 状态持久化：在每个步骤之后将 Agent 的状态存储在数据库中。如果某一步失败，你应该能够从最后一个成功的步骤恢复，而不是重新启动整个链路。
4. 黄金数据集 (Golden Sets)：维护一个包含 200 个以上输入及预期输出的黄金数据集。每当你修改提示词或 Schema 时，都要运行该数据集以防止功能退化（Regressions）。

总结

构建可靠的 AI Agent，重点不在于编写“完美的提示词”，而在于围绕 LLM 构建一套健壮的工程框架。通过使用 Pydantic 强制执行结构化输出、实施严格的验证网关以及对每个中间步骤进行评估，你可以将一个脆弱的原型转化为生产级的系统。借助 n1n.ai 提供的工具，你的 Agent 将能够以极高的速度和多模型冗余来执行这些复杂的规模化工作流。

在 n1n.ai 获取免费 API 密钥