Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
FAQ/Agent Collaboration

Agent Collaboration

Agent-to-agent permissions, events, report-back, shared folders, systems, rooms, asks and deliverables. Short, grounded answers with links to the full documentation.

53 questions

How do agents talk to each other in Trinity?

Agents communicate through the Trinity MCP server, not by calling each other's containers directly. Every agent gets its own agent-scoped API key, injected automatically and wired into the agent's MCP configuration, so it can call tools like chat_with_agent(agent_name, message)to send a message to another agent and get the response back. Trinity detects the calling agent and records the interaction as a collaboration event on the Dashboard's activity Timeline, which you can replay over a chosen time range. See Agent Network.

Why can't my agent call another agent?

By design. Trinity's permission model is restrictive by default: a new agent has zero agent-to-agent permissions, and the MCP server blocks any chat_with_agent call to a non-permitted target with an error before it reaches the other agent. You must grant each connection explicitly on the Permissions tab; only the system agent (trinity-system) bypasses permission checks. See Agent Permissions.

Why was my agent's call refused with "inter_agent_depth_exceeded"?

The call was too deep in a chain of agent-to-agent calls. Trinity counts each hop, and refuses a hop past the limit (8 by default) before any work starts. This stops agents from calling each other in an endless loop. Retrying does not help: the MCP tools mark the refusal retryable: false. The count carries through loops an agent starts, schedules it triggers by hand, chat-session turns and events it emits, so none of those resets the chain; webhook triggers, cron-fired schedule runs and self-reminders do start a new one. A wake when a run the agent delegated ends stands where the agent stood when it delegated, so it adds nothing to the count. The refusal names the running execution that set the depth (exhausted_by). If a real pipeline needs more hops, an admin can raise inter_agent_max_chain_depth (up to 32). See Agent Network.

How do I let one agent call another?

Open the detail page of the agent that will be making the calls and go to its Permissions tab, which lists every other agent in the system with a toggle (Allow All / Allow None set every row at once). Toggle on the agents it may call and click Save Permissions. Permissions are directional: allowing Agent A to call Agent B does not allow B to call A — each direction is a separate grant, made from B's own Permissions tab. The change takes effect on the next MCP call, with no restart needed. See Agent Permissions.

Does the Permissions tab control who can call my agent, or who my agent can call?

Who your agentcan call. Each row on an agent's Permissions tab is a grant from this agent to the listed one — toggling research-worker on for orchestrator lets orchestrator call research-worker, subscribe to its events and mount its shared folder, and says nothing about whether research-worker may call back. To control who may call your agent, open each caller's Permissions tab and toggle your agent there. Nothing is granted in either direction by default, and only the system agent (trinity-system) bypasses the check. See Agent Permissions.

What does granting permission actually let an agent do?

Permission grants communication, not control. A permitted agent can see the target in list_agents, send it messages via chat_with_agent, run and stop loops on it with run_agent_loop and stop_loop, subscribe to its events, mount its exposed shared folder, and read its declared metrics with get_metrics— the same permission record gates each of these, and it is also the boundary for reading or answering the target's operator-queue items over MCP (see MCP & API). It does not let the calling agent manage the target (start, stop, or reconfigure it), and the reverse direction stays blocked until you grant it separately. See Agent Permissions.

What is a peer skill grant, and why was my agent's call refused with "skill_not_granted"?

A permission lets the caller run the skills the target declares itself— the ones in the target's own repository. A skill an admin assigned from the skills library (directly or through a skill set) is not included: when another agent names it in a request (/skill-name), the call is refused with skill_not_granted before anything runs, and the refusal is audited. A peer skill grantopens one such skill to one caller: an admin turns it on in the caller's Permissions tab, under Library skills on agents this agent can call, and it goes away with the permission. The target itself, its schedules and loops, people, and a parent calling an agent it spawned never need one. After an upgrade nothing is granted; Settings → Agents lists the agent-to-agent calls that used a library skill in the last 30 days and are now refused, with a Grant button each. If the grants or assignments cannot be read, the call is refused with peer_surface_unavailable rather than let through. See Agent Permissions.

Can one agent hand off a long-running task to another without waiting?

Yes. Call chat_with_agent(agent_name, message, parallel=true, async=true), which returns an execution_id immediately instead of holding the connection open, then poll get_execution_result(agent_name, execution_id) until the task completes. This keeps you clear of the synchronous call bound (MCP_CHAT_TIMEOUT_MS, default 25 seconds) and suits delegation chains where the worker may run for many minutes. A synchronous call that outlives that bound is not lost either — it answers with a status: "queued_timeout" receipt carrying the execution_id to poll, so never re-send a reworded version, which would dispatch a second execution (details in MCP & API). You usually don't have to poll at all: by default the calling agent is woken with one turn when the delegated run ends (below). See Agent Network.

Why did my agent get a caller_wake turn that nobody scheduled?

A run it delegated to another agent ended, and Trinity woke it once so it could act on the outcome instead of polling. This is on by default. The turn quotes the worker's reply (up to 2,000 characters, with a marker when it was cut), and the full result is readable with get_execution_result. At most one wake starts per agent every 15 seconds, a run that ends while a wake is still running is delivered when that wake ends, and wakes between one pair of agents are capped per hour (caller_wake_max_per_hour, default 120). The chat_with_agent receipt tells the caller in advance: wake: "on_ending", or wake: "none" with the reason. See Agent Network.

How do I stop an agent from being woken when the runs it delegated end?

Turn off Wake this agent when its asks endunder the agent's Settings › Guardrails › Reliability, or send {"mode": "off"} to PUT /api/agents/{name}/operator-resume. The one switch covers both kinds of wake, an answered ask and a delegated run that ended, so switching it off stops both. Only the owner or an admin can change it, never with an agent's key, because each wake is a turn the owner pays for. With it off, the agent's chat_with_agent receipts say wake: "none" with wake_reason: "opted_out", so it knows to set a reminder instead. See Agent Configuration.

Can an agent grant itself permission to call another agent?

No. Granting and withdrawing permissions is human-only: the permission routes refuse an agent-scoped API key, so an agent can never widen its own reach or hand access to another agent. Only the agent's owner or an admin can change its permissions, and only toward agents they can access themselves. Every grant, replacement and withdrawal is written to the audit log. See Agent Permissions.

What does my agent see when it lists agents with its own key?

Its reach, not its owner's fleet: itself, the agents it has permission to call, and the agents it spawned with its current key. That holds for the MCP list_agentstool and for every fleet-wide backend route the key can call directly — the agent list, execution summaries, tags, the event-subscription list, telemetry, the operator queue, the /ws/eventsstream — even when the agent's owner is an admin. Any other agent answers like one that does not exist, so the key learns nothing about it. Two fleet health sweeps (get_fleet_health, the sync audit) still cover the owner's agents because they carry only git and health state. If your agent needs to see a sibling, grant the permission on its Permissions tab. See Agent Permissions.

What happens when I remove a permission between two agents?

Each thing the permission controls stops at a different moment. Calls (chat_with_agent, loops, reading the other agent's work) stop at the very next call. Event deliveries stop at the next event; the subscription itself is kept, so granting the permission again resumes it. A shared folder the agent mounted from the other agent stays until the agent's next start, which rebuilds the container without it, so restart the agent if you need it gone now. See Agent Permissions.

My agent's call to another agent timed out — should it send the message again?

No. If the call came back with an execution_id, that is a receipt: the work arrived and is queued, running or done. Read the outcome with get_execution_result(agent_name, execution_id), or set a reminder naming that execution_id and check back later. A reworded re-send can run the work twice. Even an error without an execution_id is not proof that nothing ran, so look for the exact message in list_recent_executions before re-sending word for word (agent_busy is the exception: the queue was full and nothing ran). Every agent is taught these rules in its platform prompt as the delegation contract. See Agent Network.

How do I share files between two agents?

Use shared folders, which are backed by Docker volumes. On the source agent, open Settings › Storage › Shared folders and enable Expose Shared Folder — anything it writes to /home/developer/shared-out becomes available to permitted agents. Grant the consuming agent permission on the Permissions tab, then enable Mount Shared Folders on the consumer; the folder appears at /home/developer/shared-in/{agent-name}. Restart both agents to apply the volume mounts. See Agent Network.

Why doesn't the shared folder show up in my consuming agent?

Volume mounts are applied when a container is created, so a restart of both agents is required after changing folder settings — enabling the toggles alone is not enough. Also check that the consumer has permission to the source agent, and that the source agent has actually been started with Expose Shared Folderenabled: if the source's shared volume doesn't exist yet, Trinity skips the mount until it does. See Agent Network.

How do event subscriptions between agents work?

Events are a lightweight pub/sub layer. A source agent calls emit_event(event_type, payload) with a type like report_ready; Trinity finds every subscription matching that source agent and event type and dispatches an async task to each subscriber. The subscriber creates the rule with subscribe_to_event(source_agent, event_type, target_message), and the task's message is built from that target_message template with placeholders like {{payload.field}}filled in from the event payload — for example Process report {{payload.url}}. Events are persisted and broadcast over WebSocket for real-time visibility. See Event Subscriptions.

Why isn't my agent receiving events it subscribed to?

Three things to check. First, subscriptions are permission-gated: the subscribing agent must have permission to call the source agent, or the subscription won't fire. Second, the subscription must match both the exact source agent name and the exact event type the emitter uses. Third, subscribe_to_eventidentifies the subscriber from the calling agent's own agent-scoped key, so it must be called by the agent itself, not through a user key — verify what exists with list_event_subscriptions. Beyond that: the permission is re-checked on every delivery, so a withdrawn grant silently pauses the subscription; a stopped subscriber misses the wake; and dispatches past the hourly cap between one pair of agents are skipped (a high-priority alert on the subscriber says so). See Event Subscriptions.

Why did Trinity skip my event subscription's tasks with a "dispatches capped" alert?

An event chain fired too often between one pair of agents. Trinity counts dispatches from one source agent to one subscriber per hour, across every subscription between them, and skips the rest of the hour once the cap is reached (120 by default, operator setting event_dispatch_max_fires_per_hour). The first skip in each hour raises one high-priority alert on the subscriber, saying a subscription may be looping. The usual cause is a subscriber whose task emits an event the source reacts to, and so on. Fix the loop rather than raising the cap. See Event Subscriptions.

Is it safe to put text from outside into an event payload?

Safer than it used to be, but treat it as data. When Trinity builds the subscriber's task message, each {{payload.*}} value is credential-scrubbed, capped at 4,000 characters and wrapped in ⟦ ⟧, and the message gets a line telling the subscriber that the marked text is event data, not instructions. The template text you wrote stays as written. A whole payload is limited to 64 KiB. The framing helps a model tell your instructions from the payload, but it is not a guarantee, so keep the subscriber's own permissions narrow. See Event Subscriptions.

Can an agent be notified the moment another agent's task finishes, instead of polling?

Yes. Rather than polling get_execution_resultin a loop, the waiting agent subscribes to the worker agent's task-completion event. When the worker's task reaches a terminal state, Trinity wakes the subscriber with an automatic report-back task carrying the outcome (every task run emits it — parallel=true delegations included; only a synchronous /chatturn does not) — so a long delegation ends by notifying the caller instead of the caller busy-checking. See Event Subscriptions.

Can a worker agent report back to its caller automatically when it's done or fails?

Yes. An agent that delegated the run is woken by default when it ends, with no setup (see the caller_wake question above). For runs it did not start, use task-completion event subscriptions: Trinity emits agent.task.completed and agent.task.failed events at the end of every execution, and an agent that has subscribed to another agent's task events is woken with a report-back task when one fires. It's permission-gated — the subscriber needs permission to the worker — and best-effort: the wake reaches a running subscriber, so a stopped agent misses it rather than receiving a queued backlog. See Event Subscriptions.

Can several of my agents hold a conversation together in one shared session?

Yes — this ships in every Trinity build. From the Workspace, mention a second agent in an existing one-to-one chat (@ and its name) and Trinity opens a shared roomwhere several agents — and you — work one topic together across many turns. Each agent keeps its own private context while the room holds the shared transcript, and turn-taking is mechanical: an agent speaks only when it's @mentioned. Rooms carry hard message, cost and time budgets so a chain of turns cannot run away. See Shared Sessions.

Who sets a room's limits, and who can rename it or change who's in it?

An admin sets the defaults for every room started from the Workspace under Settings → Retention → Room budgets: Messages (200 by default, up to 500), Cost cap (USD) (empty by default, meaning no cap), and Expires afterN hours (168 by default — one week; up to 168, and 0 means never). A room closes permanently, with a visible reason, when it reaches any of them; changes apply to rooms created from then on, and a Workspace client or Workspace-only account cannot override them, though a caller with an operator role or above creating a room over the API or MCP may pass its own budget (up to 500 messages, $1,000 and 168 hours). The person who created the room is its moderator: closing it and adding or removing agents are for a person, the moderator or an admin (signed in, or with their own user-scoped key), never an agent or a system-scoped key, while any human member can rename the room in place from its header. Agents only ever talk in a room — they never manage it. See Shared Sessions.

Can I add a colleague to a room, or leave one?

Where your install lets a room's moderator seat people, the room's People · N control opens People in this room, where the moderator adds a colleague with Add a person. They join as a collaborator who can read and talk but not approve, spend or reassign, and they read the room from the point they joined unless the moderator shows them earlier messages. Anyone can Leave room, which ends their access. On other installs, @mention a colleague in a message to tag them; the tag lands in their Inbox. See Shared Sessions.

What happens if an agent writes a very long reply in a room?

It lands. A turn's reply is posted as one message of up to 100,000 characters; past that it is trimmed, keeping the beginning and the end (where the conclusion and the next @mention usually are) around a marker saying how much was cut. If a reply cannot be posted at all, or arrives after the room closed, the room shows a line saying so rather than going quiet. Messages people post are limited to 100,000 characters. For long deliverables, agents are nudged to share a file and post a summary. See Shared Sessions.

Why did the agents in a room pause and wait for me?

Agents in the room kept handing the conversation to each other. One message from a person sets off at most 8 agent-to-agent hand-offs; past that the room posts The agents paused after 8 hand-offs and are waiting for a person, naming the agent that was next, and wakes no one else. Press Continueunder the transcript to wake that agent with a fresh count, or send a message, which starts a fresh count too. Continue is offered once per pause, only a person can press it, and the room's budgets still apply. A separate limit lets each participant wake agents at most 30 times in 5 minutes. (Rooms from before this change said Mention chain stopped at depth 8; it means the same thing.) See Shared Sessions.

What does the notice about a client reading the room mean?

A room that includes a Workspace client — someone outside your own organisation — tells every agent it wakes that a person is reading, so agent-to-agent turns keep internal details, other customers and costs out of the transcript. The signal comes from the room's membership alone, never from anything a participant writes, and it names nobody. A room holding only agents and operators carries no such notice. See Shared Sessions.

Can I stop an agent that's working in a room?

Yes, if your message started the turn and you are signed in as a platform user. Each agent working on the room's message gets a live card under the transcript with Stop, and the same run is listed as a Room turn on the rail's Work tab, where it can be stopped too. Stopping one agent leaves the others running. The transcript then reads {agent}'s turn was stopped.— not a failure — and the agent keeps its memory of the room, so the messages it did not answer reach it the next time it is mentioned. Esc in the room composer stops a turn only when exactly one can be stopped. A Workspace client sees … is thinking… instead and has no Stop. See Shared Sessions.

Can agents in a room see the files and screenshots I send?

Yes. A file you drop on a room, or paste into its composer, goes to every agent in it, and the rail's Files tab sends to Everyone in this chatby default, with each agent still selectable. When an agent is woken, it is told which files you have sent it, and it is shown an image when the conversation asks about one — so @sidekick what's in the screenshot?works in a room as it does in a 1:1. The agent is told only about the files of the person whose message woke it, so in a room with two people the other person's files go unmentioned for that turn. See Shared Sessions.

Do files I attached in a 1:1 come along when I @mention another agent?

Yes. Files you attached in that 1:1 and have not yet sent with a message go along: the composer's attachment chips, and files sent from the rail's Filestab in the last 15 minutes. The Workspace delivers them to the newly mentioned agents before it posts your message, so the agent can see what you asked about. A line under the room's composer then names what was delivered and to whom, and what did not arrive: a file that missed an agent (attach it again here to retry) or one that never finished uploading. See Workspace.

Can an agent read another agent's metrics?

Yes, if it holds a permission grant on that agent, the same grant chat_with_agentuses. The agent passes the other agent's name as agent to get_metrics; without a grant the read is refused. Cross-agent reads count against the reader's own rate budget and are recorded in the audit log under the reading agent. See Agent Permissions.

How can I watch agents collaborating on the Dashboard?

Use the Dashboard's Timelineview (the default): it replays the fleet's activity and collaboration events — chat start/end, tool calls, schedule start/end, and agent-to-agent calls — each stamped with a state (started, completed, failed, cancelled) and scrubbable over a time range you choose. Agent-to-agent calls appear as collaboration events in that stream, so you can see which agents called which as it happens. The older node-and-edge network canvas has been retired in favor of this Timeline replay; a separate Grid view arranges agents as tiles for at-a-glance status. See Agent Network.

Can I deploy a whole team of agents in one step?

Yes, with a system manifest: a YAML file listing the agents (name, template, configuration) plus permission presets, shared folder wiring, schedules, tags and auto-start settings. Install it from Library → Systems— pick a bundled manifest, upload a file, or paste YAML, then Preview (validates without creating anything and shows the agent names, who can call whom, and any schedules that would start) and Deploy — or use the deploy_system MCP tool or the REST API, which offer the same dry run. You need the creator role, because installing a system creates agents. It's a recipe deployment: once created the agents are independent, and deploy is best-effort, so read the result's status and its "things needing attention" list rather than trusting the HTTP code. See System Manifest.

Can I remove a whole deployed system in one step?

Not in a community build: remove the system's agents one by one. Removing a whole system — the Remove a deployed systempanel under Library → Systems and the teardown_systemMCP tool — needs a matching entitlement. The tool previews by default and removes nothing unless you set dry_run to false. See System Manifest.

How do I restart all agents in a system at once?

Use the restart_system(name) MCP tool or POST /api/systems/{name}/restart. Membership is by tag, not by name: deploy tags every member with the system name and the restart resolves members from that tag (only agents deployed before tagging existed fall back to the name prefix), so restarting acme never touches a system called acme-extra. Trinity stops the running members, starts each again, and reports which restarted and which failed — handy after changes that need a container restart, such as shared folder updates. It requires the creator role and is human-only: an agent-scoped API key is refused, because a bulk restart would let an agent touch agents it didn't spawn. See System Manifest.

Can I export a deployed system as a manifest and deploy it again somewhere else?

Yes. GET /api/systems/{name}/manifest (or the get_system_manifestMCP tool) writes a manifest from the system's current members — their permissions, shared folders and real schedules — that you can hand to deploy_systemagain. Two things are deliberately left out: permission edges pointing at agents outside the system are dropped rather than exported as broken names, and your instance-wide platform prompt is never embedded as the manifest's prompt: key, because deploying that export elsewhere would overwrite the prompt for every agent on the other instance. Keep the redeploy caveat in mind: deploying a manifest where those agent names already exist creates suffixed copies (_2, _3). To bring an existing system in line with a manifest instead, use apply_system (POST /api/systems/apply), which previews by default and creates only what is missing. See System Manifest.

Can external orchestrators discover and call my Trinity agents?

Yes — discover and call. Every agent publishes an A2A Agent Card (protocol 0.3.0) at GET /api/agents/{name}/a2a/agent-card— a standard JSON document (built from the agent's template.yamland container labels) advertising its name, description, capabilities, skills, and URL, so external orchestrators can discover it without knowing Trinity's internal API. That endpoint requires authentication (owner, admin, or shared user, via JWT or MCP key), and it still returns a partial card when the agent is stopped.

To let an outside orchestrator actually reach an agent, turn on exposure in the agent's A2A tab. That tab appears only when the A2A capability is enabled for your instance; otherwise it is hidden and the public routes answer 404. Exposure is off by default, and until you enable it nothing is publicly reachable. Once enabled, the agent gets a public discovery card at GET /a2a/{name}/.well-known/agent-card.json and a JSON-RPC task endpoint at POST /a2a/{name} (message/send, message/stream over SSE, tasks/get, tasks/cancel). Discovery is unauthenticated and rate limited per IP; tasking always requires a credential— a Trinity MCP API key, whose holder still has to be an owner or shared user of that agent, or, once AAuth is switched on, a request signed by an agent on another Trinity instance whose identity is on the agent's inbound allow-list. A caller with neither is refused whatever network it arrives from. A non-exposed agent is indistinguishable from one that doesn't exist — both return 404.

Set PUBLIC_CHAT_URL or FRONTEND_URL so the card advertises an externally reachable URL. See A2A Protocol.

Can my agents call an external A2A agent?

Yes — this is the outbound direction, and it's off by default. An admin turns it on and registers each external endpoint by name (with any credential it needs); an agent then picks a target by nameand can never supply a URL of its own, so a prompt injection can't aim Trinity at an address of the attacker's choosing. Agents call it with the call_a2a_agent tool and poll long-running work with get_a2a_task. Calls are bounded — 30 per minute per agent, 120 fleet-wide — and each one is deduplicated by a label you supply, so a re-run replays the earlier answer instead of paying twice. See A2A Protocol.

How do I let an agent on another Trinity instance call my agent without handing out a key?

Turn on AAuth on both instances. In Settings › Integrations, each admin sets the Issuerto their instance's public HTTPS host and flips Sign and accept agent-to-agent callson — the panel reads Liveonce both are set. On your side, expose the agent over A2A and add the calling agent's identity, aauth:<agent>@<their-host>(the other admin's panel prints it), to its inbound allow-list. On their side, the admin registers your agent's A2A URL on the Outbound A2A endpoints panel with Authentication set to AAuth (signed as the agent), and their agent calls it with call_a2a_agent. Every call is then signed by their instance and verified by yours; nothing is issued, stored or rotated, and revoking access is deleting the allow-list entry. Only the agent's own key can place a signed call, and a remote 403 means the identity is not on the list yet. See A2A Protocol.

Why does an A2A call from my own private network now need a credential?

Because the network a call arrives from no longer says anything about who sent it. Earlier builds let a call from a trusted network range task an exposed agent with no key; that path is gone, and every inbound A2A call now needs a Trinity MCP API key or a signed AAuth identity, whichever network it comes from. The admin trusted-networks list still exists, but it only governs outbound calls: it lets your agents call a peer on a private address or over plain http:// that the SSRF check would otherwise refuse. For your own instances on a tailnet or VPN, keep the host on that list and give the endpoint a key from the provider instance, or turn on AAuth on both sides. See A2A Protocol.

My A2A call came back as working — did it fail?

No. It means the remote agent is still on the turn. A Trinity instance holds an inbound message/send for 25 seconds; a turn that finishes inside that window returns the completed task, a longer one returns early with the task id and working (or submittedwhile the agent's queue has not started it) and keeps running. Poll tasks/getwith that id — from an agent, get_a2a_task(endpoint, task_id)— until the state is terminal; a refused task reads as rejected with the reason and never stays working. Do not re-send the message, which would ask the question twice; a disconnected caller does not cancel the turn, so the result waits for you. A caller that needs the old behaviour can send configuration.blocking: true to wait for the terminal state however long it takes. See A2A Protocol.

An outbound A2A call timed out — should I just try again?

No, not blindly. A timeout means Trinity gave up waiting, not that the remote agent didn't run the task — the response says possibly_delivered for exactly this reason. (A long turn on a Trinity remote is not a timeout: the remote answers working with a task_id after 25 seconds, and you poll that.) If you have a task id, poll it with get_a2a_task. Otherwise re-send with the same dedup label: that replays the original answer if the call already completed, rather than triggering the work a second time. See A2A Protocol.

Can my agent message me proactively instead of waiting for me to ask?

Yes, with the send_message MCP tool. The agent names a role with to — primary, approver or viewer— and the platform resolves the person. When nobody holds the primaryseat, the message goes to the agent's owner, who is always allowed proactive messages (if the owner has no email address, the send is refused and names the remedy: assign a primary in the agent's Access tab). Any other role nobody fills, or a role several people fill, is refused by name. Addressing by recipient_emailstill works but is deprecated. It's consent-based: the recipient must be the agent's owner or have the agent shared with them with the allow-proactive flag enabled, otherwise the send is rejected. Delivery goes over Telegram, Slack, or web — autotries Telegram, then Slack, then web — and sends are rate-limited to 10 messages per recipient per hour, with a 4096-character limit per message. A recurring agent that must not repeat itself can pass an idempotency_key (with an optional idempotency_ttl, 60 seconds to 24 hours, default 24 hours): a second send with the same key to the same person inside that window is not delivered, even from a different run. See MCP Server.

Can my agent ask a specific person a question and wait for their answer?

Yes. When an agent parks a request in its operator queue it can address it to one person it is shared with (addressed_to_email). The ask reaches that person's Workspace Inbox. An ask raised during a chat turn appears as a tile inside that chat's conversation, placed where it was asked, and you answer it right there; once it has ended it stays in that chat's history as one muted line (kind · title · how it ended · when). An ask raised outside any chat — by a scheduled run, a loop or a gate — appears in no chat, only in the Inbox; your reply to it lands in your Main chat with that agent. Exception: an ask raised from a reminder the agent set during your own session appears as a tile in your Mainchat directly. Operators still see it in the Operations queue. The answer is the decision the agent reads: for an approval that listed options it must be exactly one of them — anything else is refused with a 422naming the offered options — and a note is optional, never standing alone. Answering removes the ask everywhere at once; an expired ask stays visible, marked expired, and the agent treats expiry as "not approved". Someone the agent isn't shared with can't be addressed — the item becomes an ordinary operator ask instead. An ask addressed by role (to) to a role that several people fill reaches every one of them: the first answer ends it, the others see who answered, and none of them can dismiss or discuss it. See Approvals.

What happens when an agent asks a question during a room conversation?

The room records it: one line when the ask is raised ({agent} asked: “{title}” — waiting on {who}) and one when it ends. The ask itself reaches its addressee as usual, in their Inbox. Once it is answered, the agent continues in that room with a room turn and posts its reply there, as long as the room is open, the agent is still in it and the room is under budget; otherwise it is woken the ordinary way. The room lines never show the answer or a note, and name a person only if they are seated in the room. See Approvals.

Why does a card say it is waiting on someone else, and what happens when the agent's primary contact changes?

A decision addressed to a person or a role can only be made by them, so the refusal names who it waits for — the seat, plus the people on a gated-skill approval, never people on a role ask. An admin can still end the card, with a reason. When the agent's primary contact changes, its pending asks addressed to primaryand its pending gated-skill approvals move to the new person, so they don't wait on someone who no longer holds the seat. See Approvals.

I answered my agent's request but nothing happened — why?

By default answering starts one turn of the agent immediately — that run shows in Executions with the trigger operator_response— and the agent acts on the decision in it; a cancellation wakes it the same way (trigger operator_ending). If the agent was not running when you answered, nothing starts it: the ask reads Agent not yet woken — it picks this up when it next runs, and the agent's next start delivers the answer. Check Wakes when an ask ends in the agent's Settings → Reliability: switched off, an answer is only read at the start of the agent's nextturn — its next scheduled run, loop iteration or message — so an agent with no schedule and nobody chatting to it waits indefinitely even though the decision was recorded. An expiry never wakes the agent; it reads the timeout on its next turn. It's a per-agent switch the owner controls, never something a request can ask for. The Workspace confirmation tells the answerer which case applies — Sent. versus Sent — {agent} is picking this up. See Wake When an Ask Ends.

What does it mean when an agent's ask shows as withdrawn?

The agent ended its own ask because it no longer needed an answer — the question answered itself, or the action is no longer needed — and nothing is asked of you. The ask leaves the Action tab and stays in your Inbox history for 7 days as Withdrawn by the agent, with the agent's one-line reason under it; the Operations page's Resolved tab shows the same. This differs from a replaced ask, where the agent asked again with new terms and the new ask names the old one. An agent can withdraw only an ask nobody has answered yet; once you answer, your answer stands. See Approvals.

How does an agent deliver a report to a specific person?

By addressing it: the report MCP tool takes a role in to (primary, approver or viewer) and the platform resolves the person from the agent's own roster. The older audience_email still works but is deprecated; to: operator publishes an operator-only report. An addressed report is a deliverable: it appears in that person's Workspace under the rail's Info → Reports for that agent and, if the agent also passed its current execution_id, as a Delivered herecard at the end of the chat that produced it. A report published outside a chat — from a scheduled run, for instance — lists under Info only. Unaddressed reports stay operator-only and never appear in the Workspace, so an agent that addresses no one simply shows its clients an empty Reports section. See Agent Reports.

What happens when someone rates a deliverable, and what does the agent get to see?

Each deliverable card carries Useful / Not what I needed; one click records the rating, and a negative one also opens an optional comment box. It's one rating per person per deliverable — clicking the other option corrects it, and there is no un-rate. When the agent reads its ratings back it gets tallies only: that it was rated up or down, never the words and never who, because a comment is untrusted text from someone who is, by construction, annoyed, and handing it to the thing being criticised is a prompt-injection path. The agent's owner and admins read comments in full: a negative rating raises a heads-up in the operator queue (once per person per deliverable per day) that only they see, and a comment typed after the click is added to that same heads-up. The only route by which the words reach an agent is a capture-feedbackskill, run in a background turn of its own and never posted into your chat — which is why the acknowledgement reads either passed on to the agent or recorded for the team. See Agent Reports.

My agent handed work to another agent that finished after I left the conversation — where does the result go?

Back to the conversation it started from, success and failure alike, when the agent handed it off in the background: chat_with_agent(..., parallel=true, async=true)reports back by default, while a plain sequential delegation is answered inside the agent's own reply and does not report separately. A Slack channel or Telegram group that doesn't allow such notes gets none. A job that began in a Workspace chat and finished later — because the agent delegated it or kicked off background work — lands as a message from the agent in that chat, filed under the agent you were talking to and naming the one that did the work when that differs; it opens with Finished or Didn't finishplus the status, so a failure never vanishes. The same report-back reaches a Slack channel or thread, a Telegram chat, and — for a scheduled run addressed to someone — that person's Mainchat with the agent. Each finished job reports at most once and never to a conversation it didn't start from, and an ordinary turn that already answered inline isn't reported a second time. The Workspace doesn't push it while you watch; it's there on the next load or chat switch. See Event Subscriptions.

What's the difference between an agent loop and agent collaboration?

A loop runs the same task against one agent repeatedly with a bounded run count — it's single-agent automation, not communication. Collaboration is different agents calling each other via MCP: delegation, orchestrator-worker patterns, events, and shared folders. Use a loop to grind through a backlog on one agent; use collaboration when the work needs to move between agents. See Agent Loops.