Remote agents

An agent normally reasons on a model your workspace calls. It can instead
reason somewhere else: at an endpoint you run, speaking the
AG-UI protocol, which is what agents built with
LangGraph, CrewAI, Mastra, Pydantic AI and Google ADK already speak.

Your workspace still supplies the tools, the rules and the record. Every call
the remote asks for passes the same permission check, scope check, approval
gate, destructive-action backstop and audit row as any other agent's.

Setting one up

Open Settings, Agents, edit or create an agent, and open Advanced.

• Remote agent (AG-UI endpoint) is the URL your agent answers on.
• Auth header is the header name the secret travels in. Leave it empty for
  Authorization: Bearer.
• Secret is the credential. It is stored encrypted and never shown again.

Press Test connection. It runs the real client against the real endpoint
with the real credential, so what it proves is what a run will do.

What the endpoint must be

A run does not send a question. It sends the agent's instructions, the
workspace knowledge it is grounded in, the conversation so far, and the result
of every tool your workspace ran for it.

So an endpoint that resolves outside your own network must use https and must
have a secret. One on your own network, such as a bot in the same compose
file reached at http://agent-bot:4200, needs neither.

This is decided by the address actually dialled, not the hostname typed, so a
name that resolves to the public internet cannot slip past it. In local-only AI
mode nothing off your network is reachable at all.

Quick tunnels will not work

Putting an agent that runs on your laptop behind https usually means a tunnel,
and Cloudflare's quick tunnels (trycloudflare.com) are the fastest way to get
one. They do not carry server-sent events, which is how AG-UI answers, so
the request succeeds and no events ever arrive.

Use something that streams:

• a named Cloudflare tunnel, rather than a quick one
• ngrok, or another tunnel that supports server-sent events
• a real address on a host you control

If you hit it anyway, the error says so by name.

What is governed and what is not

Everything the remote asks your workspace to do is governed. Whatever it does
on its own machine, such as a browser it drives or a shell it runs, is outside
your workspace and outside those checks. Those actions appear in the run
transcript marked remote, as the remote's own account, and are left out of the
count of actions your workspace took.

The run's audit row names the remote by host only. The path is not recorded,
because it can carry a routing token, and the secret never reaches a row.

A remote agent's model spend happens on its own account, so the per-agent daily
token limit cannot apply to it. Its step limit still does.

When something is wrong

What you see	What it means
remote answered 401	The secret or the header name is wrong.
refusing to send workspace content ... over plain http	The endpoint resolves off your network and is not https.
refusing to send workspace content ... with no secret	The endpoint resolves off your network and has no secret set.
That address is blocked	A cloud metadata or link-local address, which no agent endpoint should be on.
the remote answered but sent no events	Something between your workspace and the agent is buffering or stripping the stream. A quick tunnel does this.
ended the stream without finishing the run	The agent started answering and stopped. This one is the agent, not the network.