agent.toml

agent.toml is the file representation of a reusable Rebyte Agent. It keeps the Agent's instructions, model, capabilities, and Skills in one portable declaration that can be validated before it reaches the API.

The CLI resolves the file and calls the Agent API. The TOML document itself is never stored or sent as an API payload.

An Agent created this way is an organization-scoped API resource. It is not a Workspace Agent, does not appear in the product UI, and has no user owner inferred from the person who created the organization API key. Run it through the OpenAI-compatible Responses API, or use the lower-level Session and Message API when you need asynchronous control or human-in-the-loop answers.

Only name is required. Unknown fields are rejected.

Complete schema

name = "research-agent"
description = "Web research with citations"
llm = "deepseek-v4-pro"
max_steps = 32

# Put the instructions inline...
prompt = """
You are a meticulous research agent.
"""

# ...or load them from a UTF-8 file next to agent.toml.
# Do not set both prompt and prompt_file.
# prompt_file = "prompt.md"

capabilities = [
  "web_search_&_browse",
  "sandbox",
  "skills",
  "composio:github",
  "custom:550e8400-e29b-41d4-a716-446655440000"
]

[[skills]]
repo = "rebyteai/skills"
path = "research/deep-research"

Fields

Field	Required	Default	Description
name	Yes	—	Agent name, 1–100 characters.
description	No	Empty	Description, up to 500 characters.
llm	No	deepseek-v4-pro	Manager model used by the Rebyte agent loop.
max_steps	No	32	Maximum manager steps per run, from 1 through 128.
prompt	No	Empty	Inline Agent instructions, up to 100,000 characters.
prompt_file	No	—	UTF-8 instructions file resolved relative to agent.toml. Mutually exclusive with prompt.
capabilities	No	Rebyte defaults	Ordered capability references, up to 64. Duplicates are rejected.
skills	No	Empty	GitHub Skill directories, up to 128. Duplicates are rejected.

Supported llm values:

deepseek-v4-pro
glm-5.2
kimi-k3
claude-sonnet-5
claude-opus-5
gpt-5.6
gpt-5.4-mini

Some models require purchased credits or an active subscription.

Capabilities

capabilities is one ordered string array for Rebyte capabilities, Composio toolkits, and organization-owned custom MCP servers.

Rebyte capabilities

web_search_&_browse
sandbox
skills
coding_agent
ask_user_question
report_builder
company
app_builder_contract
github
sound_studio
speech_generator
http_client

When capabilities is omitted, Rebyte uses:

capabilities = [
  "web_search_&_browse",
  "sandbox",
  "skills",
  "coding_agent",
  "ask_user_question",
  "report_builder",
  "company"
]

Composio toolkits

Prefix a toolkit key with composio::

capabilities = ["composio:github", "composio:slack"]

The toolkit must be available to the organization. Credentials stay in Rebyte and are never written into agent.toml.

Custom MCP servers

Prefix an existing custom MCP server UUID with custom::

capabilities = ["custom:550e8400-e29b-41d4-a716-446655440000"]

Custom MCP servers are organization-owned. A manifest containing one of these references only works in an organization where that server exists.

Skills

Each Skill identifies a GitHub repository and the directory containing its SKILL.md:

[[skills]]
repo = "owner/repository"
path = "skills/research"

repo must use the canonical owner/repository form without a .git suffix. path must name a repository-relative directory. Absolute paths, .., query strings, fragments, whitespace, and paths ending in SKILL.md are rejected.

CLI lifecycle

Validate locally

rebyte agent validate -f agent.toml

Validation parses TOML, checks every field, resolves prompt_file, and makes no network request.

Create an Agent

export REBYTE_API_KEY="rbk_..."
rebyte agent create -f agent.toml

This calls POST /v1/agents and prints the new Agent ID.

Apply the complete manifest

rebyte agent apply <agent-id> -f agent.toml

apply replaces every field represented by the v1 manifest. Omitting an optional field applies its documented empty or default value: for example, omitting skills clears the current Skill list.

Export current API state

rebyte agent export <agent-id> -o agent.toml

The API resource is the source of truth after creation. export reads the current Agent and writes a canonical manifest with an inline prompt. Original comments, formatting, and prompt_file paths are not retained.

The command refuses to overwrite an existing file unless --force is present. Omit -o to write to stdout.

Environments

Network commands read REBYTE_API_KEY. Select an environment explicitly:

rebyte agent create -f agent.toml --env dev
rebyte agent create -f agent.toml --env test
rebyte agent create -f agent.toml --env prod

Environment	Base URL
dev	REBYTE_DEV_BASE_URL, or http://localhost:3332
test	Required REBYTE_TEST_BASE_URL
prod	https://api.rebyte.ai

REBYTE_ENV selects the default environment. REBYTE_BASE_URL points at an exact Relay URL when no explicit environment is selected. --base-url has the highest priority and can target a local mock, tunnel, or another Relay.

Execute the Agent

Creating an Agent only stores reusable configuration. For most integrations, use its Agent ID as model with the official OpenAI SDK:

import OpenAI from "openai";

const rebyte = new OpenAI({
  apiKey: process.env.REBYTE_API_KEY,
  baseURL: "https://api.rebyte.ai/v1",
});

const response = await rebyte.responses.create({
  model: "the-agent-id-printed-by-rebyte-agent-create",
  input: "Research Acme and summarize what you find.",
});

console.log(response.output_text);

The first call returns a durable response.conversation.id. Pass that stable Conversation ID on every later turn:

const followup = await rebyte.responses.create({
  model: "the-agent-id-printed-by-rebyte-agent-create",
  conversation: response.conversation.id,
  input: "Now compare it with its closest competitor.",
});

See the Responses API guide or the Rebyte TypeScript SDK guide.

The lower-level execution lifecycle remains available:

POST /v1/agents
POST /v1/sessions
POST /v1/sessions/{sessionId}/messages
GET  /v1/sessions/{sessionId}/messages/{messageId}

Message submission returns 202 Accepted; that is not proof that the Agent finished. Poll the authoritative Message until it reaches a terminal status, then read its final response. See the complete Agent, Session, and Message quickstart.

Not represented in v1

The following runtime and AgentSky-style fields are not part of the current Rebyte Agent schema and are rejected if present:

type
instructions
customInstalls
customData
vcpus
memory_mb
secretRefs
reasoningEffort

Agent Computer size, secrets, credentials, and Session runtime settings remain separate from the static Agent definition.