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/devmode/exampleApplication/privkey/session1/sse?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

Agent’s 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 Registry Configuration for details on how to expose your configuration options.

Prompt injection (optional)

Coral Server’s session creation API supports passing in a systemPrompt parameter to agents - intended to allow extra text to be injected to those agents’ system prompts.

To support this feature, read the CORAL_PROMPT_SYSTEM environment variable - and interpolate it into your existing prompt.

If you don’t plan on supporting this feature, or it makes no sense for your agent - it’s recommended you output an error/warning if CORAL_PROMPT_SYSTEM is being set.

Packaging your agent

Now that your agent works with Coral, to make it easy to work with orchestration - you need to package your agent.

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

It’s recommended you support both runtimes if you intend to publish your agent.

Docker

Executable

This runtime is even more implementation dependent - since you are running a command/process directly. It’s also not portable, since it’s hard to account for all possible system environments.

For that reason it’s recommended to use the Docker runtime instead - although for writing public agents, you should still support this runtime.

A good pattern to maximise portability is writing bootstrap 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 are some examples of bootstrap scripts we use for our agents:

#!/usr/bin/env bash

# Bash script that sets up a python virtual environment with uv, and runs the python script provided.
# Usage: `./run_agent.sh <python_script>`

# Check for exactly one argument
if [ $# -ne 1 ]; then
  echo "Usage: $0 <python_script_path>" >&2
  exit 1
fi
PYTHON_SCRIPT="$1"

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

# Ensure write permissions for script directory
chmod u+w "$SCRIPT_DIR" || {
  echo "Error: Could not set write permissions for $SCRIPT_DIR" >&2
  exit 1
}

PROJECT_DIR="$SCRIPT_DIR"
echo "Project directory: $PROJECT_DIR"
echo "Python script to run: $PYTHON_SCRIPT"

# Change to project directory
cd "$PROJECT_DIR" || {
  echo "Error: Could not change to directory $PROJECT_DIR" >&2
  exit 1
}

# Set and activate virtual environment
echo "Activating virtual environment..."
VENV_ACTIVATE="$([[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" || "$OSTYPE" == "cygwin" ]] && echo "$PROJECT_DIR/.venv/Scripts/activate" || echo "$PROJECT_DIR/.venv/bin/activate")"
[ ! -f "$VENV_ACTIVATE" ] && { echo "Error: Virtual environment activation script $VENV_ACTIVATE not found" >&2; exit 1; }
source "$VENV_ACTIVATE" || { echo "Error: Failed to activate virtual environment" >&2; exit 1; }

# Run Python script
echo "Running $PYTHON_SCRIPT..."
uv run "$PYTHON_SCRIPT" || { echo "Error: Failed to run $PYTHON_SCRIPT" >&2; exit 1; }

Writing registry snippets

To make it easier for others to use your agent, you should share registry snippets for people to paste into their application.yaml. It is not expected for users of your agent to modify this registry snippet directly (except for the name of it in their registry).

Feel free to look at the README’s of our agents listed here to see examples of registry snippets

Make sure to provide multiple snippets for each runtime that you support.

An agent definition in an application.yaml has two parts, the options, and the runtime:

Options

options are a list of user configurable options you want to expose.

Each option has:

name

string

required

The name of the option (e.g API_KEY, MODEL_TEMPERATURE, MODEL_PROVIDER)

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. All agent options are optional by default, unless this default field is defined. The type of this is a number or string, depending on what type is set to.

Runtime

Docker

image should be the docker image Coral Server should pull and use. It should be the same URL you would pass to docker pull [image]

my_agent: # change this
  options:
    - # ...
  runtime:
    type: "docker"
    image: "[url to docker image (ghcr.io, docker registry, etc)]"
    environment:
      - # ...

Executable

command should be an array of strings that represent the command Coral Server should run, to run your agent.

my_agent: # change this
  options:
    - # ...
  runtime:
    type: "executable"
    command: ["python", "-u", "agent.py"]
    environment:
      - # ...

All runtimes have an environment field, which is a list of environment variables we want to pass in during orchestration. This is also how you pass defined options to agents.

There are a few ways to declare an environment variable:

Pass option directly

- option: "NAME" # passes the value of the option NAME as an environment variable with the same name

Pass option with different name

- name: "NEW_NAME" # name of the env var
  from: "OPTION_NAME" # name of the option to take the value from

Static environment variable

- name: "NAME" # name of the env var
  value: "some fixed value" # the value of the env var

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 /devmode/[appId]/[privKey]/[sessionId]/see?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 /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.

Introduction

Core Concepts

Examples

Get Started

Guide

Troubleshooting/FAQ

Onboarding Agents

Prerequisites

Modifying your agent

Connect to Coral

Agent Configuration

Prompt injection (optional)

Packaging your agent

Writing registry snippets

Options

Runtime

Orchestration Environment

Devmode

Introduction

Core Concepts

Examples

Get Started

Guide

Troubleshooting/FAQ

​Prerequisites

​Modifying your agent

​Connect to Coral

​Agent Configuration

​Prompt injection (optional)

​Packaging your agent

​Writing registry snippets

​Options

​Runtime

​Orchestration Environment

​Devmode

Prerequisites

Modifying your agent

Connect to Coral

Agent Configuration

Prompt injection (optional)

Packaging your agent

Writing registry snippets

Options

Runtime

Orchestration Environment

Devmode