Agent Communication

How do agents communicate with each other?

In most advanced agentic scenarios, agents need to communicate with other agents to achieve their goals.

In fact, our recommendation is that you build agents with highly specialized roles and skills and use agent-to-agent communication to achieve the overall goal.

There are a number of ways to achieve agent-to-agent communication natively in Agentuity.

Communication Types

Agents can communicate with each other in a number of ways in the Agentuity platform. The following are the different types of communication that are supported:

Intra Project

Intra project communication is the simplest form of agent-to-agent communication. Agents within the same project can communicate with each other locally without leaving the local network.

Inter Project

Inter project communication is a more advanced form of agent-to-agent communication. Agents can communicate with each other across projects within the same organization but will communicate over the internal network.

Inter Organization

Inter organization communication is the most advanced form of agent-to-agent communication. Agents can communicate with each other across organizations. Currently, Agentuity only supports inter organization agent communication if the target agent is public and the source agent has been given the agent ID by the other organization. For inter organization communication, the source agent will communicate over the internal network.

Communication Methods

Agents has two primary methods of communication with other agents:

Handoff

When an agent needs to handoff a request to another agent, it can do so by using the SDK handoff method. The handoff method will send the request to another agent and the other agent will be responsible for completing the request.

For handoff, the source agent can modify the original request data or simply pass the request as is. The target agent will receive the request and can complete the request as if it was the original request.

A trivial example of a handoff:

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';
 
export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
  return resp.handoff({name: 'My Other Agent'});
}

In the above example, the source agent is sending a request to the My Other Agent agent. The My Other Agent agent will receive the request and can complete the request as if it was the original request.

Calling another agent is a common pattern in agentic workflows. It is often used to delegate a task to another agent or to get the result of a task from another agent.

In another trivial example, the source agent is sending a request to the My Other Agent agent and passing a message to the other agent. The My Other Agent agent will receive the request and can complete the request as if it was the original request. Since we are passing a String type, the other agent will receive the message as a string and with content type text/plain.

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';
 
export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
  return resp.handoff({name: 'My Other Agent'}, "would you please do this?");
}

Invocation

When an agent needs to invoke another agent to complete a task and wants to wait for the result, it can do so by using the SDK getAgents method on AgentContext. The getAgents will perform resolution to determine the target agent location and return a handle to the target agent that can be used to run the target agent.

If the target agent is local (intra project), the getAgents method will return a handle to an internal agent which can be used to run the target agent.

If the target agent is remote (inter project or inter organization), the getAgents method will return a handle to an external agent which can be used to run the target agent. In addition, the SDK internally will use the authorization token to authenticate the source agent to the target agent.

A trivial example of an invocation:

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';
 
export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
  const agent = await ctx.getAgent({name: 'My Other Agent'});
  const agentResponse = await agent.run({name: 'My Other Agent'}, "would you please do this?");
  const text = await agentResponse.data.text();
  return resp.text(text);
}

In this trivial example above, the functionality is similar to the handoff example above. The source agent is sending a request to the My Other Agent agent and passing a message to the other agent. The My Other Agent agent will receive the request, perform an operation and return the result to the source agent. The source agent will simply return the result as a text result.

In a real life scenario, you'll likely want to pass the appropriate data types to the target agent and wait for the result and then use the result in your own agent to perform additional tasks.

Parallel Execution

Sometimes you want to send a request to multiple agents at the same time. This is an example of parallel execution.

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';
 
export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
const agent1 = await ctx.getAgent({name: 'My First Agent'});
const agent2 = await ctx.getAgent({name: 'My Second Agent'});
await Promise.all([
  agent1.run({task: 'My First Task'}),
  agent2.run({task: 'My Second Task'}),
]);
return resp.text('OK');
}

In this example, the source agent is sending a request to two different agents at the same time. The source agent will wait for both agents to complete their tasks before returning.

In a real life scenario, you'll likely want to pass the appropriate data types to the target agents and wait for the results and process them before continuing.

Agent Resolution

How do we resolve the target agent? There are two main ways to do this:

Intra Project Resolution

When calling an agent within the same project, the agent name is usually the easiest way to resolve the target agent. The agent name is a human readable name for an agent. It is a string that was used for the agent's name.

Inter Project Resolution

When calling an agent across projects within the same organization, the agent ID is typically the most reliable way to resolve the target agent. The agent ID is a unique identifier for an agent.

However, if the agent name is not unique across projects, the agent project ID can be used to disambiguate the target agent. The agent project ID is a unique identifier for an agent's project.

A trivial example of a handoff:

import type { AgentContext, AgentRequest, AgentResponse } from '@agentuity/sdk';
 
export default async function Agent(
 req: AgentRequest,
 resp: AgentResponse,
 ctx: AgentContext
) {
  return resp.handoff({
     id: 'agent_123456789abcedef',
     projectId: 'project_123456789abcedef',
  });
}

Inter Organization Resolution

Currently, Agentuity only supports inter organization agent communication if the target agent is public and the source agent has been given the agent ID by the other organization. When using inter organization communication, only the agent ID is required to resolve the target agent.

Communication Authorization

When communicating with other agents outside the local project, Agentuity will automatically generate a one-time use authorization token with a short expiration. This token is used to authenticate the source agent to the target agent automatically without the need for the source agent to pass the token to the target agent.