Multi-Agent

X-Agent (Cross-Agent)

Agents can discover, create, and invoke other agents in the same workspace to delegate tasks and collaborate.

How it works

Each agent container includes an MCP server called agents that exposes the five X-Agent tools. When an agent calls one, the request travels from the container back to the Gamut host 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 the caller's behalf.

The caller never communicates directly 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 in the workspace. Returns each agent's slug, display name, and description; the calling agent is excluded. In auth mode, the list is filtered to agents the calling agent's owner has access to.

Call 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 that become the new agent's system prompt. Returns the new agent's slug, which invoke_agent accepts immediately.

Every create_agent call requires manual approval. There is no "always allow" policy for agent creation. In auth mode, the new agent inherits the ACL of the calling agent's owner.

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 to continue; it must exist and must not be currently running. If omitted, a new session starts on the target agent.
sync (optional): If true, the tool blocks until the target agent finishes its turn and returns the final response inline. If false (the default), the tool returns immediately with status running; read the result 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.

get_agent_sessions

Lists another agent's sessions, 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.

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

get_agent_session_transcript

Reads the full message transcript of another agent's session. 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 inputs and outputs are summarized and thinking blocks are stripped to keep the transcript compact.

If sync=true and the session is currently running, the tool waits for the turn to complete before returning.

Session tracking and provenance

When one agent invokes another, the resulting session on the target is tagged with metadata recording who started it, and its name defaults to "Invoked by " so cross-agent sessions are easy to spot in the session list.

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).

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 and circular invocations.

The host enforces the rule through session metadata: if the calling session has invokedByAgentSlug set, the invoke_agent call is rejected with an error explaining the constraint. The restriction applies only to invoked sessions; in sessions started directly by a user, the agent keeps full X-Agent capabilities.

Self-invocation guard

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

Use cases

Manager-worker delegation

A manager agent receives a complex task, breaks it into subtasks, delegates each one with invoke_agent and sync=true, then synthesizes the results. A research agent might invoke a "Web Researcher" to gather information, a "Data Analyst" to process it, and a "Report Writer" to produce the final document.