Agent Collaboration (A2A)¶

Agent Collaboration (A2A) lets one Agent delegate work that requires another Agent's specialized capabilities, data scope, or tool permissions. The two Agents can belong to different workspaces, and each continues to operate within its own permissions and behavioral boundaries.

For example, an incident-response Agent can delegate database diagnosis to a database specialist Agent in another workspace, then consolidate the returned evidence and recommendations in the current task. Users do not need to repeat the issue across workspaces or grant the caller direct access to the target workspace.

Beta

Agent Collaboration is currently a Beta feature that only supports authorized calls between Agents in the {{ no such element: super_collections.SuperDict object['ai_agent_teams_name'] }} service. It is not an integration endpoint for the third-party Agent2Agent Protocol.

What Agent Collaboration Does¶

Agent Collaboration connects capability publishing, caller authorization, task delegation, and result consolidation. It helps teams:

Reuse specialist Agents for databases, SRE, security, testing, cost analysis, and other focused responsibilities;
Isolate data and permissions because the target uses its own workspace data, Skills, MCP services, and tool permissions;
Collaborate across workspaces without granting the caller direct access to the target workspace;
Follow execution from queued through terminal status in the current task;
Return the target's result to the caller so the main task can continue without duplicating the analysis.

Use Agent Collaboration when the target has unique data, tools, permissions, or domain context. When the current Agent can complete the work itself, an external delegation is usually unnecessary.

flowchart LR
  A[Configure identifiers for both Agents] --> B[Publish the target capability]
  B --> C[Authorize the caller on the target]
  C --> D[Start a task with the caller]
  D --> E[Target executes within its own boundaries]
  E --> F[Result returns to the current task]

Understand the Relationship¶

Open Configuration > Agent Collaboration in an Agent workspace to view its card and collaboration relationships:

Area	Description	Main actions
Agent card	Shows the Agent's unique identifier and external capability description.	Configure the identifier once; review and edit the capability description.
Authorized to	Shows which caller Agents may invoke the current Agent.	Add, edit, enable, disable, or remove authorization.
Callable	Shows which target Agents have authorized the current Agent.	Review the target, workspace, capability, and online status.

Authorization is configured on the target Agent. If Agent A needs to call Agent B, add Agent A's identifier under Authorized to on Agent B. After the authorization is saved, Agent B appears under Callable on Agent A.

Before You Start¶

Make sure that:

The caller and target Agents have both been created and their runtime services have been deployed;
Both Agents are available and have clear responsibilities and behavioral boundaries;
An administrator for each Agent can help establish the relationship;
The target has the Skills, MCP services, and data permissions required for the delegated work;
The team has agreed on what may be delegated and which actions still require human confirmation.

Workspace Owners, administrators, and the creator of the current Agent can maintain its profile and caller authorizations. Other members with access can only view them. Collaboration configuration becomes read-only while the Agent is being created, offline, disabled, or otherwise unavailable.

Step 1: Configure the Agent Identifier¶

The Agent identifier is the stable identity used for authorization, capability discovery, and delegation.

Open the target Agent workspace.
Go to Configuration > Agent Collaboration.
Enter a recognizable prefix under Agent Identifier.
Review the complete identifier generated by the system.
Save it and confirm the identifier in the confirmation dialog.

The prefix must:

Contain 3–32 characters;
Start with a lowercase letter;
Use only lowercase letters, numbers, and single hyphens (-);
Not end with a hyphen.

The system appends a suffix dedicated to the current Agent. For example, entering database-diagnostics can produce:

database-diagnostics_27abcd

Note

The complete Agent identifier becomes permanent after confirmation and cannot be changed. Use a long-lived responsibility name rather than a temporary project, environment, or person name.

The caller should also configure its Agent identifier. Its complete identifier must be given to the administrator of the target Agent when authorization is added.

Step 2: Describe the Public Capability¶

The External capability description tells other Agents what the current Agent specializes in and when to call it. The system prepares a default from the Agent name, workspace, and description; edit it to reflect the actual responsibility.

Include:

The Agent's specialty and intended users;
The types of data, Skills, or tools it can use;
Suitable tasks and expected input;
The result it can return;
Tasks it will not handle or actions that require confirmation.

Example:

I am the database diagnostics Agent from the Database Operations workspace.
I can analyze database queries, slow SQL, connection pools, lock waits, and capacity risks, then return evidence, impact, and optimization recommendations.
Provide the database object, time range, and question to investigate. I perform read-only analysis by default and do not change database configuration or execute SQL.

Use language that makes the call decision clear. A generic statement such as "handles many kinds of issues" does not help callers choose the right Agent.

Step 3: Authorize the Caller¶

An administrator of the target Agent completes these steps:

Open the target Agent's Agent Collaboration page.
Select Authorized to.
Click Add authorization.
Enter the caller's complete Agent Identifier.
Select a permission mode.
Add a Call boundary when needed.
Save the authorization and leave it enabled.

Setting	Description	Recommendation
Caller Agent identifier	Uniquely identifies the caller receiving access.	Copy the complete identifier from the caller profile instead of typing it manually.
Permission mode	Controls confirmation behavior while the target executes delegated work.	Prefer Default permission for production and sensitive scenarios.
Call boundary	Further limits the accepted task, data scope, or action type.	Use a testable rule, such as "Read-only database diagnosis; no configuration changes."
Enabled status	Controls whether the caller may start new calls.	A new authorization is enabled when saved; turn off its card switch when new calls should be paused.

Permission modes:

Mode	Behavior	Suitable for
Default permission	The target follows its normal confirmation rules. If a delegated action requires human approval, the external caller cannot approve it and the call ends as Refused.	First-time integrations, read-only diagnosis, production data, and boundaries that are still being validated.
Full access	The target can act directly within its existing capabilities without requesting confirmation for each action.	Trusted sources and stable, low-risk automation after a team risk review.

Full access changes confirmation behavior only. It does not expand the target's data scope, Skills, MCP services, tool permissions, behavioral boundaries, call boundary, or system safety controls.

After saving, return to Agent Collaboration > Callable on the caller. Confirm that the target appears with the expected capability and online status.

Step 4: Use Collaboration in a Task¶

After the relationship is established, users continue to work from My Tasks on the caller. There is no need to select a target Agent in advance, open a separate session, or call a tool manually.

Open the caller Agent workspace.
Create a task or open an existing task.
Describe and send the request as usual. You may ask a particular Agent to handle part of the work, or simply provide the task goal, the object to analyze, its workspace, and the expected result. When the request extends beyond the current Agent's data scope or capabilities, it automatically decides whether an authorized external Agent should collaborate on the task.

Example:

Analyze the increase in checkout-api errors over the last 30 minutes.
Use slow-query, connection-pool, and lock-wait data from the "Production Database" workspace.
Distinguish confirmed facts from hypotheses and return prioritized next steps.

The caller first uses its own capabilities to process the task. When the task requires data it cannot access or expertise it does not have, it checks whether an authorized callable Agent has the corresponding capability. If a match is available, collaboration starts automatically. Users do not need to know or enter the target Agent's name.

The target completes the relevant work within its own workspace, capabilities, and permissions, then returns the result to the caller. The caller combines it with the current task context and provides one response, without requiring the user to switch workspaces or take additional action.

Example: Cross-Workspace Database Diagnosis¶

This example lets an application incident-response Agent call a database diagnostics Agent from another workspace.

1. Prepare the Agents¶

Role	Example identifier	Responsibility
Caller	`incident-response_ab12cd`	Correlates alerts, logs, traces, and changes to organize an incident analysis.
Target	`database-diagnostics_27abcd`	Queries database telemetry and analyzes slow SQL, connections, and lock waits.

In the target's external capability description, state the supported database scope and read-only boundary.

2. Add Authorization¶

On the database diagnostics Agent, add incident-response_ab12cd under Authorized to:

Setting	Example
Permission mode	Default permission
Call boundary	Read-only database diagnosis only. Do not change parameters, execute SQL, or restart instances.
Enabled status	Enabled

3. Start the Task¶

Enter the following on the incident-response Agent:

Analyze the order-service timeouts that began at 15:20.
First correlate alerts, logs, and traces from the current workspace. Then call database-diagnostics_27abcd to inspect slow SQL, connection pools, and lock waits for the same period.
Return a timeline, evidence from both Agents, the most likely causes, impact, validation steps, and any actions requiring approval.

4. Verify the Result¶

Confirm that the task shows a call card for the database diagnostics Agent and wait for Completed. The final response should distinguish evidence from each Agent. If the target lacks enough information, provide a more specific object, time range, or validation question instead of widening permissions immediately.

Frequently Asked Questions¶

Issue	Troubleshooting
Add authorization is unavailable	Confirm that the current Agent has an identifier, your account can manage collaboration, and the Agent is available.
The target is missing under Callable	Confirm that authorization was added on the target, the caller identifier is exact, and the authorization is enabled, then refresh.
The task does not start an external call	Confirm that the target is online and listed under Callable. If collaboration is required, name the target and delegation scope explicitly.
The call is refused	Review the target capability, permission mode, call boundary, and behavioral boundaries, then narrow the request.
The call fails	Check both runtime statuses, authorization, and the target's required Skills, MCP services, and data permissions.
The identifier cannot be edited	This is expected after the first confirmation so existing authorization relationships remain stable.

Disabling an authorization prevents new calls. Disabling or removing it also cancels queued calls, while calls already running continue to completion. Check for active cross-Agent work before either operation.

Recommendations¶

Split Agents by professional responsibility instead of creating overlapping Agents only for collaboration;
Use a stable, recognizable responsibility name for each Agent identifier;
State both supported and unsupported work in the external capability description;
Start with Default permission and a specific call boundary for production scenarios;
Pass only the information needed for the delegation; never include secrets, Tokens, or unrelated sensitive data;
Review Authorized to and Callable regularly, and disable or remove relationships that are no longer needed.