Introduction

A coral-agent.toml contains all the information that the Coral server needs to orchestrate a Coral agent. You cannot have a Coral agent without a coral-agent.toml file; similar to a package.json file for a Node project. TOML is the syntax used in this configuration file.

Example

edition = 2

[agent]
name = "my-agent"
version = "0.0.1"
description = "Has access to company databases"

[runtimes.docker]
image = "myusername/myagent"

[options.OPENAI_API_KEY]
type = "string"
required = true
secret = true

File format reference

edition

The current latest edition is 2

If edition is not set, it will default to 1 for backwards compatibility. This will issue a warning

edition = 2

The edition field is a number describing the format of the coral-agent.toml file.

Second edition

The second edition, or (edition = 2) is the current edition of Coral agent definitions. Changelog compared to first edition agent definitions:

Top level changes:
- Added the edition field
Option changes:
- Added Numeric types
  - The number type remains for backwards compatibility. It is now mapped to the f64 type.
- Added the blob type
- Added the bool type
- Added list types
- Added the validation table
- Added the display table
  - Moved description to display.description for options
- Added the base64 and secret for string types
  - The secret type remains for backwards compatibility and will set type = "string" and hidden = true
- Added filesystem option value transport via the transport field

First edition

First edition, or (edition = 1) agents can still be used by the Coral server but will generate warnings. Versions of the Coral server that support only first edition agents cannot load second edition agents. Any agent that is still using first edition agent definitions should be updated as soon as possible. In the future, first edition agents will not be valid in a Coral server registry.

Migration steps

Set edition = 2 at the top of the agent definition
Change all types of secret to string and add the hidden = true field
Change all types of number to f64. Or, use a new more fitting numeric type
Rename description on options to display.description

Optionally:

Consider adding the validation table
Consider adding the full display table
Choose a new type for your options that better fits it’s use case
Use the file system transport for options that take can take a large input value (e.g images or other large files)

agent

[agent]
name = "..."
version = "0.0.0"
description = "..."
capabilities = ["resources"]

Agent table, containing name, version, description and capabilities fields.

name

[agent]
name = "my name..."

There are no restrictions imposed on the name of your agent in the file format reference. But note that, submitting your agent to the marketplace requires that the name is unique and that it contains only:

lowercase characters: a-z
uppercase characters: A-Z
numbers: 0-9
special characters: _ and -

version

[agent]
version = "0.0.0"

The version must be in format [0-9]+\.[0-9]+\.[0-9]+. See also version recommendations for the marketplace.

description

[agent]
description = "Access to GitHub MCP tooling"

Agents in a Coral server have descriptions that are given to other agents in the graph to identify them. This field specifies the default description for this agent in the graph. It is possible that the consumer of this agent changes the description specified here. A description is “external”, other agents in the graph use an agent’s description to identify its purpose, but the agent itself doesn’t use its description to describe itself. Do not put prompting for your agent in the description.

capabilities

The capabilities field is not yet fully implemented

[agent]
capabilities = ["resources", "tool_refreshing"]

Some features of Coral require implementation from the agent. The capabilities field is used to describe what optional features of Coral the agent supports. Supported capabilities:

resources
- The agent supports MCP resources fully. Fully supporting MCP resources requires that any given MCP resource is fetched per agent iteration
tool_refreshing
- The agent will check for new tools per iteration

runtimes

[runtimes.docker]
image = "myuser/myimage"

[runtimes.executable]
command = ["my-agent.exe", "--some-argument"]

Runtimes specify how the Coral server should orchestrate the agent. Currently there are only two supported runtimes, executable and docker.

docker

[runtimes.docker]
image = "myuser/myimage"

docker is the preferred runtime for an agent. The docker runtime is required for agents on the marketplace and ensures that the agent is portable.

Do not set a tag when using the docker runtime. The agent’s version will be appended to the end of the image.It is important that running an older version of your agent runs a matching older version of your agent’s Docker image.

The following example will request myuser/myimage:1.0.0 from Dockerhub:

[agent]
name = "my-agent"
version = "1.0.0"

[runtimes.docker]
image = "myuser/myimage"

Make sure you tag your images with the correct version before pushing them to Dockerhub!

executable

The executable runtime should only be used for agent testing or development.Agents with only a executable runtime defined will not be accepted into the marketplace.

[runtimes.executable]
command = ["./launch", "my-agent"]

The specified command will be run on the server in the same directory as the coral-agent.toml file, taking the following directory for example:

agents/
├─ my-agent/
│  ├─ coral-agent.toml
│  ├─ src/
│  │  ├─ main.py

Your executable runtime could be:

[runtimes.executable]
command = ["python", "src/main.py"]

options

[options.MY_OPTION_1]
type = "string"
required = false
secret = true
default = "..."
base64 = false
transport = "env"

[options.MY_OPTION_1.display]
label = "My first option"
description = "Set this option to make my agent do something cool"
group = "My options"
multiline = false

[options.MY_OPTION_1.validation]
variants = ["value1", "value2"]
min_len = 1
max_len = 100
regex = "$value[0-9]^"

[options.MY_OPTION_2]
type = "i32"
# etc...

[options.MY_OPTION_2.display]
label = "My second option"
# etc...

[options.MY_OPTION_1.validation]
variants = [10, 20]
min = 1
max = 100

Agent options define variables that the server will set for the agent when it is orchestrated. Options allow for more generic development of agents and fine-tuning by agent consumers. Options are commonly used to:

Provide API keys for services the agent needs access to
Configure LLM parameters, for example:
- The model provider (OpenAI, Anthropic, etc)
- The model used (GPT-4, Claude 3.5, etc)
- Maximum tokens
- Hyperparameters

See here for more information on how options are sent to the agent.

type

An option type controls valid values for an option and how the option will be encoded. The type will be verified by the server. The server will never orchestrate an agent with a value for an option that is of the wrong type.

Numeric types

type	value	`transport = "env"`	`transport = "fs"`
i8	127	`127`	`0x7F`
i16	-15234	`-15234`	`0xC47E`
i32	1589473628	`1589473628`	`0x5EB8E15C`
i64	7234567890123456789	`7234567890123456789`	`0x6451780B5FE68D15`
u8	203	`203`	`0xCB`
u16	5432	`54321`	`0xD431`
u32	3141592653	`3141592653`	`0xBB40E64D`
u64	12345678901234567890	`"12345678901234567890"`	`0xAB54A98CEB1F0AD2`
f32	3.14159274	`3.14159274`	`0x40490FDB`
f64	2.718281828459045	`2.718281828459045`	`0x4005BF0A8B145769`

For JSON compatibility type = "u64" must be specified as a string, both as a default to an option in coral-agent.toml and as a value give to the Coral server.

When transport = "fs" all numeric types are written in big-endian byte order.

Other types

type	value	`transport = "env"`	`transport = "fs"`
bool	true	`1`	`0x01`
string	Hello World!	`Hello World!`	`Hello World!` (utf8)
blob	[164, 145, 163, 164]	`dGVzdA==` (base64)	`0x74657374` (raw bytes)

When transport = "fs":

Bool values be written as u8 byte; 1 for true and 0 for false.
A string’s base64 setting will be ignored. The string will always be written in a UTF-8 encoding

When transport = "env":

Bool values will be 1 for true and 0 for false.
String values can be passed with base64 encoding if base64 = true is set
Blob values will always be passed as base64

List types

All types except for the bool type have a matching list type, for example:

list[i32]
list[string]
list[blob]

List types will always default to an empty list. If no value is given for an option, the server will provide an empty list as a value for that option.Warnings will be generated for list types when required = true.

When transport = "fs":An environment variable will be set for this option containing a list of files, one file for every value specified.The list of paths will be separated using the operating-system-dependant path separator:

; on Windows
: on Unix-like operating systems

For example:

[options.MY_OPTION]
type = "list[string]"
transport = "env"
default = ["one", "two"]

Windows environment:

$env:MY_OPTION = "C:\path\to\file1.opt;C:\path\to\file2.opt"

Unix environment:

MY_OPTION = "/path/to/file1.opt:/path/to/file2.opt"

File content (identical on Windows and Unix):

$ cat /path/to/file1.opt
one

$ cat /path/to/file2.opt
two

When transport = "env":The values will be sent as a comma-separated list. If you expect a large value (that your OS might not fit into an environment variable) consider using the transport = "fs" transport instead.If you’re using a type = list[string] and expect commas to exist in the strings, it is recommended to use base64 = true or transport = "fs".

Edition 1 types

Edition 1 types are deprecated

Type	Description	Notes
`number`	Previously used for numbers	converted to a `f64` type
`secret`	Previously used hidden strings	converted to a `string` type with `hidden = true`

transport

The default value of transport is env

Transport is either env or fs. The env transport should be used in 90% of cases. The fs transport exists mostly to support potentially large (strings, string lists, blob or blob list) options. Encoding varies by type. See the type section for examples of how different types are encoded with different transports.

required

The default value of required is false

[options.MY_OPTION]
type = "string"
required = true

Options with required = true must be specified to the server. The server will not orchestrate an agent with an unspecified required value. This should be used for options that the agent cannot run without.

Setting a default value for an option and setting required = true will produce a warning. required = true should only be set when you need the user to specify a value for an option.

secret

Only valid on type = "string" or type = "list[string]"

The default value of secret is false

[options.MY_OPTION]
type = "string"
secret = true

Strings with secret = true will be censored in logs and input fields in the UI. This should be used for options with sensitive input, like API keys.

base64

Only valid on type = "string" or type = "list[string]" and when transport = "env"

The default value of base64 is false

[options.MY_OPTION]
type = "string"
base64 = true

Encodes strings (type = "string" or type = "list[string]") in base64. No effect on options with transport = "fs". It is recommended to set base64 = true on list of strings that may contain commas.

default

[options.MY_OPTION]
type = "string"
default = "test"

The default value for this option.

The value of the default must match the given type!For example:

[options.STRING_OPTION]
type = "string"
default = "test"

[options.INT_OPTION]
type = "i32"
default = 123

[options.BOOLEAN_OPTION]
type = "bool"
default = true

[options.INT_LIST_OPTION]
type = "list[i32]"
default = [123, 123, 123]

[options.STRING_LIST_OPTION]
type = "list[string]"
default = ["test", "test", "test"]

u64 types must be represented as a string! See (numeric types)(/configuration/agent#numeric-types).

display

The optional display table contains fields that are used to customize how this option is displayed in user interfaces, such as Coral studio.

label

The default value of display.label is the key given for the option in the options table

[options.MY_OPTION]
type = "string"
display.label = "My option"

A optional friendly display name for the option

description

[options.MY_OPTION]
type = "string"
display.description = "My option is used to my make my agent ..."

A human-readable description for this option.

In first edition agents, the description field was placed top level in the option:

[options.MY_OPTION]
type = "string"
description = "My option is used to my make my agent ..."

This syntax is not valid in second edition agents.

group

[options.MY_OPTION]
type = "string"
display.group = "My options"

[options.MY_OPTION2]
type = "string"
display.group = "My options"

[options.MY_OPTION3]
type = "string"
display.group = "Other options"

The group that this option should be in, displayed as an Accordion in Coral studio. All options with the same group name will be combined.

multiline

The default value of display.multiline is false

display.multiline = true has no effect on type = "bool" options

If display.multiline = true then the user input dialog for this field will span multiple lines. Useful for options that contain LLM prompts or partial prompts.

validation

The optional validation table contains fields that are used to validate the potential value given for this option by an agent consumer. The server will reject requests for agents that contain invalid values for options.

The validation table cannot be specified on type = "bool" options

If you do not want to perform a validation on the option’s value you must leave it unspecified!TOML does not support null values.

variants

[options.STRING_OPTION]
type = "string"
validation.variants = ["my value 1", "my value 2", "my value 3"]

[options.INT_OPTION]
type = "i32"
validation.variants = [1, 2, 3]

[options.INT_LIST_OPTION]
type = "list[i32]"
validation.variants = [
    [123, 123, 123],
    [321, 321, 321]
]

[options.STRING_LIST_OPTION]
type = "list[string]"
validation.variants = [
    ["my value 1", "my value 2", "my value 3"],
    ["my value 4", "my value 5", "my value 6"]
]

If specified, only values contained in this array are valid values for this option.

The value of validation.variants cannot be an empty array

The value of the validation.variants must match the given type!

min

Only valid on numeric types

[options.MIN_TOKENS]
type = "i32"
validation.min = 3000

The minimum accepted value for this option. Note that the value given to min must be the same numeric type of the option, this means you cannot specify a negative min value for an unsigned numeric type.

max

Only valid on numeric types

[options.AGENT_ITERATION_COUNT]
type = "i32"
validation.max = 200

The maximum accepted value for this option. Note that the value given to max must be the same numeric type of the option, this means you cannot specify a value of 500 for a type = "u8" option.

min_len

Only valid on type = "string" or type = "list[string]"

[options.SYSTEM_PROMPT]
type = "string"
validation.min_len = 100

The minimum number of characters required for the value of this option.

max_len

Only valid on type = "string" or type = "list[string]"

[options.SYSTEM_PROMPT]
type = "string"
validation.max_len = 2000

The maximum number of characters accepted for the value of this option.

regex

Only valid on type = "string" or type = "list[string]"

TOML parses the \ character, so you will need to escape backslashes in your regular expression with another backslash. See the example TOML below.

[options.EMAIL]
type = "string"
validation.regex = "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"

A regular expression used to validate the value given for this option. Partial matches will be accepted. You can use anchors if you need to control this behaviour.

min_size

Only valid on type = "blob" or type = "list[blob]"

[options.IMAGE]
type = "blob"
validation.min_size = { size = 1.0, unit = "KiB" }

Specifies a minimum size for a blob or list of blobs. Available units:

Unit	Name	Size in Bytes
b	BYTE	1
KiB	KIBIBYTE	1,024
MiB	MEBIBYTE	1,048,576
GiB	GIBIBYTE	1,073,741,824
TiB	TEBIBYTE	1,099,511,627,776
kB	KILOBYTE	1,000
MB	MEGABYTE	1,000,000
GB	GIGABYTE	1,000,000,000
TB	TERABYTE	1,000,000,000,000

max_size

[options.IMAGE]
type = "blob"
validation.max_size = { size = 5.0, unit = "MiB" }

Specifies a maximum size for a blob or list of blobs. Available units:

Unit	Name	Size in Bytes
b	BYTE	1
KiB	KIBIBYTE	1,024
MiB	MEBIBYTE	1,048,576
GiB	GIBIBYTE	1,073,741,824
TiB	TEBIBYTE	1,099,511,627,776
kB	KILOBYTE	1,000
MB	MEGABYTE	1,000,000
GB	GIGABYTE	1,000,000,000
TB	TERABYTE	1,000,000,000,000

Overview

Guides

Concepts

Configuration

Features

Examples

Help

​Introduction

​Example

​File format reference

​edition

​Second edition

​First edition

​agent

​name

​version

​description

​capabilities

​runtimes

​docker

​executable

​options

​type

​Numeric types

​Other types

​List types

​Edition 1 types

​transport

​required

​secret

​base64

​default

​display

​label

​description

​group

​multiline

​validation

​variants

​min

​max

​min_len

​max_len

​regex

​min_size

​max_size

Introduction

Example

File format reference

edition

Second edition

First edition

agent

name

version

description

capabilities

runtimes

docker

executable

options

type

Numeric types

Other types

List types

Edition 1 types

transport

required

secret

base64

default

display

label

description

group

multiline

validation

variants

min

max

min_len

max_len

regex

min_size

max_size