@orbytelabs/agent

Create, inspect, and delete Teamy agents from Node.js 20+ using ESM. Set ORBYTE_API_KEY to a secret key on your server.

import {
  createAgent,
  deleteAgent,
  getAgent,
  listAgents,
} from "@orbytelabs/agent";

const created = await createAgent({
  name: "Support",
  instructions: "Investigate support incidents and report findings.",
  tools: ["readWebPage", "searchKnowledge"],
  reasoningLevel: "off",
});
const agents = await listAgents();
const agent = await getAgent(created.id);
await deleteAgent(created.id);

Creation requires name and instructions. Optional model selects a supported model; omission uses the runtime default. Optional reasoningLevel accepts off, low, medium, or high and defaults to off. Models without reasoning support use off. Trimmed names allow 1–200 characters, instructions 1–100,000, and model IDs 1–128. Unknown fields are rejected.

Agent objects contain id, name, instructions, model, reasoningLevel, tools, and optional description. Appearance fields such as icon and color are excluded. The key selects the application. Pass an agent ID to run() from @orbytelabs/run.

listAgents() returns an array, possibly empty. getAgent(id) and createAgent(input) return one agent. deleteAgent(id) resolves without a value. Deletion removes the agent and its revision history, retains threads and automations, and does not cancel running threads. Automations referencing the deleted agent cannot start new runs with it.

Tool names use the exported AgentToolName literal union, so editors suggest valid names and TypeScript rejects typos. Generation derives the union from the backend tool registry without including backend code in the SDK. The API validates tool names at runtime. Omit tools or pass [] to use all default tools. A nonempty array enables only those tools from the current catalog. New tools added to the platform later follow the default enabled behavior. Responses include the resolved enabled names. Connection permissions, approval rules, and subagent restrictions still apply.

All functions accept { client: { apiKey, baseUrl, fetch }, signal } as their options argument. Core reads ORBYTE_API_KEY and ORBYTE_BASE_URL by default. Custom API URLs must use HTTPS, except HTTP loopback servers for local development.

HTTP failures throw OrbyteError from @orbytelabs/core, with status and an API code when available. Missing or inaccessible agents return 404, including repeat deletion. Invalid input shapes fail local validation; unknown tool names are rejected by the API. Network failures reject directly. Creation is not idempotent and is never retried automatically.