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 { queryOptions } from "@tanstack/react-query";
import { client, tryClient } from "@/lib/client";
export type AgentVisibility = "public" | "private";
/**
* A coworker as the browser sees it.
*
* `canManage` and `systemOwned` are server-decided authorization facts; components render from the
* returned flags rather than recomputing ownership rules.
*/
export type AgentProfile = {
id: string;
name: string;
title: string;
roleDescription: string;
avatarSeed: string;
visibility: AgentVisibility;
/** Where this coworker runs. Null for the Bot in the box. */
endpoint: string | null;
/**
* Whether it runs on this deployment's own Bot.
*
* Creating a coworker with no endpoint stores the deployment's managed address, so `endpoint`
* alone cannot tell "built-in" from "hosted by a person" — and the difference decides whether the
* Connection screen asks for a callback token. A built-in coworker calls tools back with the
* deployment's own credential and needs no setup at all.
*/
builtIn: boolean;
/** Whether a key is set for it. Never the key itself. */
hasAuth: boolean;
/**
* Whether this coworker holds a credential for calling tools back.
*
* A boolean, because the token is readable exactly once: in the response that issued it. The
* surface needs this only to decide between offering "generate" and "rotate".
*/
hasCallbackToken: boolean;
hidden: boolean;
/** Whether the signed-in person pinned it to the top of their Bots list. Nobody else's. */
pinned: boolean;
/** A Team Bot an administrator assigned to this person; their Bots list always pins it. */
assignedToMe?: boolean;
systemOwned: boolean;
canManage: boolean;
/**
* Whether the signed-in person created this coworker.
*
* Separate from `canManage`, which is also true for administrators on everybody's coworkers. Split
* a roster on `canManage` and an administrator's "mine" fills up with other people's work.
*/
mine: boolean;
/**
* Whether its owner gave it a computer of its own, rather than letting it share theirs.
*
* What was asked for. Whether it is happening is `isolationActive`: an administrator can withdraw
* "Isolated Bots" from the owner, and the Bot then runs on a shared computer with this still true,
* so that giving the switch back restores it.
*/
isolated: boolean;
/** Whether its next run gets that computer of its own. Decided by the server from the owner's switch. */
isolationActive: boolean;
/**
* Why an isolated Bot is running on a shared computer instead, or null. `admin`: the owner no
* longer holds "Isolated Bots". `deployment`: this OpenBot cannot make a second computer.
*/
isolationOffReason: "admin" | "deployment" | null;
};
/**
* Whether this is an agent shared with you: made public by somebody else, not your own.
*
* Written once so every list of "shared with you" — the home screen's carousel among them — filters
* through this rule rather than a copy of it.
*/
export function isSharedWithYou(agent: AgentProfile): boolean {
return !agent.mine && agent.visibility === "public";
}
export const agentKeys = {
all: ["agents"] as const,
list: (hidden = false) => ["agents", "list", { hidden }] as const,
detail: (agentId: string) => ["agents", "detail", agentId] as const,
botRouteDetail: (agentId: string) =>
["agents", "bot-route-detail", agentId] as const,
handoff: (agentId: string) => ["agents", "handoff", agentId] as const,
capabilities: () => ["agents", "capabilities"] as const,
};
/** What kinds of coworker this deployment can create. */
export type AgentCapabilities = {
/** Whether a coworker can run on the deployment's own Bot, with no endpoint of its own. */
builtInAvailable: boolean;
/**
* Whether this deployment can give a Bot a computer of its own at all.
*
* Only where its computers are made one at a time (the supervisor, or a cluster's sandboxes).
* Whether the signed-in person may is a different question, answered by the "Isolated Bots"
* switch in `myCapabilitiesQueryOptions`.
*/
isolationAvailable: boolean;
};
export function agentCapabilitiesQueryOptions() {
return queryOptions({
queryKey: agentKeys.capabilities(),
queryFn: (): Promise<AgentCapabilities> =>
client("/api/agents/capabilities", "capabilities", {
fallback: "Could not load what this deployment supports",
}),
// Deployment configuration, not data: it cannot change without the server restarting.
staleTime: Number.POSITIVE_INFINITY,
});
}
/** Which Bots one Bot may hand work to, and whether this deployment lets it. */
export type HandoffGrants = {
/**
* Whether the capability is switched on at all.
*
* Separate from the grants because the two fail differently: with this false, a grant is a row
* nothing will ever read, so the screen says so rather than offering a switch wired to nothing.
*/
enabled: boolean;
/** Whether the signed-in person may change any of it. Granting is an administrator's. */
canGrant: boolean;
/** Bot ids this Bot may address today. */
reachable: string[];
/**
* Whether this Bot can hold such a grant at all.
*
* The handing-on tool executes inside this deployment's own run loop, so only a Bot that runs in
* it can be offered one. False means every grant would be refused, and the screen should say that
* once instead of letting each switch bounce with the same message.
*/
grantable: boolean;
};
export function agentListQueryOptions(hidden = false) {
return queryOptions({
queryKey: agentKeys.list(hidden),
queryFn: (): Promise<AgentProfile[]> =>
client(`/api/agents${hidden ? "?hidden=true" : ""}`, "agents", {
fallback: "Couldn't load your Bots.",
}),
});
}
/** Package-defined IDs remain one path segment without changing their stored or cache identity. */
export function agentApiPath(agentId: string): string {
return `/api/agents/${encodeURIComponent(agentId)}`;
}
export function agentQueryOptions(agentId: string) {
return queryOptions({
queryKey: agentKeys.detail(agentId),
queryFn: (): Promise<AgentProfile> =>
client(agentApiPath(agentId), "agent", {
fallback: "Couldn't load this Bot.",
}),
});
}
export function agentHandoffQueryOptions(agentId: string) {
return queryOptions({
queryKey: agentKeys.handoff(agentId),
queryFn: (): Promise<HandoffGrants> =>
client(`${agentApiPath(agentId)}/handoff`, "handoff", {
fallback: "Could not load which Bots this one may ask",
}),
});
}
/** What the server said when it tried the endpoint. */
export type ConnectionVerdict =
| { ok: true; events: string[] }
| { ok: false; reason: string };
/**
* Ask the server to reach a coworker's endpoint, from where a run will reach it.
*
* A plain function rather than a factory: the answer is about this moment, nothing caches it, and
* there is no key for anything to invalidate. Fails closed, like the other verdicts here — an
* endpoint that cannot be tested is reported as unreachable rather than thrown at the form.
*
* The unsaved key is sent so the test matches the form as it stands, not as it was last saved.
*/
export async function testAgentConnection(
endpoint: string,
key: string,
): Promise<ConnectionVerdict> {
try {
const response = await tryClient("/api/agents/test-connection", {
method: "POST",
body: {
endpoint,
...(key.trim() ? { headers: { Authorization: key.trim() } } : {}),
},
});
const body = (await response.json().catch(() => null)) as
| ConnectionVerdict
| { error?: string }
| null;
if (body && "ok" in body) return body;
return {
ok: false,
reason:
(body as { error?: string } | null)?.error ??
"The connection could not be tested.",
};
} catch {
return { ok: false, reason: "The connection could not be tested." };
}
}