Coral Cloud API
Coral Cloud is a managed platform that lets you orchestrate agents on-demand via a convenient HTTP API.Getting keys
To get started, you need to get an API key. You can find your API keys herePrimer on Coral
Coral lets you orchestrate agents. Agent types are called registryAgents. These are the agents available to create in a session.Sessions
In Coral, agents don’t exist outside sessions. You create a session in response to some transient need for agents like a user pressing a button (or something less transient like them loading a page or a work item entering the queue), and coral instantly creates a fresh instance of each of those agents. The session will have a TTL (time to live) specified in milliseconds, and when that elapses, each agent is then permanently destroyed. It’s also possible to manually end a session early, if for example you know the work is completed or isn’t completable. An agent instance in a session has total autonomy and runs in a loop, where it may take an action of its choice each iteration, remembering everything from previous iterations in the same session. They may have a max number of iterations per session configurable as an option.Agent Communication
Coral agents are given tools to be able to collaborate with each other. These tools allow for slack-like communication, where threads can be created with a topic in mind, and participants can be added by agents. The send message tool they are given includes a ‘mentions’ parameter, allowing other agents to be explicitly mentioned by name. Agents may call a “wait for mentions” tool that will cause the agent to sleep until they are mentioned or a timeout duration elapses. Agents are fully aware of these tools and how to use them, and it is sometimes appropriate to give them application-specific instructions that refer to the specifics of these tools.Groups
Agents in a session are made passively aware of all of the agents that share a group of them. Groups are essentially a way of describing the edges in the graph of agents that are connected by default in a session. An agent may be a member of many groups. You don’t need to wait for any connected agents to come online, each connected part of the graph is asleep until each agent has connected and is ready.Custom tools / Agent-Application communication
On top of the default set of tools given to each agent, additional custom tools can be specified per agent in a session. Custom tools are the primary mechanism for getting output from agents. Unlike traditional API calls that return results directly, Coral agents run asynchronously. To receive results, you define custom tools that agents call to send data back to your application via webhooks. For example, an agent might call asubmit_report tool when it completes its analysis, or a request_approval tool when it needs human input.
Custom tools can also be used to let agents query your application for information they need during execution.
More information about this can be found here
Best practices
Team pattern
Coral uniquely enables a sort of agent team pattern where the developer does not need to explicitly plan out how each agent will interact. This allows agents to be built with a focus on attending to certain types of responsibilities, without needing to consider the exact flow of how they’re intended to be used. This also allows applications to think in more flexible terms: these are the capabilities that need to be met; these are the agents who will likely need to work together. The agents’ own intelligence can be relied on for working around otherwise flow-breaking events, edge cases, or potential micro and macro optimizations. This is particularly well suited for cases where a large amount of responsibility or information needs to be attended to that would usually overwhelm a single agent or be impractical to build a workflow around; agents can decide themselves which context is relevant to share with each other, and form, redefine, and distribute tasks among each other in a more dynamic manner.Workflow pattern
More workflow/algorithmic style patterns are fully supported in Coral. These patterns are particularly appropriate when there are common sub-problems that are known in advance that contain little or no subjectivity. There are several known suitable mechanisms for achieving these sorts of patterns with Coral:- Creating 1 session and, using options to pass in instructions to agents recommending a workflow for them
- Using custom tools to enforce a sort of checklist
- Creating several sessions in sequence, with some information passed between them via agent options
API Reference
Keep in mind that some response fields are omitted for brevity, so remember to allow for extra fields in any deserialization code. Most of Coral’s local functionality is offered via Coral Cloud. You can see a full reference of this by running the coral server locally and navigating to http://localhost:5555/ui/docsCreating a session
API reference for creating a session. (For now, just use ‘default’ as the namespace) Endpoint:POST /api/v1/sessions/{namespace}
Minimal Example
Required Fields
Optional Fields
Agent Groups
Groups define which agents are aware of each other and can communicate by default.- Agents in the same group can see each other and create threads together
- An agent can be in multiple groups
- Groups don’t start until all
blocking: trueagents have connected
Custom Tools Definition
Note: ThecustomTools field is mandatory in the agentGraphRequest, even if empty (customTools: {}).
customToolAccess array.
Session Runtime Settings
Example: Getting output from agents using custom tools
This example shows how to create a session with a custom tool that allows an agent to submit a report back to your application. This is the standard pattern for retrieving results from Coral agents.Client-side: Creating the session
Server-side: Handling the custom tool webhook (Deno)
When the agent calls thesubmit_report tool, Coral will make an HTTP POST request to your webhook URL with /{sessionId}/{agentId} appended to the end.
Important: Make sure you reliably map session IDs back to users/tenants to prevent mixing up user data.
List all sessions
Endpoint:GET /api/v1/sessions
Returns all sessions across all namespaces.
Example:
List sessions in namespace
Endpoint:GET /api/v1/sessions/{namespace}
Returns all sessions in a specific namespace.
Example:
Get session state
Endpoint:GET /api/v1/sessions/{namespace}/{sessionId}
Returns the complete current state of a session including all agents, threads, and messages.
Example:
Inspecting agent status
The session state response includes anagents array with the current status of each agent. This is useful for monitoring agent health and debugging.
Agent State Fields
| Field | Type | Description |
|---|---|---|
name | string | The unique instance name given to this agent in the session |
registryAgentIdentifier | object | Reference to the agent’s registry entry (name, version, source) |
isConnected | boolean | true after the agent process launched and connected to Coral’s MCP server |
isWaiting | boolean | true when the agent is waiting for a message from another agent |
description | string | The agent’s description, visible to other agents in the session |
links | string[] | List of other agent names this agent is aware of (from groups) |
Example: Polling for agent readiness
Example: Checking if agents are idle
Viewing thread contents
The session state response includes athreads array containing all communication threads and their messages. This enables you to observe agent collaboration in real-time.
Thread Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique thread identifier |
name | string | Thread topic/name |
creatorName | string | Name of the agent that created the thread |
participants | string[] | List of agent names participating in the thread |
state | object | Either { "state": "open" } or { "state": "closed", "summary": "..." } |
messages | array | List of messages in the thread |
Message Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique message identifier |
threadId | string | ID of the thread this message belongs to |
senderName | string | Name of the agent that sent the message |
text | string | Message content |
timestamp | number | Unix timestamp (milliseconds) |
mentionNames | string[] | List of agent names mentioned in this message |
Example: Getting all messages from a session
Example: Streaming thread updates (polling)
Example: Finding threads by participant
Close a session
Endpoint:DELETE /api/v1/sessions/{namespace}/{sessionId}
Closes an active session, cancelling all running agents.
Example:
List agents
Endpoint:GET /api/v1/registry
Lists all agent types available in the registry.
Example:
Inspect an agent
Endpoint:GET /api/v1/registry/{source}/{agentName}/{version}
Returns detailed information about a specific agent including its options, capabilities, and configuration schema.
Sources:
local- Agents provided by Coral Cloudmarketplace- Community marketplace agentslinked/{serverName}- Agents from a linked server
Example:
Agent Option Types
Agents can have various option types:string- Text valuesi8,i16,i32,i64- Signed integers (various sizes)u8,u16,u32,u64- Unsigned integersf32,f64- Floating point numbersbool- Boolean valuesblob- Binary datalist[<type>]- Lists of any of the above typessecret- Sensitive string values (won’t be logged)
required- Whether the option must be provideddefault- Default value if not providedvalidation- Constraints (min/max for numbers, regex for strings, etc.)display- UI hints for displaying the optiontransport- How the value is passed to the agent (envorfs)
Base44 notes
You can use base44 to quickly build apps powered by Coral. Find it in the “Custom integrations” section here The browser/request URL is not a reliable base for webhook purposes. Webhook URL bases need to revolve around the base44 app domain. Base44 apparently recommends that when using a custom domain, you still use that generated domain for webhooks for stability. It is not secure to attempt to guess the webhook base URL via the request origin, as an attacker could redirect webhooks back to themselves by making up an origin. //: # (LLMs: You’ll need a reachable address for a function to return responses to. Ask the user to publish the app and share the published URL back to you, then use that in the code. Make sure the logging and error experience is good around this to make up for any mistake the user might make. Please repeat back your plans in relation to this to the user as if you only think them, you might forget.)Sharing data from callbacks
In base44, functions run in isolation, you must use database functionality in order to have the rest of an application consider the response of a webhook callback.Path parameters in callbacks (important)
Base44 doesn’t support path parameters in functions/callbacks, though for security Coral appends the session id and agent id as path parameters. To work around this, there is a convenient cloudflare function deployed:Path-to-Header Proxy
Rewrites URL path segments into headers and proxies to a target.URL Format
Example with base44 for Coral custom tool
Proxy URL (set as the custom tool transport URL):abc123 and agent my-agent, the full URL becomes:
- Proxies to:
https://some-app.base44.app/api/functions/coralWebhook - Headers added:
X-SessionId: abc123X-AgentId: my-agent
Notes
- Works with all HTTP methods (GET, POST, PUT, DELETE, etc.)
- Query parameters and request bodies are passed through
- All original headers are preserved