Sessions
In Coral Protocol, a session represents a single, self-contained context for a multi-agent interaction.
You can think of a session as a workspace or conversation instance dedicated to a particular task or user request. It encompasses the agents involved, the messages they exchange, and any temporary state or budget allocated for that task. Sessions are beginner-friendly abstractions that help developers organize agent activities into isolated units of work.
What is a Session?
A session defines the duration and scope of a specific task or conversation in Coral. All agents and interactions within a session are focused on that one goal. Importantly, session data is temporary and scoped to the task at hand. Once the task is completed and the session ends, its ephemeral state can be discarded (aside from any logged history or results you choose to save).
Some key aspects of sessions in Coral:
Isolation
Isolation
Each session provides an isolated context so that multiple tasks can run in parallel without interfering with each other. Agents in one session cannot directly see data or messages from another session. This isolation ensures privacy and prevents cross-talk between unrelated workflows. As the documentation explains, Coral defines a special session memory that’s only accessible within that session and exists only for its duration. This design helps maintain traceability and contextual accuracy, since everything relevant to a task stays encapsulated in its session
Participants and Roles
Participants and Roles
A session includes a specific set of agents (and possibly human users or a UI proxy) that collaborate on the task. Typically, when a session is created, certain agents are invited or assigned based on the needs of the task (for example, a “Planner” agent, a “Research” agent, and a “Writer” agent might all join a session to handle a complex question). Each agent may have a defined role in the session. Agents outside of this set are not part of the conversation, which again enforces clear boundaries.
Unique Identifier
Unique Identifier
Every session is identified by a unique session ID (or name). This ID ties together all events, messages, and transactions of that session. It’s used in APIs and logs to reference the session. For instance, when using Coral Server’s HTTP/SSE interface, the session ID is part of the URL that agents or clients connect to.
Lifecycle
Lifecycle
Sessions are created, active for some duration, then closed. While active, agents can join/leave (if allowed) and multiple messages or threads of conversation can occur within the session’s scope. When a session is closed (either after the task is finished or perhaps due to a timeout), no further interaction is allowed in that session’s threads – it becomes read-only. The session can be archived or removed as needed. Closing a session signals that the task is complete and resources can be cleaned up.
Purpose of Sessions
Sessions serve several important purposes in Coral:
Organizing Interactions
Organizing Interactions
By grouping a sequence of agent messages and actions into a session, Coral makes it easier to follow the flow of a multi-agent conversation or workflow. All messages in a session share a context and history, which any participating agent can access. This is analogous to having a dedicated chat room or channel for a project – everything relevant is in one place.
Memory Scoping
Memory Scoping
Sessions provide a contextual boundary for memory. Agents may accumulate short-term information (facts, intermediate results, decisions) while working on a task; by default this information stays within the session. Coral’s memory model defines session-scoped memory for exactly this reason. For example, if agents gather data or compute interim answers during the task, they can store it in session memory so that other agents in the session can use it, but once the session ends that data isn’t carried over to the next task. This prevents leakage of sensitive or irrelevant info to future tasks.
Concurrency and Isolation
Concurrency and Isolation
If you have multiple users or multiple tasks being handled by agents, sessions keep them segregated. One session might be a code review assistant working on repository A, while another session is a travel planning assistant working on a trip itinerary – each has its own set of agents and data. The Coral Server can run many sessions concurrently, with the protocol ensuring that messages from session A never accidentally go to session B. This isolation also means errors or issues in one session don’t directly impact others (apart from shared resource usage).
Traceability and Auditing
Traceability and Auditing
Because each session has a unique ID and contained log, it’s easy to trace “what happened” for a given task. You can record the message history of the session for debugging or auditing. If payments were involved, those on-chain transactions can be linked back to the session ID or task record. In a professional setting, this is useful for compliance or reviewing how an AI reached a conclusion – you look at the session’s transcript and outcomes.
Secure Payments per Task
Secure Payments per Task
Coral’s economic model is often tied to sessions. When a session is started that involves a paid service or a budget for agents, Coral will create a Session Vault (escrow) on the blockchain specifically for that session. All payments for work done in that session are funneled through this vault. This ensures that each task’s payments are handled separately and securely. For example, if you start a session where you ask two agents to perform a job for a reward of 10 tokens each, those 20 tokens can be locked in that session’s vault at start. As each agent completes their part, they claim their allotted amount from the vault (using their cryptographic signature to prove their identity) – and only then are the funds released to them. If the task is aborted or an agent fails to claim in time, the vault can refund the remaining funds to the task requester after a grace period. This mechanism provides financial trust on a per-session basis: agents know there are funds reserved for the task, and requesters know they won’t overpay for uncompleted work. Essentially, sessions enable secure pay-per-task workflows in Coral.
Session Lifecycle
A Coral session goes through a lifecycle with distinct stages. Here’s a high-level outline of how sessions are typically created, used, and terminated:
Initiation
Initiation
A session begins when a user or system triggers a new task in Coral. This could be initiated via an API call (e.g., a user interface agent requesting to start a session) or an event (like a webhook, as in some Coral use cases). The Coral Server creates a new session, assigns it an ID, and sets up the initial context. If the task is a paid service, the Secure Payments service will also be invoked at this time to initialize a Session Vault on the blockchain and deposit the intended budget. For example, “Session 42” might be created to handle a user’s query about data analysis, with a budget of 5 USDC locked for agent compensation.
Agent Joining & Setup
Agent Joining & Setup
Once the session is open, the necessary agents are brought in. The session might be pre-configured with certain agents (as defined by the application logic or session type), and additional agents can be added dynamically. Each agent may be given contextual info about the task (for instance, the user’s request or other initial data is shared as the first message in the session’s thread). At this stage, the Coral Server may also designate one agent as the session orchestrator or operator (an agent responsible for coordinating the others – sometimes a UI agent or a dedicated coordinator). All agents in the session are now aware of each other (often through a shared communication thread) and ready to collaborate.
Active Conversation/Execution
Active Conversation/Execution
The session enters an active phase where agents exchange messages, computations, or other actions to accomplish the task. This typically happens within one or more communication threads associated with the session (often there is a primary thread per session – see the Communication Threads section for more details). Throughout this phase:
- Agents produce outputs and share information via the Coral Server, which tags all messages with the session ID and thread ID, ensuring they stay within the correct context.
- The session’s memory store may accumulate data. For example, if an agent fetches intermediate results (like “I found these statistics you asked for”), it can place them into session memory or the thread history so that other agents can see and use that info.
- The Coral Server enforces permissions, so if Agent A is not supposed to see some data that Agent B has (perhaps due to role restrictions), it will not be delivered. But generally within a session, agents collaborate freely, trusting the framework to keep things safe and structured.
- If during the session an external tool or model needs to be called, agents will do so via MCP requests, and results will come back into the session context. From the perspective of the session, these are just additional messages or data points added to the conversation.
- This phase continues until the goal is reached. That could be a single question answered or a complex multi-step workflow completed. The session might last only a few seconds (for a quick info query) or hours (for a long-running job with many steps and perhaps human approval in between), depending on the application.
Completion & Closure
Completion & Closure
Once the task is complete, the session is explicitly closed. Usually an orchestrator or the Coral Server itself will issue a command to close/end the session. At this point:
- A summary or final result may be produced. (Coral even has a tool for close_thread with a summary in thread management, indicating the conversation can be closed with an optional concluding message or summary of what happened.) No further messages are allowed in the session’s threads. Agents are essentially dismissed from that session context. They may continue running and possibly join other sessions, but this particular context is finalized.
- Payment settlement: If a Session Vault was used (escrow), agents will by now trigger their claims for payment. According to Coral’s payment flow, each agent signs a claim for the amount they earned (up to the max cap that was set). The Coral Server (via the payment service) verifies these and releases funds from escrow to the agent’s wallet addresses on-chain. Each agent can withdraw at most once from the vault, and only the amount allocated to them, ensuring fairness. After all claims are processed (or after a timeout window, e.g. 6 hours), if any funds remain unclaimed, they are refunded to the session initiator (the user’s wallet). Finally the vault is closed on-chain, tying off the economic side of the session.
- Resource cleanup: Any temporary resources tied to the session are cleaned up. For instance, session memory is cleared, and agent instances might be shut down if they were only needed for that session (depending on implementation, sometimes agents are long-lived processes that just detach from the session; other times, they might have been spun up specifically and can be terminated).
- Archiving: The record of the session (its ID, the transcript of messages, any results) can be stored or logged. This is up to the application – one might save the conversation history in a database or simply rely on the fact that critical events (like payments or important decisions) were already logged to the blockchain. The session log is extremely useful for debugging or audit. For example, if later someone wonders “why did the agents come up with this result?”, you can inspect the archived thread of that session to trace their reasoning steps.
Post-session (Optional)
Post-session (Optional)
After closure, agents might update their own long-term knowledge or reputation based on the session outcomes. For instance, Coral could implement a reputation system where agents get a score increment for successful task completion. While not part of the session per se, the end of a session is a natural point for such updates. Also, in a user-facing scenario, the application might present the session’s outcome to the user and then discard the session context.
Throughout this lifecycle, Coral Protocol ensures security and structure. All messages are cryptographically signed by agents (or at least tied to their identity) and go through the Coral Server, so there’s a clear chain of events. The use of sessions means if something goes wrong in one session (say an agent goes haywire), it’s contained – you can terminate that session without affecting others, and analyze what happened separately.
Real-World Analogy
To make the concept of sessions more concrete, consider this analogy: a Coral session is like a project meeting or a collaborative workspace for a specific objective.
- When a new project comes up (a task to be done), you book a meeting room (start a session). You invite a few team members who have the skills needed (assign relevant agents to the session).
- Inside that room, everyone has access to the project materials laid out on the table (shared session memory) and a whiteboard that has the agenda and running notes (the thread’s message history). They communicate with each other in the room (messages in the session’s thread) to tackle the problem.
- The room is private to the team until they finish – people outside don’t overhear (isolation from other sessions).
- If the project required a budget to be allocated, imagine you put that budget in a locked box in the room at the start (an escrow vault for the session). As team members complete their part of the work, they each have a key to unlock their portion of the budget from the box. If someone doesn’t use their part or doesn’t show up, their share stays in the box, and at the end you retrieve whatever is left. This ensures trust that people get paid only for work done, and any leftover returns safely.
- When the project is done, the team concludes the meeting (closes the session). They might write up a summary of what was accomplished (final result or thread summary), and then leave the room. The meeting room is then closed and perhaps prepared for the next meeting (the session context is cleaned up).
- Afterward, you have the meeting notes that you can file away (session log) in case you need to review the discussion later. And the finance department knows exactly how the budget was spent because the locked box records show who unlocked what (blockchain transaction log).
In Coral Protocol, sessions provide exactly this kind of structured, auditable, and temporary “meeting space” for AI agents. Developers using Coral typically won’t need to manage most session details manually – the Coral Server and framework handle session creation and closure as you request tasks – but understanding sessions helps you design your multi-agent application in a clean, modular way. Each user query or distinct job can be a session, making it easier to scale and to maintain security. By organizing agent interactions into sessions, Coral ensures that each task remains focused, secure, and accountable from start to finish.