Skip to content

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.

8.7 KB
Raw Blame
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 };
}