X-Agent (Cross-Agent)

Superagent agents can interact with other agents in the same workspace through a set of cross-agent tools collectively called X-Agent. One agent can list the other agents available, create new agents on the fly, send messages to another agent, and read that agent's session history -- all without leaving its own session.

This enables multi-agent workflows where a manager agent delegates subtasks to specialized worker agents, or where peer agents collaborate by exchanging information through invocations and transcript reads.

How it works

Each agent container is equipped with an MCP server called agents that exposes five tools. When an agent calls one of these tools, the request is sent from the container back to the Superagent host process over HTTP, authenticated with the container's proxy token. The host resolves which agent is calling, applies X-Agent Policies, and performs the operation on behalf of the caller.

The caller agent never directly communicates with the target agent's container. All orchestration flows through the host, which manages container lifecycle, session creation, message persistence, and policy enforcement.

X-Agent tools

list_agents

Discovers the other agents available in the workspace. Returns each agent's slug, display name, and description. The calling agent is excluded from the results.

In auth mode, the list is filtered to agents that the calling agent's owner has access to.

Use this before invoke_agent to find the slug of the agent you want to work with.

create_agent

Creates a new agent in the workspace. Accepts a name, an optional one-line description, and optional instructions (which become the new agent's system prompt). Returns the new agent's slug.

This tool always requires manual approval. There is no "always allow" policy for agent creation -- every create_agent call prompts the user for confirmation. In auth mode, the new agent inherits the ACL of the calling agent's owner.

After creation, you can immediately interact with the new agent using invoke_agent.

invoke_agent

Sends a message to another agent. This is the primary tool for agent-to-agent delegation.

Parameters:

• slug -- The target agent's slug (from list_agents).
• prompt -- The message to send.
• session_id (optional) -- An existing session ID to continue. If omitted, a new session is started on the target agent.
• sync (optional) -- If true, the tool blocks until the target agent finishes its turn and returns the agent's final response inline. If false (the default), the tool returns immediately with status running and you can check results later with get_agent_session_transcript.

Returns: The session ID and status (running or completed). In sync mode, the target agent's last message is included in the response.

When continuing an existing session (session_id provided), the session must exist and must not be currently running.

get_agent_sessions

Lists the sessions belonging to another agent, ordered newest first. Each entry includes the session ID, name, creation time, last activity time, message count, and whether the session is currently running.

Supports pagination via limit (default 50, max 200) and offset parameters.

Use the returned session ID with get_agent_session_transcript to read a conversation, or with invoke_agent to send a follow-up message.

get_agent_session_transcript

Reads the full message transcript of a session belonging to another agent. Returns a status line (running, idle, or awaiting_input) followed by the messages.

Each message includes its role (user, assistant, system), text content, and tool name if applicable. Tool call inputs and outputs are summarized to keep the transcript compact -- the raw payloads are omitted. Thinking blocks are stripped.

If sync=true and the session is currently running, the tool waits until the target agent's turn completes before returning the transcript.

Session tracking and provenance

When one agent invokes another, the resulting session on the target agent is tagged with metadata recording which agent started it. The session name defaults to "Invoked by " so it is easy to identify cross-agent sessions in the UI.

The session metadata includes:

• invokedByAgentSlug -- The slug of the agent that initiated the invocation.
• createdByUserId -- In auth mode, the user ID attributed to the invocation (inherited from the calling agent's owner).

This provenance data is visible in the session list and is used to enforce the one-hop invocation rule (see below).

One-hop invocation rule

Cross-agent invocation is limited to one hop. If Agent A invokes Agent B, Agent B cannot invoke Agent C (or Agent A) from that invoked session. This prevents runaway chains (A invokes B invokes C invokes D...) and circular invocations (A invokes B invokes A).

The host enforces this by checking the session metadata of the calling session. If the caller's session was itself started by another agent (invokedByAgentSlug is present), the invoke_agent call is rejected with an error explaining the constraint.

An agent can still be invoked directly by a user and have full X-Agent capabilities in that session -- the restriction only applies to sessions that were themselves created by another agent's invocation.

Self-invocation guard

An agent cannot invoke itself. If invoke_agent is called with the caller's own slug, the request is rejected immediately. This prevents infinite loops within a single agent.

Use cases

Manager-worker delegation

A "manager" agent receives a complex task, breaks it into subtasks, and delegates each subtask to a specialized worker agent using invoke_agent with sync=true. The manager collects the results and synthesizes a final answer.

For example, a research agent might invoke a "Web Researcher" agent to gather information, a "Data Analyst" agent to process the findings, and a "Report Writer" agent to produce the final document.

Specialized agent collaboration

Agents with different capabilities can collaborate by reading each other's session transcripts. A "Code Review" agent might read the sessions of a "Developer" agent to understand what changes were made, then invoke the developer with feedback.

Dynamic agent creation

An agent can create new agents tailored to a specific task. For example, a "Project Bootstrapper" agent could create a set of specialized agents (frontend, backend, testing) with customized instructions, then orchestrate work across them.

Session monitoring

A supervisory agent can use get_agent_sessions and get_agent_session_transcript to monitor what other agents are doing, check on long-running tasks, or compile status reports -- all without sending new messages that would trigger additional work.

Delivering sessions to the user

After invoking another agent, the caller can use the deliver_session tool to surface the resulting session as a clickable card in the chat. The user sees a link they can click to jump directly to the invoked session and review the work. This is useful for making cross-agent workflows visible and navigable in the UI.