8 Tips for Writing Effective Agent Instructions

编写高效 AI Agent 指令的 8 个技巧

AI agents are used in many industries for various use cases — ranging from customer service and support to human resources to invoice processing. At their core, AI agents are software programs powered by a LLM that autonomously complete goals. They do this by breaking down complex tasks, and using tools and knowledge bases to execute action without step-by-step human intervention.

AI Agent（人工智能体）被广泛应用于各行各业的多种场景中，从客户服务与支持、人力资源管理到发票处理，不一而足。其核心本质是由大语言模型（LLM）驱动的软件程序，能够自主完成目标。它们通过拆解复杂任务，并利用工具和知识库来执行操作，无需人类进行分步干预。

When it comes to building AI agents there are a few key components, including:

Large language model (LLM) – this is the “brain” or the “processor” of the AI agent. The LLM is used to process information, reason, and make decisions.
System instructions – i.e. the playbook. The instructions define the agent’s goals, objectives & behavior.
Tools – which are like the hands of the agent — they are things the AI agent can do / the actions it can take.
Short term chat history – this is context that’s held during an active conversation with the AI agent. Think of this as a whiteboard you would use to jot down ideas during a meeting — it’s available for the duration of the conversation, but not for new conversations afterwards.
Long term memory – via external databases, like Milvus for RAG. Think of these database like a bookshelf, or a library, for the AI agent. They provide additional knowledge the agent may not otherwise have.

构建 AI Agent 时，有几个关键组件，包括：

大语言模型 (LLM)：这是 AI Agent 的“大脑”或“处理器”。LLM 用于处理信息、进行推理并做出决策。
系统指令 (System instructions)：即“行动手册”。这些指令定义了 Agent 的目标、任务和行为准则。
工具 (Tools)：就像 Agent 的“双手”，是 AI Agent 可以执行的操作或采取的行动。
短期聊天记录 (Short term chat history)：这是在与 AI Agent 进行活跃对话时保留的上下文。可以将其想象成会议中用来记录想法的白板——它仅在对话期间有效，不会延续到后续的新对话中。
长期记忆 (Long term memory)：通过外部数据库（如用于 RAG 的 Milvus）实现。可以将这些数据库想象成 AI Agent 的书架或图书馆，它们提供了 Agent 本身可能不具备的额外知识。

While all of these components are important for an AI agent, the playbook — i.e. the instructions — is what ties it all together. Without good instructions, your agent has no direction. No direction to tie together the brain, the memory, and the tools to perform those complex tasks and take action. When it comes to writing instructions for agents, teams often struggle to make it easy to read, modify, and maintain long-term. Below are a few tips I’ve picked up along the way for writing effective agent instructions.

虽然所有这些组件对 AI Agent 都很重要，但“行动手册”（即指令）是将它们串联在一起的核心。没有好的指令，Agent 就没有方向，无法将大脑、记忆和工具整合起来去执行复杂的任务。在编写 Agent 指令时，团队往往难以做到易于阅读、修改和长期维护。以下是我在实践中总结出的编写高效 Agent 指令的几个技巧。

Tip #1: Draw it out — create a flow chart of the business process and the agent workflow

技巧 1：画出来——创建业务流程和 Agent 工作流的流程图

Before you develop an agent and write instructions, it’s first important to understand the business process the agent is supposed to augment or enhance. Work with your business stakeholders to understand the current workflow. Then create a flow chart to define the high level steps and components. You’re probably thinking, a flow chart? Really? And yes, really, a flow chart. Creating a visual, such as a flow chart, is imperative when designing and developing agents across large teams. Flow charts provide several benefits including: understanding the overall agent flow and the different tools and knowledge sources it should interact with, providing the ability to map back to business requirements, helping the team debug issues, mapping decision points, and most importantly, ensuring team alignment. draw.io and Mermaid.js are great tools to create these visuals.

在开发 Agent 和编写指令之前，首先要理解 Agent 旨在增强或优化的业务流程。与业务相关方合作，了解当前的工作流，然后创建一个流程图来定义高层级的步骤和组件。你可能会想：流程图？真的吗？是的，确实需要。在大型团队中设计和开发 Agent 时，创建可视化图表（如流程图）至关重要。流程图有诸多好处，包括：理解整体 Agent 流程及其应交互的各种工具和知识源、能够映射回业务需求、帮助团队调试问题、明确决策点，以及最重要的一点——确保团队目标一致。draw.io 和 Mermaid.js 是创建这些可视化图表的绝佳工具。

Tip #2: Use AI developer tools to assist with writing, refining, and updating instructions

技巧 2：使用 AI 开发工具辅助编写、优化和更新指令

Whether you are creating a single agent, or multi-agent system, using AI developer tools, such as IBM Bob, can help speed up the process of writing, refining, and updating agent instructions. Similar to how you would work with a peer, AI tools can help with catching mistakes and ensuring consistency, especially as the length of the agent instructions grows. These AI tools are helpful for debugging as well. If you find an agent is not performing as expected, try analyzing the instructions with an AI tool to help detect any potential issues. When using AI tools to write and update instructions, review the output before accepting any changes. Additionally, provide general guidance and rules for the tool in regards to how the instructions should be written.

无论你是创建单个 Agent 还是多 Agent 系统，使用 AI 开发工具（如 IBM Bob）都可以加快编写、优化和更新 Agent 指令的过程。就像与同事协作一样，AI 工具可以帮助发现错误并确保一致性，特别是在 Agent 指令篇幅变长时。这些 AI 工具对调试也很有帮助。如果你发现 Agent 的表现不如预期，可以尝试用 AI 工具分析指令，以检测潜在问题。在使用 AI 工具编写和更新指令时，请在接受任何更改前仔细审查输出结果。此外，应为工具提供关于指令编写方式的通用指导和规则。

Tip #3: Design for failure, uncertainty, and boundaries

技巧 3：为失败、不确定性和边界进行设计

While agents handle tasks autonomously, it’s important to remember, in the real world, agents won’t always encounter a “happy path”. Which is why it is key to design agent instructions in a way that they can handle failures and uncertainty, and have clear boundaries. What should the agent do when the “happy path” breaks? When writing agent instructions, the following list highlights some questions and scenarios to consider in how the agent addresses fallbacks: How should the agent handle tool failures? How should the agent handle scenarios where the knowledge base or tool doesn’t return the expected information? Or any information? How many times should an agent retry a task that has failed? When should the agent escalate? When any sort of error occurs, what information is passed back to the user?

虽然 Agent 可以自主处理任务，但必须记住，在现实世界中，Agent 并不总能遇到“理想路径”（Happy Path）。因此，关键在于设计指令时要考虑到如何处理失败和不确定性，并设定明确的边界。当“理想路径”中断时，Agent 该怎么办？在编写指令时，以下列表列出了一些需要考虑的问题和场景，以确定 Agent 如何处理回退（Fallback）：Agent 应如何处理工具故障？当知识库或工具没有返回预期信息（或根本没有返回信息）时，Agent 该如何处理？任务失败后 Agent 应重试多少次？何时应将任务升级（人工介入）？当发生任何类型的错误时，应向用户反馈什么信息？

Tip #4: Add descriptions and clear guidance for tools and knowledge bases

技巧 4：为工具和知识库添加描述和明确的指导

For agents that use tools and knowledge bases, write instructions to help the agent select the correct one depending on the task at hand. In the agent’s instructions, when calling a tool or knowledge base, reference it by name. (Ideally, when you create the tool or knowledge base, provide a descriptive name. This will provide the agent with more context on what that tool or knowledge base is intended for). Additionally, when calling a tool, explicitly state what parameters are required to call the tool, and how the agent should handle information that comes back from the tool output. Similarly, for any knowledge bases your agent has access to, in the instructions address what should be returned from the knowledge base, how it should be used going forward in the workflow, and what to do in cases where no output is returned.

对于使用工具和知识库的 Agent，编写指令以帮助其根据当前任务选择正确的工具或知识库。在 Agent 指令中调用工具或知识库时，请使用名称引用它们。（理想情况下，在创建工具或知识库时，提供一个描述性的名称，这将为 Agent 提供更多关于该工具或知识库用途的上下文）。此外，在调用工具时，明确说明调用该工具所需的参数，以及 Agent 应如何处理工具输出返回的信息。同样，对于 Agent 可访问的任何知识库，在指令中应说明应从知识库返回什么内容、在后续工作流中应如何使用这些内容，以及在没有返回输出时该如何处理。