Configuring Agents

Define an Agent inline in a Session request, or save one and reuse its ID. The model field takes a supported Rebyte model ID.

Save an Agent

Using the client from the quickstart:

const agent = await client.beta.agents.create({
  name: 'Research assistant',
  model: 'gpt-5.6-luna',
  instructions: 'Explain your findings clearly. Save deliverables to /workspace/outputs.',
  metadata: { project: 'research' },
});

const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  environment: { type: 'openai_hosted' },
});

Agent settings

Generation settings depend on the selected model's adapter. Unsupported combinations return an error; service_tier: 'fast' and enabled Multi-agent execution are currently rejected.

Session overrides

Pass agent alongside agent_id to override selected fields for a new Session:

const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  agent: { instructions: 'Review only the supplied document.', tools: [] },
  environment: { type: 'openai_hosted' },
});

An explicitly supplied object or array replaces that entire field. In this example, tools: [] removes the saved tool list for this Session. Later changes to the saved Agent do not alter existing Sessions.

Environment settings

Compute configuration belongs to the Session's environment: packages, files, network policy, setup commands, and inline skills. See managed sandboxes.

MCP credentials also belong to Session configuration or Vaults, not a reusable Agent definition. See MCP connections and Vaults.

Manage saved Agents

Send Authorization: Bearer <REBYTE_API_KEY> and OpenAI-Beta: agents=v1. Reads require the tasks:read key permission; writes require tasks:write. The Rebyte Agent SDK supplies the beta header automatically. Keep the key on your application server.

List Agents

List the saved API Agents belonging to your organization:

curl --fail-with-body --silent --show-error \
  'https://api.rebyte.ai/v1/agents?limit=20&order=desc' \
  -H "Authorization: Bearer $REBYTE_API_KEY" \
  -H 'OpenAI-Beta: agents=v1'

This lists API Agents shown in Platform. It excludes product UI Agent Profiles, deleted Agents, and inline Agent definitions supplied only when creating a Session. It never lists another organization's Agents.

The response contains object: "list", a data array of Agent resources, has_more, first_id, and last_id. An empty page has data: [], has_more: false, and null IDs. Each Agent includes its id, name, model, instructions, tools, generation settings, metadata, created_at, and updated_at.

When has_more is true, request the next page with after=<last_id>, keeping the same order. One request returns one page, not necessarily all Agents. An invalid cursor returns 400 invalid_cursor. Name and metadata filters are not currently supported.

With the client from the quickstart, this example prints all saved API Agents, following every page:

for await (const agent of client.beta.agents.list({
  limit: 100,
  order: 'desc',
})) {
  console.log(agent.id, agent.name, agent.model);
}

The SDK iterator fetches subsequent pages automatically. For manual SDK paging, use page.hasNextPage() and page.getNextPage(); last_id above describes the raw HTTP response, not a property exposed on the SDK's Agent page object.

Retrieve, update, and delete

const agent = await client.beta.agents.retrieve(agentId);
await client.beta.agents.update(agent.id, { name: 'Research assistant v2' });
await client.beta.agents.delete(agent.id);

Use an ID returned by creation or listing, such as agent_.... Retrieval returns the Agent resource directly. A missing, deleted, or other organization's Agent returns 404. Updates affect future Sessions; existing Sessions keep their resolved configuration. Deleting a saved Agent leaves its existing Sessions intact; use Session deletion to remove a Session and its managed resources.

Keep configuration in source control

The Toolkit CLI creates, applies and exports native Agent configuration from agent.toml. Use model, instructions or instructions_file, and explicit tools. Environment and Skills are intentionally absent from the saved-Agent manifest. The CLI uses the Rebyte Agent SDK; it does not create product UI Agent Profiles.