How can we help?

This document outlines best practices for building and optimizing AI Agent Orchestration on the AI Agent Platform. 

• General Best Practices
  • Write clear, specific instructions without conflicts
  • Provide relevant examples in the instructions
  • Split complex tasks into simpler subtasks
  • Use Skills for structured tasks
  • Use variables to provide context
  • Leave variable assignment to Skills
  • Only share relevant information from variables
  • Test changes systematically
  • Monitor and iterate based on real usage
• Best Practices for Multi-AI Agent design
  • Define clear roles and responsibilities
  • Do not use a Routing Agent with only one Action Agent
  • Avoid reusing the same tool across multiple Agents
  • Response structuring should be done by the Supervisor
  • Use structured handoff between Agents
  • Test AI Agent collaboration scenarios

Before building in the AI Agent Platform, make sure you understand its core concepts. These include how Agents communicate, how they are structured, and how node configuration affects behavior. A solid understanding will help you design more effective and predictable flows.
 

General Best Practices

These apply broadly to the AI Agent instructions and flow design across both single and multi-Agent scenarios.

Write clear, specific instructions without conflicts

• Avoid conflicting instructions, use direct language and avoid ambiguity. Indicate exactly what you expect the Agent to do (e.g., “Summarize the key points…” vs. “Read this.”).
• Keep the same language consistent in the prompts. E.g., if you start the prompt in English, keep it in English.
• Tip: Ask yourself: If you gave this instruction to a human, would they clearly understand what to do? If not, revise it.

Provide relevant examples in the instructions

• Add examples to demonstrate ideal input/output formats or expected tone.
• Use “You are…” statements to help the Agent assume a specific persona or mindset.

Split complex tasks into simpler subtasks

• Break down large or multi-step objectives into smaller, more manageable parts.
• Use sequential steps to handle each subtask, feeding outputs from earlier steps into later ones.
• If the task is too complex consider splitting the task by adding a new AI Agent dedicated to handling that task.

Use Skills for structured tasks

Use a Skill that will be able to be reutilized: For utility functions, number-heavy logic, random number generation, sensitive data handling, or strict workflows.

Use variables to provide context

• Use the Application Input or the Output from a Skill to feed in customer data or past conversation history through variables to create more dynamic conversations
• Make sure variables have a clear description in the variable list so AI Agents know what the variable represents.
• Use skills to populate the value of variables. Avoid using the Instructions of AI Agents to fill variable values.

Leave variable assignment to Skills

• Agent instructions should not be used to manipulate or assign values to variables.
• Use a Skill, such as an Integration or Workflow, to populate or update variables.
• Variable handling should be done through structured steps, not through reasoning instructions.

Only share relevant information from variables

Avoid passing entire objects or large variable structures unless necessary. Instead, extract and share only the specific pieces of information the AI Agent needs to complete its task.

Providing too much irrelevant data, especially without proper context, can confuse the Agent and lead to less accurate or off-topic responses.

Test changes systematically

Test one modification at a time and observe the results before making further changes. Be sure to use consistent input examples to compare Agent behavior across versions.

Monitor and iterate based on real usage

Review interaction logs to understand how users engage with the Agents. Refine prompts and Agent logic based on actual conversation patterns and pain points.

Best Practices for Multi-AI Agent design 

This section approaches the design and orchestration of multiple AI Agents within a single flow, ensuring effective collaboration, task division, and system performance.

Define clear roles and responsibilities

• Assign each Agent a distinct role based on the tasks it should perform.
• Avoid overlapping functionalities to reduce redundancy and confusion.
• Use clear and specific names and descriptions that reflect each Agent’s role to maintain clarity.
• Avoid using acronyms in the AI Agents.
• Do not instruct an Agent with something they are not supposed to handle.

Do not use a Routing Agent with only one Action Agent

A Routing Agent must have more than one Action Agent beneath it to justify its role in the hierarchy. Creating a Routing Agent with only one child Action Agent introduces unnecessary complexity, latency, and serves no routing purpose.

Avoid reusing the same tool across multiple Agents

When designing AI Agents, it’s important to ensure their responsibilities are clearly defined and do not significantly overlap. While multiple Agents can use the same tools, ambiguity in their scope of work can make it difficult for Supervisors to determine which Agent should handle a given task.

If multiple Agents need to access similar functionalities, consider consolidating that logic under one Agent or using shared variables for coordination.

Response structuring must be done by the Supervisor

The Supervisor Agent receives — and is the last Agent — to prepare the message to be sent to the user. If we need to change the response somehow, then those instructions should be placed in the Supervisor Agent.

Use structured handoff between Agents

Explicitly define what output from one Agent serves as input for the next. Use clear language in handoff prompts to specify what the next Agent should do with the received data.

Test AI Agent collaboration scenarios

Simulate different paths through the multi-Agent flow to catch unexpected interactions. Be sure to monitor how Agents respond to edge cases and ambiguous inputs.