Configuring Agents

Define an Agent inline in a Session request, or save one and reuse its ID. The required model field takes an exact supported Rebyte model ID. Retired non-GPT IDs are rejected rather than redirected to a different model.

Save an Agent

Using the client from the quickstart:

const agent = await client.beta.agents.create({
  name: 'Research assistant',
  model: 'gpt-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.

Session budget

By default a Session has no spending limit beyond your organization's credit balance. Set budget to cap what one Session may spend:

const agent = await client.beta.agents.create({
  name: 'Research assistant',
  model: 'gpt-6-luna',
  budget: { max_credits: 500 },
});

max_credits is a positive integer; one credit is $0.01. The budget applies to each Session separately, not to the Agent as a whole. A Session inherits the saved Agent's budget when it is created. Pass agent: { budget: { max_credits: 50 } } to use a different budget for one Session, or agent: { budget: null } to remove it. An existing Session's budget cannot be changed.

The Session counts every model call it makes, including automatic and manual compaction, at the credits charged for that call: its cost rounded up to a whole credit. The total is returned as credits_used on the Session. Before each model call, Rebyte compares credits_used with the budget:

• While credits_used is below max_credits, the call runs. A single call can therefore finish slightly above the budget.
• Once credits_used reaches max_credits, the current Turn ends with status failed and error code session_budget_exceeded. No further model call is made.
• New messages to that Session are rejected with 409 and the same code. Create a new Session to continue.

The budget counts model calls only, not other charges such as tool use. A model call that fails before returning usage is not counted. Your organization's credit balance still applies: a Session also stops with usage_limit_exceeded when the organization runs out of credits.

Tool call titles

A tool call Item tells your application what the model called and with which arguments. It does not say why. With tool_calls: { title: 'auto' }, Rebyte asks the model to title each call in the user's language, in about ten words, for example Checking the delivery status of order 42. Your application can show the title instead of the raw call, the way a chat product shows "Searching the web for …" while the agent works.

const agent = await client.beta.agents.create({
  model: 'gpt-6-luna',
  tools,
  tool_calls: { title: 'auto' },
});

How it works:

• Rebyte adds an optional title argument to every tool definition the model sees, including functions, built-in environment tools, MCP tools and Web Search, and tells the model what it is for. Your tool definitions are not modified; a function whose parameters already declare title keeps that parameter as its own, and its calls get no Rebyte title.
• When the model fills the argument, Rebyte removes it before the call is recorded or executed. Function arguments, MCP tool arguments and sandbox commands never contain it.
• The title is published as title on the call Item (function_call, mcp_call, command_execution and web_search_call) and on each entry of the Session's required_actions. It is a string, or null when the model wrote none. See Events for when it arrives on the stream.

The title is a suggestion to the model, not a requirement: a call without one is normal, and your application should fall back to the tool name. Titles cost a few output tokens per call. Without the option, tool definitions, arguments and Items are exactly as before, and every call Item reports title: null. A Session inherits the saved Agent's setting; pass agent: { tool_calls: { title: null } } to turn it off for one Session. Rebyte Loop models do not accept the option.

Update settings for an existing Session

Update the Session's agent.model, agent.reasoning.effort, or agent.service_tier while keeping its conversation history and environment:

const session = await client.post(`/agents/sessions/${sessionId}`, {
  headers: { 'OpenAI-Beta': 'agents=v1' },
  body: {
    agent: {
      model: 'gpt-6-luna',
      reasoning: { effort: 'high' },
    },
  },
});

This uses the official OpenAI client's low-level request method because the openai@7.15.0 types for sessions.update only expose metadata. No SDK fork is required. The HTTP endpoint is POST /v1/agents/sessions/{session_id} and requires tasks:write.

Omitted settings stay unchanged; nested reasoning fields merge. Set reasoning.effort: null to reset to the selected model's default (none for gpt-6-luna), or service_tier: null to reset to auto.

Changes apply to new Turns admitted after the update. Running Turns, Turns waiting for a client function result, and already queued Turns keep their previous settings through completion. Retrieving the Session immediately shows the settings for future Turns. Its saved Agent definition is not modified.

Model-specific validation still applies. Switching models preserves omitted settings, so include a compatible effort or reset it to null when needed. Invalid combinations return 400 without applying any of the update. This endpoint does not modify instructions, tools, tool call titles, reasoning summaries, text format, Multi-agent configuration, or the environment. metadata can be updated in the same request; supplying it replaces all metadata and null clears it.

Dynamic Workflow

Add { type: 'dynamic_workflow' } to let the model generate JavaScript that combines its Session's server tools and application functions. Each active code segment has a 60-second execution limit; each application function pause can wait up to 24 hours. The feature is opt-in; it does not add external tools or a Sandbox by itself. See Dynamic Workflow for current availability, examples, tool scope and authentication.

Decision tool

Add { type: 'decision' } to expose rebyte_decide, powered by TypeSafe Jev via Rebyte's model proxy. Include dynamic_workflow as well to branch on its returned probabilities inside JavaScript. Decision calls are currently free; normal Agent language-model calls retain their existing billing. See Decision tool for question types, limits and examples.

Environment settings

Compute configuration belongs to the Environment: packages, files, network policy, setup commands, and inline skills. Inline Session creation supplies it through environment. In the shared Environment API, referencing Sessions reuse that fixed configuration without overriding it. See managed sandboxes.

Inline MCP credentials belong to Session configuration or Vaults, not a reusable Agent definition. Alternatively, add an existing Platform connection to the Agent: its tools store a connection reference while the platform manages the credentials. See MCP connections for direct server configuration.

Manage saved Agents

POST /v1/agents accepts an Idempotency-Key header with the same contract as Session creation: a retry with the same key and request returns the first Agent with 200.

Send Authorization: Bearer <REBYTE_API_KEY> and OpenAI-Beta: agents=v1. Reads require the tasks:read key permission; writes require tasks:write. The official openai client 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 filters are not 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 Rebyte 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 official openai client; it does not create product UI Agent Profiles.

Deferred functions in agent.toml

Use Rebyte CLI 0.2.1 or later. This is the saved Agent configuration; your application implements the handler and creates Sessions separately.

name = "Order assistant"
model = "gpt-6-luna"
instructions = "Find the relevant tool before looking up an order."

[[tools]]
type = "tool_search"

[[tools]]
type = "function"
name = "lookup_order"
description = "Look up an order by ID."
defer_loading = true

[tools.parameters]
type = "object"
required = ["order_id"]
additionalProperties = false

[tools.parameters.properties.order_id]
type = "string"

Validate with rebyte agent validate --file agent.toml. The CLI rejects defer_loading = true without tool_search. See Functions for discovery, client execution and returning results. MCP discovery is automatic; see MCP connections.