Guide

Bring your own agent

Connect an agent you already run, built with LangGraph, CrewAI, Mastra or anything else that speaks AG-UI, as a coworker people work with in the workspace.

4 min read

How it worksCopy link to this section

AG-UI is an open protocol for talking to agents: the workspace sends one request with the conversation, and your agent answers with a stream of events. The workspace dials your agent's address on every run, so the agent keeps running where it is, with its own code, model and tools.

  • People find the coworker and start channels with it like any other, and its visibility works the same way: private to you, or public to everyone in the workspace.
  • Its name, title and role reach your agent as one system message at the start of every run, followed by the channel's messages, so the agent knows which coworker it is playing.
  • Its model is chosen by your agent, not by the workspace.
  • Tools your agent runs on its own side are governed by your service, not by the workspace's approvals and boundary rules. Give it only the access you would give any service.

Serve your agent over AG-UICopy link to this section

LangGraph, CrewAI and Mastra each have an AG-UI integration that serves an agent at a web address, and any other framework can answer the same requests itself. Whichever you use, the address has to:

  • accept a POST with a JSON body and answer with a stream of server-sent events (text/event-stream);
  • be reachable from the workspace over the internet. An agent on your own computer needs a tunnel or a public address; private and internal network addresses are refused;
  • check a key, if you set one: the workspace sends it as the Authorization header on every run.

Add it as a coworkerCopy link to this section

  1. Start a new coworker and give it a name, a title and a role. The role is what your agent is told it is for, so write it as you would for any coworker.
  2. At Where does it run? choose Managed, and enter your agent's address as the Agent endpoint.
  3. If your agent checks a key, enter it under Key for that agent (optional) exactly as the header should carry it, such as Bearer followed by the token. It is kept in the credential vault, and a changed or removed key takes effect on the next run.
  4. Select Test, read the answer as below, and create the coworker.

A coworker made with Build your own can do the same: under Bring your own agent (optional), switch on Run at my own AG-UI endpoint.

Signed runs and how they wentCopy link to this section

On the coworker's Health tab, switch on signing for the runs sent to your agent. The secret is shown once, so copy it into your agent then; replacing it makes a new one and the old one stops matching.

  • Each run then carries Synthia-Signature: t=<unix seconds>,v=<secret version>,v1=<hex>. The hex is HMAC-SHA256 under the secret over the seconds, a dot, and the raw request body.
  • Refuse a run whose signature does not match, or whose time is more than five minutes from yours. Check the signature before you read the body as JSON.
  • The same tab shows how the runs sent to your agent went over the last day and week: how many were answered, how long the answer took to begin, and the last failure's reason. Administrators see every such coworker together under Admin › Bot fleet.

The test buttonCopy link to this section

Test sends your agent one real run with a short automated message, from the workspace's own server (where every run comes from), and waits up to 15 seconds. It reads only the opening of the answer and then hangs up, so a long reply does not hold the form open.

What you seeWhat it means
It answered, with a list of eventsYour agent is reachable and speaks AG-UI. The events are the kinds it sent back.
The agent refused this requestIt answered 401 or 403: it wants a key, or a different one.
The agent answered with another statusSomething is at that address, but it did not accept the run. Check the path is the agent's AG-UI path.
It answered, but not with AG-UI eventsThe address returned a page or other content. It is often the server's home page rather than the agent's path.
The agent did not answer in timeIt may still be starting, or the address cannot be reached from the workspace.
The address could not be reached, or is not allowedNothing answered from the workspace's side, or the address is a private one. Use a tunnel or a public address.

Last updated