Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import {
checkAgentEndpoint,
createAgentFetch,
EndpointNotAllowedError,
} from "./endpoint";
/**
* Ask an endpoint whether it is really an agent before it is stored.
*
* The registration form is the cheap point to distinguish a typo, a dead host, and a reachable
* service that is not an AG-UI agent.
*
* AG-UI requires one POST to the endpoint returning an SSE stream of events (`@ag-ui/client`'s
* `HttpAgent` is `{ url, headers?, fetch? }`). The test is a real run with a trivial message.
*/
/** How long an endpoint gets to answer. Short: this is a person waiting on a form. */
const TEST_TIMEOUT_MS = 15_000;
/** Enough of the stream to prove it is an agent. Reading it all could mean reading a whole reply. */
const MAX_BYTES = 8_000;
/**
* The opening of the answer, and then stop reading.
*
* The cap above was applied to a string this process had already taken in full, because
* `response.text()` reads a body to its end. An agent that streams — which is what an agent does —
* therefore held the form open for as long as its run took, and if that outlasted the timeout the
* abort came back through `text()` as a rejected read: `ok: false`, status 200, "The agent started
* answering and the connection broke." Nothing broke. The agent had answered correctly, in the first
* two events, and the person registering it was told to go and look at their own service.
*
* Counted in bytes, which is what the cap is named in and what a chunk off the wire is measured in.
* The chunk that crosses the cap is kept whole rather than cut at it: it is one read past the cap at
* most, and a cut through a multi-byte character would put a replacement character in the middle of
* a line the scan is about to read.
*/
async function readOpening(body: ReadableStream<Uint8Array>): Promise<string> {
const reader = body.getReader();
const decoder = new TextDecoder();
let text = "";
let bytes = 0;
try {
while (bytes < MAX_BYTES) {
const { done, value } = await reader.read();
if (done) break;
bytes += value.byteLength;
text += decoder.decode(value, { stream: true });
/*
* ONE RECOGNISED EVENT IS THE WHOLE QUESTION, so stop on it.
*
* The cap and the end of the stream were the only two ways out, and an agentic harness
* supplies neither: it opens with `RUN_STARTED` — ninety bytes, nowhere near the cap — and
* then goes away to call a model and run tools, holding the stream open for as long as that
* takes. The read therefore waited out the whole run and was cut off by the request timeout,
* which surfaced as "The agent started answering and the connection broke" about an agent
* that had answered correctly in its first event. Measured against `agent-antigravity`.
*
* Events rather than bytes, because bytes prove nothing: a stream of SSE comments or
* heartbeats would satisfy a "something arrived" test while being no evidence of an agent.
*/
if (eventTypesFrom(text).length > 0) break;
}
} finally {
// The agent is very likely still writing. Nothing is going to read the rest, and leaving it open
// holds a socket into somebody's agent for as long as that run cares to go on.
void reader.cancel().catch(() => undefined);
}
return text;
}
export type ConnectionTestResult =
| {
ok: true;
/** The AG-UI event types that came back, in order, so a person sees it really answered. */
events: string[];
status: number;
}
| { ok: false; reason: string; status?: number };
/**
* The smallest thing that is still a real run.
*
* Not a HEAD or a bare GET: plenty of things answer those. Only a POST that produces AG-UI events
* distinguishes "an agent" from "a web server that happens to be reachable".
*/
function probeBody() {
return {
threadId: `openbot-connection-test-${crypto.randomUUID()}`,
runId: `openbot-connection-test-${crypto.randomUUID()}`,
messages: [
{
id: crypto.randomUUID(),
role: "user",
content:
"This is an automated connection test from OpenBot. Reply with one short word.",
},
],
tools: [],
context: [],
state: {},
forwardedProps: {},
};
}
/** Pull `event:`/`data:` type names out of an SSE body, which is how AG-UI reports what it did. */
function eventTypesFrom(text: string): string[] {
const types: string[] = [];
for (const line of text.split("\n")) {
const trimmed = line.trim();
if (trimmed.startsWith("event:")) {
types.push(trimmed.slice("event:".length).trim());
continue;
}
// Most AG-UI servers put the type inside the JSON payload rather than on an `event:` line.
if (trimmed.startsWith("data:")) {
try {
const parsed = JSON.parse(trimmed.slice("data:".length).trim()) as {
type?: unknown;
};
if (typeof parsed.type === "string") types.push(parsed.type);
} catch {
// A fragment of a longer line. Not worth reporting: the summary is about whether events
// arrived at all, and one unparsed chunk does not change that answer.
}
}
}
return [...new Set(types)];
}
/**
* Try an endpoint and say what happened, in words a person can act on.
*
* Never throws. Every failure a person can cause, a typo, a dead host, an endpoint that answers HTML
*, comes back as a reason, because this is rendered next to the field they just filled in.
*/
export async function testAgentConnection(
rawEndpoint: unknown,
options: {
headers?: Record<string, string>;
allowPrivateHosts?: boolean;
allowedHosts?: ReadonlySet<string>;
fetchImpl?: typeof fetch;
timeoutMs?: number;
} = {},
): Promise<ConnectionTestResult> {
// Use the same target check that governs storing the endpoint, so this form cannot probe internal
// addresses that registration would refuse.
const verdict = checkAgentEndpoint(rawEndpoint, {
allowPrivateHosts: options.allowPrivateHosts,
...(options.allowedHosts ? { allowedHosts: options.allowedHosts } : {}),
});
if (!verdict.allowed) return { ok: false, reason: verdict.reason };
// Wrapped rather than called directly, so the address the request finally lands on is checked too.
// Checking only what the person typed leaves the redirect as the way around it.
const doFetch = createAgentFetch({
...(options.allowedHosts ? { allowedHosts: options.allowedHosts } : {}),
...(options.allowPrivateHosts !== undefined
? { allowPrivateHosts: options.allowPrivateHosts }
: {}),
...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
});
let response: Response;
try {
response = await doFetch(verdict.url, {
method: "POST",
headers: {
"content-type": "application/json",
accept: "text/event-stream",
...options.headers,
},
body: JSON.stringify(probeBody()),
signal: AbortSignal.timeout(options.timeoutMs ?? TEST_TIMEOUT_MS),
});
} catch (error) {
// An address this deployment will not dial is a specific thing that happened, and the person
// registering can act on it: it names the address, or the hop their address sent us to.
if (error instanceof EndpointNotAllowedError) {
return { ok: false, reason: error.message };
}
const timedOut = error instanceof Error && error.name === "TimeoutError";
return {
ok: false,
reason: timedOut
? "The agent did not answer in time. It may be starting up, or the address may be unreachable from this server."
: "This server could not reach that address. If your agent runs on your own machine, it needs to be reachable from here, a tunnel, or somewhere this server can dial.",
};
}
if (!response.ok) {
return {
ok: false,
status: response.status,
reason:
response.status === 401 || response.status === 403
? "The agent refused this request. If it needs a key, add it as a header."
: `The agent answered ${response.status}. An AG-UI endpoint answers a POST with a stream of events.`,
};
}
let body: string;
try {
body = response.body ? await readOpening(response.body) : "";
} catch {
return {
ok: false,
status: response.status,
reason: "The agent started answering and the connection broke.",
};
}
const events = eventTypesFrom(body);
if (events.length === 0) {
// Reachable, and not an agent. The most useful thing to say is what it looked like instead.
const contentType = response.headers.get("content-type") ?? "nothing";
return {
ok: false,
status: response.status,
reason: `That address answered, but not with AG-UI events (it sent ${contentType}). Check it is the agent's AG-UI path and not its home page.`,
};
}
return { ok: true, events, status: response.status };
}