This page is up to date, and intended for version 1.0 of the Coral Server and Coral Studio.

Prerequisites

A running instance of Coral Server
An existing agent you want to onboard to Coral

Modifying your agent

Agents interact with Coral sessions exclusively through a uniquely provided MCP server. All interaction with other agents is then done with the tools available through that MCP.

Connect to Coral

Since each agent in a session is given its own MCP - your agent must receive the MCP’s connection url dynamically. When running the agent through Coral Server’s orchestrator, that is provided by the CORAL_CONNECTION_URL environment variable. Here are some example snippets for popular Python frameworks:

These snippets are not complete implementations, or guaranteed to work as is for your agent! Actual integration heavily depends on your agent’s existing implementation.

from camel.toolkits.mcp_toolkit import MCPClient
from camel.utils.mcp_client import ServerConfig

coral_url = os.getenv(
    "CORAL_CONNECTION_URL",
    default = "http://localhost:5555/sse/v1/devmode/exampleApplication/privkey/session1/?agentId=example_agent"
)
coral_mcp = MCPClient(
    ServerConfig(
        url=coral_url,
        timeout=3000000.0, # These timeouts are large since wait_for_mentions, etc. can take a long time to resolve.
        sse_read_timeout=3000000.0,
        terminate_on_close=True,
        prefer_sse=True
    ),
    timeout=3000000.0
)

The default SSE connection url used in the snippets are devmode endpoints - useful for rapid local testing, without using the orchestrator.

Agent Configuration

Agents have a lot of options that users would want to change. API keys, models, providers, and even sampling parameters (temperature, top_p) - are all things we want to accept dynamically. Coral’s orchestrator provides an ‘option’ system, that allows you - the agent developer - to expose specific typed options, and receive the values of those options as environment variables.

This means you should not load .env files by default (unless using devmode), since environment variables should only be provided by Coral Server.

See Agent Options for details on how to expose your configuration options.

Packaging your agent

Now that your agent works with Coral, to make it work with orchestration - you need to package your agent. In the root of your agent repository/folder, create a coral-agent.toml file. This is the entrypoint for your agent from Coral’s POV. For example, for local use of agents - these files are referenced by your coral server’s registry.toml. An agent definition starts with basic metadata:

[agent]
name = "name-of-my-agent"
version = "0.1.0" # agent version (should be semver)
description = "Description of this agent's capabilities, that is shown to other agents"

Agent Options

Coral’s orchestrator allows you to expose specific typed options, to be passed to your agent on instantiation as environment variables¹.

¹ Future runtimes may pass options to agents via something other than environment variables

options are a map of option names, to user configurable options you want to expose. Each option has:

type

'string' | 'number'

required

Whether the value of this option should be a string or a number.

description

string

required

A description of what this option configures in your agent.

default

string | number

The default value of this option if not provided when spawning this agent. The type of this is a number or string, depending on what type is set to.

required

boolean

Whether this option is required. false by default.

Example coral-agent.toml snippet

# ...

[options]
DISCORD_API_TOKEN = { type = "string", description = "Discord API token", required = true }
DISCORD_THREAD_ID = { type = "string", description = "The ID of the thread to watch", required = true }
DISCORD_TIMEOUT_WARNING = { type = "string", description = "The amount of time before a warning issuing a warning to the user that the thread will timeout.", default = "30m" }
DISCORD_TIMEOUT = { type = "string", description = "After the timeout warning has occurred, the thread will close in this amount of time.", default = "30m" }
OPENROUTER_API_KEY = { type = "string", description = "An API key for OpenRouter", required = true }

# ...

Agent Runtimes

Coral Server’s orchestrator supports different ‘runtimes’ - or ways of running agents. It currently supports both Docker containers, and local subprocesses, with plans to support Kubernetes, Phala, and more.

It’s recommended you support Docker if you intend to publish your agent, or export it as a remote agent (closed beta).

Docker

Running your agent via docker naturally requires your agent to be containerized.How you containerize your agent depends a lot on how your agent is written - what language it uses, how it manages dependencies, etc. Feel free to browse our curated list of agents here for reference on packaging Python agents for Docker using uv.Once it is, you simply reference your image in the coral-agent.toml:

[runtimes.docker]
image = "name-of-docker-image" # whatever you would put in `docker run <image>`

While specifiying a tag does work, we recommend you do not add one, since Coral Server will use the agent’s defined version (as seen earlier) as the docker tag (for better reproducibility).This means you must tag your images with the agent’s version when publishing to a container registry.

For agents only intended to be ran by your own local coral servers, just having the image built & present locally is enough.For public agents, you need to make sure the image is available on a registry like Docker Hub or Github’s Container registry

Executable (local subprocess)

This runtime is even more implementation dependent - since you are running a command/process directly on the same host as the server. It’s also not portable, since it’s hard to account for all possible system environments.For these reasons it’s recommended you use the Docker runtime whenever possible.A good pattern to maximise portability is writing wrapper scripts for each OS you want to support, that handles ensuring dependencies are present/downloaded (e.g. create/enter a python virtual environment, download dependencies)Here’s an example of a bootstrap script we use for our agents:

Bootstrap script

#!/usr/bin/env bash
set -e

fatal () {
    echo "$1" >&2
    exit 1
}

PYTHON_SCRIPT="main.py"

# Determine script directory
SCRIPT_DIR=$(dirname "$(realpath "$0" 2>/dev/null || readlink -f "$0" 2>/dev/null || echo "$0")")

PROJECT_DIR="$SCRIPT_DIR"
echo "Agent directory: $PROJECT_DIR"

# Change to project directory
cd "$PROJECT_DIR" || fatal "Could not cd to '$PROJECT_DIR'"
echo "Running $PYTHON_SCRIPT..."
uv run "$PYTHON_SCRIPT"

Adding this runtime to your coral-agent.toml would look something like:

[runtime.executable]
command = ["bash", "-c", "run_agent.sh"]
# each 'word' of your command should be a separate item in the array, to minimise issues with argument parsing

Orchestration Environment

Agents run under orchestration are provided with a set of “system” environment variables that are needed/useful to work with Coral:

CORAL_CONNECTION_URL -> The URL of the MCP server this agent must connect to,
CORAL_AGENT_ID -> The ID of this agent,
CORAL_ORCHESTRATION_RUNTIME -> How this agent is being orchestrated ("docker", "executable"),
CORAL_SESSION_ID -> The ID of the session this agent belongs to,
CORAL_SSE_URL -> CORAL_CONNECTION_URL, but without any query parameters
- You should use CORAL_CONNECTION_URL instead, whenever possible.

Devmode

It can be useful to be able to run agents outside of Coral’s orchestrator to quickly iterate without needing to create sessions repeatedly. Coral Server supports running in “devmode”, which disabled Application ID / Privacy Key checking, and implicitly creates sessions whenever an agent tries connecting. To use, first run Coral Server in devmode:

./gradlew run --dev

Now, an agent can connect to /sse/v1/devmode/[appId]/[privKey]/[sessionId]/?agentId=[agentId] - and automatically have a session with that ID created (if it doesn’t already exist), and be registered with the provided agentId.

appId, privKey & sessionId can be anything, they just need to be identical between agents you want to be in the same session

To support running through devmode in your agents, a good practice is to default to a /sse/v1/devmode/... url when the CORAL_CONNECTION_URL environment variable is not set. You can also check that the CORAL_ORCHESTRATION_RUNTIME environment variable, and load a .env file if it isn’t set. This makes it easy to provide API keys, etc. to agents you run directly - since through orchestration those would normally be passed in when creating a session.

If you do load .env files in your agents, you must make sure you are not running in orchestration (by checking CORAL_ORCHESTRATION_RUNTIME for example) before loading them.Loading environment variables externally under orchestration can cause hard to debug issues like unintentionally used or accidentally shared API keys at best, and connection issues between the agent and the server at worst.

Overview

Guides

Concepts

Features

Examples

Help

Writing Agents

Prerequisites

Modifying your agent

Connect to Coral

Agent Configuration

Packaging your agent

Agent Options

Agent Runtimes

Orchestration Environment

Devmode

Overview

Guides

Concepts

Features

Examples

Help

​Prerequisites

​Modifying your agent

​Connect to Coral

​Agent Configuration

​Packaging your agent

​Agent Options

​Agent Runtimes

​Orchestration Environment

​Devmode

Prerequisites

Modifying your agent

Connect to Coral

Agent Configuration

Packaging your agent

Agent Options

Agent Runtimes

Orchestration Environment

Devmode