@orbytelabs/run

Run an existing Teamy agent from Node.js 20+ using ESM. Set ORBYTE_API_KEY to a secret key on your server. Discover agent IDs with @orbytelabs/agent.

import { run } from "@orbytelabs/run";

const execution = run("AGENT_ID", "Investigate incident INC-184.");
for await (const event of execution.stream()) {
  if (event.type === "text-delta") process.stdout.write(event.text);
}
const result = await execution.result();
console.log(result.text, result.hasPendingAction);

Execution modes

run() is lazy. The first consumer selects the request mode:

| Operation | Behavior | | ---------------------------- | ------------------------------------------------------------- | | Iterate execution.stream() | Stream events over POST /threads. | | await execution.result() | Consume the stream and return the saved result. | | await execution | Submit background work and return { id } before completion. |

All operations reuse one request. execution.id becomes available once the backend returns the thread ID. Only one stream consumer can be active. Call result() after the loop, including after an early break, or on its own. It waits for an active consumer; awaiting it inside that consumer's loop would deadlock. Repeated result calls share a promise.

After background submission, stream() and result() reject with execution_mode_conflict. Awaiting an already streaming execution returns its ID without detaching it. Promise.resolve(execution) and Promise.all([execution]) also select background mode for an execution that has not started.

Events and results

Append text-delta.text by block id. Tool calls, results, and errors share a toolCallId; tools may run in parallel. A tool-result marked preliminary can be followed by a final result or error. Tool-input deltas may be incomplete JSON; use tool-call.input for complete input.

Events include model and step lifecycle, reasoning, tool approvals, sources, and generated files when emitted. Provider request/response internals and private metadata are excluded. finish ends generation; the terminal status confirms the saved result. result() returns that status with optional final text. Check hasPendingAction even after success and resolve it in Teamy.

Configuration and errors

Pass { apiKey, baseUrl, fetch, signal } as the third argument. Core reads ORBYTE_API_KEY and ORBYTE_BASE_URL; the default URL is https://api.teamy.run/api/v1. Custom URLs must include /api/v1 and use HTTPS, except HTTP loopback for local development. Trust any custom destination or transport with your credentials and prompt.

HTTP failures throw OrbyteError from @orbytelabs/core, with status and API code when available. result() rejects with execution_failed for a failed status, execution_aborted for an abort event, or an error event's code. Invalid input fails local validation; network failures reject directly. An SSE event exceeding 16,777,216 string characters rejects with stream_event_too_large.

An AbortSignal cancels the request. Streaming is tied to its HTTP connection; disconnecting may interrupt generation. An incomplete stream rejects with stream_interrupted or a transport error. Use core's GET /threads/{id} to inspect saved state. There is no reconnect or automatic creation retry.

Use const { id } = await run(agentId, prompt) for background work and read status later or configure a completion webhook in Teamy. Cancelling submission does not cancel an accepted background execution.