Multi-Agent Orchestration (Team of Agents)
Learn about Teams of Agents and Agent-as-Tool here.
Multi-Agent Orchestration
Did you know that you’ve been using multi-Agent orchestration already? Sapience takes care of the complexity for you, and whenever you’re working with a Gen 3 Agent like the system Sapience Agent, or Data Analyst Agent, or any of the org- and user-scoped Agents that are available in your workspace, these Agents frequently call other Agents for help!
Overview
At its core, Sapience is an Agent Orchestration platform. Don’t let that scare you. You already know how this works. Sapience comes with some built-in Agents, lets you create your own Agents, lets your Org Admin create Company-wide Agents, and dynamically creates Project Agents for every Project you create, and File Agents for every File you upload.
So - now lets take your understanding to the next level, and talk about Teams of Agents. This is the Sapience term for what other platforms would call all of these technologies “multi-agent orchestration”, “hand-offs”, “guardrails”, and “agent-as-tool”. Sapience uses these under-the-hood, but you don’t need to worry about that.
Key Concepts
Sapience Objects & Resources
This articles builds on the concept of the Sapience object graph (the “things” in Sapience). If you haven’t read that foundational article, do that now:
Agent
The core building block (or “primitive”) of Sapience. Agents are covered in detail elsewhere, so please consult those pages:
Trigger
A trigger is something that kicks off an Agent to do work. When you use an agent in Chat, the trigger is you sending a message to an Agent. But there are other things that trigger Agents to do work as well.
Email: for Agents that have an email address (most), sending an email to an Agent will trigger a Run, and after it finishes its work, it replies to you.
Scheduled Job: any time you create a Scheduled Job to run with an Agent or a Project Agent, you’re essentially creating a progammatic task that fires up at the desired time, and triggers an Agent Run.
Another Agent: central to the idea of Sapience being a multi-Agent orchestrator is the idea that one Agent can trigger another. This is what happens when you are in Chat, upload an Excel file, and it asks if you want to use the Sapience Coding Agent behind the scenes. Or if you ask an Agent to do web research, it will fire up the Web Research Agent and run that before it replies to you.
API call / webhook: if you’re using Sapience in your automation flows, when you call the Sapience API you’re usually (though not always) triggering an Agent Run.
Run
A unit of execution for an Agent. It will usually mean that it establishes some sort of goal internally, and then loop many times (up to 50), invoking tools, other agents, or simply continuing to make LLM calls to do work. At the end of the Run there is a final output. For the Chat interface, data is streamed back to the GUI so you can see what its doing internally. There are other output modes, such as when its outputting a structured JSON response (following a zod or pydantic schema) and others. But a Run is just an Agent doing something and then deciding that its “done”.
Team of Agents
Any time a Run involves more than 1 Agent, its technically a Team. Bigger Teams apply for doing complex work, like whenever you use the Deep Research feature. Teams of Agents are depicted in the diagram above. There is always one Agent in the group that is the Leader. The other Agents in the group are sub-Agents of worker Agents. Note that the concept of the Leader is ephemeral. In one team, the Sapience Agent might be the Leader, calling other Agents. In another Team, the Sapience Agent might be a sub-Agent.
Team Leader
The Agent that is deciding: 1) have we achieved our goal yet or should we keep working? 2) which other Agents should be used to do work; 3) what order each Agent should be triggered; 4) what inputs those Agents should get, and what to do with the output of each sub-Agent Run. Most Agents can play the role of Leader.
Sub-Agents
Any Agent in a Team that is not the Leader. All Agents can play the role of sub-Agent. Note that there are a couple of different ways that Agents 2,3,4… N in a Team can be invoked, with both hand-offs and agent-as-tools supported.
Inter-Agent flow control and communication works with these two primary patterns:
Agent-as-Tool (hub and spoke): this is where the Leader invokes another Agent as a tool, waits for the other Agent to run, and then decides a) what to do with the output; b) whether to ask it for more or different information. This is the primary pattern Sapience uses for multi-Agent runs. Research shows that having one Agent who is understands the big-picture and the overarching goal, that then uses other agents as “workers” is the most effective Agent orchestration pattern currently.
Hand-offs: This is where Agent1 actually transfers control to Agent2 (i.e. gives up its status as Leader and elects another Agent to become the Leader). This works well in certain situations, particularly when an Agentic flow is actually a linear pipeline (do this, then do that, then do this other thing). In this case the new Agent inherits the full conversation context and “takes over”. We generally recommend setting up linar flows as automations rather than using Agent hand-offs.
Interplay with Skills: whilst you can always prompt an Agent in the main Chat interface to use another Agent to do some work, and you should do this while you are figuring out the flow you want to run, once you’ve figured out the best set of prompts to get the team of Agents do work as you desire, you can/should create a Skill that codifies that flow so you can use it again and again (see below).
Memory & Skills
This is not technically a “multi-Agent orchestration” thing, but we include it here as its very important to the operation of multi-Agent orchestration in practice.
Memory: when Agents are running in a Team, its a good idea to prompt them to always retrieve memories first. The Memories layer of Sapience offers Agents a global state that they can write to and where YOU can provide important information that all Agents should know about. You can see the Memory item in the diagram above in the left box, as this is really a consideration for each Agent when it runs. i.e. all Agents can access the Memory layer, and you should prompt them to do so. Learn more about Memory with this article:
Skills: skills are another core Agent primitive and therefore in the left box in the diagram above. Agents can use Skills to do work. A common pattern would be to setup an Agent that is an expert at a certain thing. E.g. you might have an Agent using a Skill you’ve created to do a very customized and detailed piece of work. Then when you’re running multi-Agent workflows, you can have task specific Agents that will work using a given Skill, all orchestrated by one Leader. Read more about Skills in this article: