Developer documentation/Agents API
Build applications with a managed agent runtime, durable sessions, and tools.
Start building #
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:
Rebyte Agent SDK React hooks, chat UI, server adapter, CLI and Rebyte extensions. Uses the official OpenAI client. Demo
commerce-agent-starter A 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
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.
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.
pnpm add openai@7.15.0
python
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-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. |
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.