Build with Rebyte.

Build applications with a managed agent runtime, durable sessions, and tools.

Agents API6 min read

Start building

Terminal

pnpm add openai@7.15.0

Use Node.js 22+ and the official OpenAI client. Configure apiKey with your REBYTE_API_KEY and baseURL as https://api.rebyte.ai/v1. See the Quickstart for a complete example.

Our two application repositories serve different purposes:

SDKRebyte Agent SDKReact hooks, chat UI, server adapter, CLI and Rebyte extensions. Uses the official OpenAI client.Democommerce-agent-starterA complete commerce demo with catalog, cart and client functions. Clone it to run or customize the storefront.

The official OpenAI client: Call the Agents API with the official openai package, your Rebyte API key and the Rebyte endpoint. View supported features
Trace execution: Follow model calls, tool activity and token usage with execution traces tied to each session and turn. Explore observability
Control access: Isolate session files, restrict sandbox network access and keep service MCP credentials outside the sandbox in encrypted Vaults. Runtime security

Run your first session SDK and example app

On this page

Start building Core concepts From input to result Current availability Official OpenAI SDK SDK and example application Rebyte Agent SDK Commerce Agent Fixed Workflow Agents

Core concepts

Concept	Purpose
Agent	Reusable configuration: model, instructions, tools, and generation settings.
Environment	Optional compute and filesystem used by a session.
Session	Persistent execution and conversation state, with a resolved copy of the agent configuration.
Events and items	Events communicate inputs and progress; items retain messages and execution output.

A Turn tracks one unit of work inside a session. An Artifact is an immutable deliverable produced by a completed turn. A saved Agent can be reused across Sessions; each managed Session owns its own environment.

From input to result

Create a Session with an inline Agent definition or a saved Agent ID.
Provide input at creation or submit it through the Session events endpoint.
Receive text, tool activity, and lifecycle events as the runtime works.
Read the resulting Items, Turn status, and Artifacts.
Continue the Session with another task, or queue another task behind its active Turn.

Your application handles its UI and function tools. Rebyte manages execution and the Session's hosted environment. See Architecture.

Your application starts sessions and receives events and output from the Agents API. Rebyte runs the managed agent harness, which sends tool calls to the Sandbox and receives tool results. Rebyte provisions and manages both the runtime and the Sandbox.

Current availability

The production endpoint is https://api.rebyte.ai/v1. Use http://127.0.0.1:34567/v1 only with a running local Relay and a key for its local organization.

Capability	Current implementation
Agents, Sessions, Turns, Items	Implemented
Live event streaming and input queuing	Implemented; historical events are not replayed; active-Turn input queues
Managed environments, inline files, Artifacts	Implemented
Functions, HTTP and stdio MCP, Vaults	Implemented with documented limits
Platform connections	Add existing Personal or Organization accounts to API Agents; platform-managed authentication
Tool search	Deferred client functions with explicit `tool_search`; automatic MCP discovery with a short-lived catalog cache
Dynamic Workflow	Available through the API; CLI 0.2.3+ supports the declaration. Model-generated JavaScript composes Session tools and application functions, with durable function handoffs.
Web search	Implemented; `cached` mode runs as live, no location targeting
Inline ZIP skills, plus Rebyte's GitHub-sourced skills	Implemented in managed environments; capability directories are auto-scanned for `SKILL.md` once the Sandbox is available
Webhooks	Signed Session, Turn, Workflow Run and Schedule Run notifications with retries and function handoffs
Plugins	Not yet supported
Execution tracing	Implemented through Langfuse; view Agent, Session and Turn traces in Platform
Multi-agent	Not yet supported
Automatic context compaction	Not yet supported

The navigation follows OpenAI's guide with additional pages for Rebyte-specific features. A hollow dot marks an unsupported capability. Compatibility is defined by the implemented fields and behavior, not by the presence of a page in this guide.

See OpenAI compatibility for a dated comparison of implemented features, missing endpoints and behavior differences.

Official OpenAI SDK

Use the official openai package with Rebyte's endpoint and organization API key. Agents API methods, types, pagination and SSE handling come from that dependency.

Terminal

pnpm add openai@7.15.0

typescript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.REBYTE_API_KEY,
  baseURL: 'https://api.rebyte.ai/v1',
  maxRetries: 0,
});
const session = await client.beta.agents.sessions.create({
  agent: { model: 'gpt-5.6-luna', instructions: 'Help the user.' },
  environment: { type: 'openai_hosted' },
  input: 'Hello!',
});

The openai_hosted protocol value selects Rebyte-managed compute at this endpoint. Omit environment for chat, service MCP and client functions without a Sandbox. The official SDK adds OpenAI-Beta: agents=v1; raw HTTP clients must provide it. The verified TypeScript dependency is openai@7.15.0. Python applications can use openai==3.13.0 with the same endpoint. See Quickstart.

Workflow Agents and Schedules are Rebyte extensions. Use their HTTP APIs or the small @rebyteai/agent-extensions@0.3.0 npm package with an existing official client. They are not methods on the official OpenAI class. Current availability describes server support.

SDK and example application

Repository	What it provides	How to use it
rebyte-agent-sdk	Rebyte Agent SDK: API extensions, React/UI, server adapter, CLI and examples.	Install packages from npm. Clone only to run the complete examples or contribute source changes.
commerce-agent-starter	A complete commerce demo with catalog, cart, Skills and client functions.	Clone it to run or customize the example storefront.

Rebyte Agent SDK

Rebyte Agent SDK is Rebyte's SDK, maintained in the rebyte-agent-sdk repository. It includes the official openai API client, Rebyte extensions and runnable examples, plus @rebyteai/agent-react for React session state, @rebyteai/agent-ui for a ready-made chat interface, @rebyteai/agent-server for the server adapter, and a configuration CLI.

Start with the Node application or Cloudflare application. The Agents API recipes cover Agent creation, independent Sessions, streaming, files and client functions. Install only the packages your application needs:

npm package	Purpose
`openai`	Official API client for Agents, Sessions, streaming and Artifacts.
`@rebyteai/agent-extensions`	Optional Rebyte Workflow and Schedule resources.
`@rebyteai/agent-react`	React hooks and session state.
`@rebyteai/agent-ui`	Ready-made React chat interface and styles.
`@rebyteai/agent-server`	Server adapter that keeps your Rebyte API key out of the browser.
`@rebyteai/cli`	Create, update, validate and export Agent configuration from the terminal.

Terminal

pnpm add openai@7.15.0

The current npm release, 0.3.0, uses the official client. The 0.4.0 source adds function-wait support while its npm publication is pending. Follow the SDK guide to install the packages or run a template. Existing 0.2.x packages still use the old fork. Follow the 0.3.0 migration guide to upgrade. Standard API integrations need only openai.

Commerce Agent

Commerce Agent is a complete example storefront. Its Python host implements catalog, cart and presentation functions with on-demand discovery, with a separate API Session for each conversation and per-Session Skills. Follow the Rebyte integration guide for setup and the execution flow.

The SDK’s TypeScript examples use the official client. Commerce uses the official Python client. Both connect to the same Rebyte Agents API.

API Agents appear in Platform. They are independent of product UI Agent Profiles and Workspaces. A Session never inherits another Session's Sandbox or Artifacts because it uses the same saved Agent.

To list your organization's saved API Agents, use GET /v1/agents or client.beta.agents.list(). See Agent listing and pagination for authentication, a cURL request, and an SDK example that retrieves every page.

Fixed Workflow Agents

Workflow Agents execute saved JavaScript directly. Create a draft in the console or API, test it, then explicitly publish a fixed version for API callers.

Scheduled Agents run an Agent on a recurring or one-time schedule. Choose a continuous Session for context across runs, independent Sessions for isolated tasks, or a pinned published Workflow version.

Protocol referenceOpenAI Agents API ↗