AI Agent Tool Calling PromptsAI Agent 工具调用 Prompt
Tool calling prompts become harder to manage as agents connect to more APIs, schemas, and providers. This guide explains how layered prompts, RAG retrieval, and repair rules keep AI agent tool calling reliable at scale.
当 Agent 接入更多 API、schema 和 provider 后，工具调用 prompt 会越来越难维护。本文解释如何用分层 prompt、RAG 检索和修复规则，让 AI Agent 的工具调用在规模化后依然可靠。
Why Prompt Layering Matters for Tool Calling
为什么工具调用需要 Prompt 分层
The original QVeris blog argues that tool-calling systems should not rely on one long, generic prompt. When agents call hundreds or thousands of tools, each provider has different parameter conventions, field names, schemas, examples, and failure patterns. A single prompt eventually becomes hard to maintain, hard to debug, and easy to contradict.
QVeris 原始博客的核心判断是：工具调用系统不能长期依赖一个又长又通用的 prompt。当 Agent 需要调用数百甚至数千个工具时，不同 provider 会有不同的参数约定、字段名称、schema、样例和失败模式。单一 prompt 会越来越难维护，也更容易产生规则冲突。
The Three Layers: Global, Provider, Exact Tool
三层规则：全局、Provider、具体工具
Universal safety and intent rules. Never fake a repair, never replace the core object, and avoid changing user intent silently.
通用安全和意图规则：不能伪造修复成功，不能替换用户指定的核心对象，也不能悄悄改变用户意图。
Provider-specific conventions. A field fix may be safe for one API but an intent shift for another.
Provider 级别的约定：同样的字段修复在一个 API 中可能安全，在另一个 API 中可能已经改变查询意图。
Rules loaded by full tool_id: quote tools, balance sheet tools, news tools, or company overview tools all need different repair boundaries.
按完整 tool_id 加载规则：行情、资产负债表、新闻搜索、公司概览等工具需要不同的修复边界。
Retrieve documentation, past failures, examples, and risk labels for the current call.
根据当前调用检索文档、历史失败案例、样例参数和风险标签。
What This Design Solves
这种设计解决什么问题
Prompts stop growing linearly
Prompt 不再线性膨胀
Rules live in layers instead of one giant block. Teams can update provider or tool rules without rewriting the whole system prompt.
规则被放在不同层级，而不是堆进一个巨大的系统 prompt。团队可以单独更新 provider 或工具规则。
Tool repair becomes safer
工具修复更可靠
The agent can fix field names, formats, enum values, or types while preserving the user’s core query object.
Agent 可以修复字段名、格式、枚举值或类型，同时保留用户真正要查询的核心对象。
Historical failures become memory
历史失败变成经验
RAG lets the system reuse past repair examples and avoid repeating known bad fixes.
RAG 让系统复用历史修复案例，避免重复犯同样的错误。
Prompt Layering vs One Large Prompt
分层 Prompt 与单一大 Prompt 对比
| Approach | Strength | Risk |
|---|---|---|
| One large prompt | Simple to start | Becomes long, conflicting, and hard to update as tools grow |
| Layered prompts | Clear ownership of rules | Needs routing logic to know which layer to load |
| Layered prompts + RAG | Dynamic, maintainable, and experience-aware | Needs high-quality retrieval and risk labels |
Example Workflow for AI Agent Tool Repair
AI Agent 工具修复工作流示例
user intent -> discover candidate tool inspect schema -> retrieve provider rules retrieve exact tool rules -> retrieve historical repairs repair low-risk fields -> call tool -> validate output
This structure fits QVeris because QVeris already treats external capabilities as discoverable, inspectable, and callable units. Prompt layering adds a maintainable reasoning layer around those calls.
这个结构适合 QVeris，因为 QVeris 本身就把外部能力拆成可发现、可检查、可调用的单元。Prompt 分层是在这些调用外面增加一层可维护的判断机制。
Tool Calling Prompt Checklist
工具调用 Prompt 检查清单
Before a tool-calling agent enters production, teams should test whether the prompt stack protects user intent, loads only relevant provider rules, validates required parameters, and records why a repair was attempted. A prompt that fixes every failed call automatically can be dangerous; the system must know the difference between a harmless schema repair and a change to the financial object being queried.
工具调用 Agent 上线前，团队应该测试 prompt 栈是否能保护用户意图、只加载相关 provider 规则、验证必填参数，并记录为什么尝试修复。一个自动修复所有失败调用的 prompt 可能很危险；系统必须区分“无害的 schema 修复”和“改变被查询金融对象”。
Changing ticker to symbol may be safe. Replacing AAPL with a different company because the call failed is not.
把 ticker 改成 symbol 可能是安全修复；因为调用失败就把 AAPL 换成另一家公司则不是。
A production system should record which global, provider, or exact-tool rule shaped the final call.
生产系统应记录是哪条全局、provider 或具体工具规则影响了最终调用。
Related Reading for Reliable Tool Calling
可靠工具调用的相关阅读
Layered prompts work best when they sit next to capability discovery, schema inspection, and structured execution. Read the original QVeris blog for the prompt design pattern, then connect it to the QVeris docs when you are ready to implement discover, inspect, and call flows.
分层 prompt 与能力发现、schema 检查和结构化执行放在一起时效果最好。可以先阅读 QVeris 原始博客了解 prompt 设计模式，再结合 QVeris 文档实现 discover、inspect、call 流程。
Common Tool Calling Prompt Failures
常见工具调用 Prompt 失败模式
| Failure失败模式 | Example例子 | Repair rule修复规则 |
|---|---|---|
| Wrong field name字段名错误 | Agent sends ticker when the tool expects symbol.工具需要 symbol，但 Agent 发送 ticker。 | Allow schema-level repair if the company identity is unchanged.如果公司身份未变，可以允许 schema 级修复。 |
| Unsafe substitution不安全替换 | Agent replaces a missing ticker with a similar company.Agent 把缺失 ticker 换成类似公司。 | Stop and ask for clarification instead of changing the object.停止并询问澄清，而不是改变查询对象。 |
| Overloaded promptPrompt 过载 | One system prompt contains every provider rule and repair example.一个系统 prompt 塞进所有 provider 规则和修复案例。 | Retrieve only the rules relevant to the current tool and provider.只检索当前工具和 provider 相关规则。 |
When RAG Helps Tool Calling Prompts
RAG 什么时候能帮助工具调用 Prompt
RAG is useful when the agent needs recent documentation, known provider quirks, examples from past failures, or policy notes that are too specific to keep in a global prompt. It should not retrieve arbitrary text into the tool call. The retrieval layer should rank only documents that explain the current provider, the exact tool schema, or previous repairs for the same failure class.
当 Agent 需要最新文档、已知 provider 特性、历史失败样例或不适合写进全局 prompt 的策略说明时，RAG 很有价值。但它不应该把任意文本塞进工具调用。检索层应只排序当前 provider、具体工具 schema 或同类失败修复相关的文档。
A good implementation also records the retrieved rule IDs. That makes it possible to debug why the agent changed a parameter, skipped a call, or asked the user to clarify the request.
好的实现还会记录被检索到的规则 ID。这样团队才能调试 Agent 为什么修改参数、跳过调用，或者要求用户澄清请求。