​
Deploying Coral Server

The first step to integrating Coral Server with your application is having a proper deployment of it. Exactly how you manage & deploy it depends on your application, but we offer a docker image for Coral Server, and support orchestrating agents via Docker.

​
Using Coral Server

In production, the only ways you should be interfacing with Coral Server & the agents inside - is through the create session endpoint (/sessions), and custom tools.

​
Creating Sessions

Creating sessions is how you define and orchestrate agent graphs. While Coral Studio provides a ready-made interface for doing it, when integrating Coral with your application, you’ll want to use Coral Server’s APIs directly. 
curl \
    -X POST \
    -H "Content-Type: application/json" \
    --url http://localhost:5555/sessions/ \
    -d "[JSON BODY HERE]"
To create a session, send a POST request to /sessions, with a JSON body containing your session parameters. Here are some sample request bodies: 
// Single agent session, with a custom prompt and an API key passed in.
{
  "applicationId": "...",
  "privacyKey": "...",
  "agentGraph": {
    "agents": {
      // each agent in a session is given a unique (for the session) name
      "my-agent": {
        "type": "local", // we want to run an agent from our local registry
        "agentType": "interface", // the name of the agent in the registry

        // agents in a registry have a set of options you can set
        "options": {
          "OPENAI_API_KEY": "..."
        },

        "tools": [], // let us pass custom tools to individual agents
        "systemPrompt": "Speak like a pirate!" // optional field for adding custom prompts
      }
    },
    // links define which agents can "see" each other
    "links": [["agent-1"]],
    "tools": {} // define our custom tools (see below section)
  }
}

​
Session Request Parameters

​
applicationId
string
required
The Application ID (defined in your application.yaml)
​
privacyKey
string
required
The Privacy Key for the given Application (also defined in your application.yaml)
​
agentGraph
object
required
The desired graph of agents for this session.
​
links
string[][]
required
What agents can interact with each other - defined as a list of ‘groups’ of agents, where each agent in a group can “see” every other agent in that same group.For example:
{
  "links": [
    ["a", "b", "c"],
    ["c", "d"]
  ]
}
Defines two groups, where agents a, b & c can all interact, and agents c & d can interact. Agents a & b however, cannot interact with agent d.
​
tools
Record<string, object>
required
Key-value dictionary defining all custom tools.
​
tools.[name]
object
Custom tool entry. The key for an entry is the name of that tool - which you reference in the tools field in each agent.
This name key is only used for referencing in the agent tools field, agents see the name defined in name

​
Custom Tools

There are a lot of scenarios in which you need agents to be given application-specific capabilities - that can’t be built into the agents themselves (if you are using 3rd party agents). For that reason, Coral Server supports injecting custom MCP tools at runtime.

​
Example - User Input

A common use case in applications is exposing some kind of “chat”-style agent to your end users. This can be implemented using custom tools.
Coral Studio implements this exact use case for easy local development. Feel free to browse the source code for an example implementation.
You’ll need to implement two tools, request-input, and respond-to-input (you can call them whatever you like) The flow would look (roughly) like:
  1. Agent calls request-input when they’re ready - which hangs until there is user input.
    • Your implementation of request-input would propagate this input request to your frontend, and resolve it once the user enters something (in say a chat style UI).
  2. Agent does whatever work it needs based on that user input.
  3. When the agent is ready to respond, it calls respond-to-input, with the answer/response as input.
    • Your implementation of respond-to-input would then carry that response to the frontend - to display to your end user.
An example definition for these tools (in your /sessions body) could look like the following: 
{
  // ...,
  "tools": {
    "request-input": {
      "transport": {
        "type": "http",
        "url": "http://[your-application]/api/mcp-tools/request-input"
      },
      "toolSchema": {
        "name": "request-input",
        "description": "Request input from the user. Hangs until input is received.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "Message to show to the user."
            }
          }
        }
      }
    },
    "respond-to-input": {
      "transport": {
        "type": "http",
        "url": "http://[your-application]/api/mcp-tools/respond-to-input"
      },
      "toolSchema": {
        "name": "respond-to-input",
        "description": "Respond to the last input you received from the user. You can only respond once, and will have to request more input later.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "response": {
              "type": "string",
              "description": "Response to show to the user."
            }
          },
          "required": ["response"]
        }
      }
    }
  }
}