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
Authorizationheader on every run.
Add it as a coworkerCopy link to this section
- 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.
- At Where does it run? choose Managed, and enter your agent's address as the Agent endpoint.
- If your agent checks a key, enter it under Key for that agent (optional) exactly as the header should carry it, such as
Bearerfollowed by the token. It is kept in the credential vault, and a changed or removed key takes effect on the next run. - 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 see | What it means |
|---|---|
| It answered, with a list of events | Your agent is reachable and speaks AG-UI. The events are the kinds it sent back. |
| The agent refused this request | It answered 401 or 403: it wants a key, or a different one. |
| The agent answered with another status | Something 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 events | The 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 time | It may still be starting, or the address cannot be reached from the workspace. |
| The address could not be reached, or is not allowed | Nothing answered from the workspace's side, or the address is a private one. Use a tunnel or a public address. |
Last updated