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.

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-5.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-5.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, 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.

Environment settings

Compute configuration belongs to the Session's environment: packages, files, network policy, setup commands, and inline skills. 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

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 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 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-5.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.