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. Install the versioned SDK release directly in your application; you do not need to clone a repository:

pnpm add @rebyteai/agent-sdk@0.2.0
export REBYTE_API_KEY="rbk_..."

Release v0.2.0 includes versioned packages and SHA-256 checksums. Install packages from npm; matching archives are also available in GitHub Releases.

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 Rebyte, { rebyteSandbox } from '@rebyteai/agent-sdk';

// Reads REBYTE_API_KEY and connects to Rebyte. No base URL is required.
const client = new Rebyte({ maxRetries: 0 });

const stream = await client.beta.agents.sessions.create({
  agent: {
    model: 'gpt-5.6-luna',
    instructions: 'Write deliverables to /workspace/outputs.',
  },
  environment: rebyteSandbox(),
  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. 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 AppKit 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 Rebyte SDK 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.