Quickstart

This example asks an agent to create a greeting file in a managed environment. It uses the production Rebyte API and a Rebyte organization key.

1. Set up the client

Use Node.js 22 or later and install the official OpenAI client. This guide uses the verified version 7.15.0:

pnpm add openai@7.15.0
export REBYTE_API_KEY="rbk_..."

No Rebyte client fork is required. Configure the Rebyte API key and endpoint explicitly; the official package defaults to OpenAI.

For local development, set REBYTE_BASE_URL=http://127.0.0.1:34567/v1 and start your local Relay. Use a key belonging to that local organization. The key needs tasks:read, tasks:write, and files:read for this example. Keep it on your application server.

2. Run a task

Save this as quickstart.mjs. An inline Agent definition lets you start without creating a saved Agent first.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.REBYTE_API_KEY,
  baseURL: process.env.REBYTE_BASE_URL ?? 'https://api.rebyte.ai/v1',
  maxRetries: 0,
});

const stream = await client.beta.agents.sessions.create({
  agent: {
    model: 'gpt-5.6-luna',
    instructions: 'Write deliverables to /workspace/outputs.',
  },
  environment: { type: 'openai_hosted' },
  input: 'Create /workspace/outputs/greeting.txt containing Hello from Rebyte.',
  stream: true,
});

let sessionId;
for await (const event of stream) {
  if (event.type === 'agent.session.created') {
    sessionId = event.session.id;
    console.log('Session:', sessionId);
  }
  if (event.type === 'agent.session.turn.output_text.delta') {
    process.stdout.write(event.delta);
  }
  if (event.type === 'agent.session.turn.failed' ||
      event.type === 'agent.session.failed') {
    throw new Error(JSON.stringify(event));
  }
}
if (!sessionId) throw new Error('No Session ID received');
console.log('\nSave this Session ID:', sessionId);

const turns = await client.beta.agents.sessions.turns.list(sessionId);
if (turns.data.length === 0 || turns.data[0].status !== 'completed') {
  throw new Error('The turn did not complete successfully');
}
const artifacts = await client.beta.agents.sessions.artifacts.list(sessionId);
for (const artifact of artifacts.data) {
  console.log('Artifact:', artifact.id, artifact.path);
  const response = await client.beta.agents.sessions.artifacts.content(
    artifact.id, { session_id: sessionId },
  );
  console.log(await response.text());
}

node quickstart.mjs

3. Continue the session

Reuse your client and saved sessionId to send another task:

await client.beta.agents.sessions.events.create(sessionId, {
  'Idempotency-Key': 'greeting-followup-1',
  events: [{
    type: 'agent.session.input.message',
    input: [{
      role: 'user',
      content: [{ type: 'input_text', text: 'Read the greeting file and explain it.' }],
    }],
  }],
});

The request acknowledges accepted input; it does not wait for completion. Subscribe to events before sending input to observe live progress, or retrieve the Session and Turns afterward. The same environment and files remain attached.

4. Retrieve conversation history

Keep the Session ID to reopen the conversation later. Rebyte persists messages and tool output; your server can load them through the same official client:

for await (const item of client.beta.agents.sessions.items.list(sessionId, {
  order: 'asc', limit: 100,
})) {
  console.log(item);
}

The loop retrieves all pages. See Retrieve conversation history for a standalone script, the HTTP endpoint, permissions, and page reload behavior. No separate Conversations API integration is needed.

5. Clean up

When you have finished, delete the Session with your saved ID:

await client.beta.agents.sessions.delete(sessionId);

Deletion also removes its managed environment and stored Artifacts. Download any deliverables you want to keep first.

Next steps

Configure a reusable Agent, add function tools, or connect an MCP server.

Session creation is not currently idempotent. After an ambiguous timeout, inspect existing Sessions before creating another. Input submission has a separate idempotency contract.

Build an application

Rebyte Agent SDK is our application SDK: React hooks, a chat UI, a server adapter and a configuration CLI. Its Node application shows streaming, uploads, cancellation and reload with those packages.

For a complete application, start with Commerce Agent and its Rebyte setup guide. It connects a storefront to a Python host with catalog, cart and presentation functions.

Use the Agents API recipes for checks that create and delete their own Agents and Sessions, including no-environment chat, client functions and hosted file delivery. Keep the organization key on your server and authorize each user's Session there.