Skip to main content

Overview

Building robust, context-aware AI agents requires more than just passing a prompt to a language model. Caesura introduces a powerful mental model for building agents: Observation and Injection.

Caesura operates as a background observer to your application's conversational flow. It analyzes the ongoing dialogue to detect psychological patterns, emotional shifts, and communication dynamics, then injects actionable recommendations back into the context for the agent's next turn.

Integration Architectures: SDK vs MCP​

There are two primary ways to integrate this observation cycle into your application: using our SDKs or connecting to our MCP Server.

The MCP Server​

The Model Context Protocol (MCP) server is the easiest way to add Caesura to existing AI clients (like Cursor, Claude Desktop, or LM Studio).

  • Pros: Requires zero code changes. You simply add a configuration block to your client.
  • Cons: It is slower and more expensive. Because MCP tools are invoked by the LLM itself, the model spends output tokens generating the tool call, waits for the HTTP response, and then resumes generation. This adds noticeable latency.

The Caesura SDKs​

If you are building your own application, the SDKs (@caesura-io/ai-sdk and @caesura-io/openai) are the recommended approach.

  • Pros: Much faster and cheaper. The SDK intercepts the conversation before it hits the LLM, meaning no output tokens are wasted on tool calls, and the model doesn't pause to invoke tools.
  • Cons: Requires installing a package and slightly modifying your application code.

SDK Execution Modes: Sync vs Async​

When using the SDK, you have two choices for how the observation cycle interacts with your application's critical path: Async (the default) and Sync.

Async Mode (Default)​

In async mode, Caesura operates entirely out-of-band.

  1. Observe: The SDK observes the conversation you are sending to the LLM.
  2. Analyze (Async): It fires a non-blocking request to the Caesura backend.
  3. Generate (Unblocked): Simultaneously, your LLM request proceeds without waiting for Caesura.
  4. Buffer & Inject: When the Caesura analysis finishes, it is buffered locally. The next time your user speaks, the buffered recommendation is injected into the prompt.

Best for: Long conversations and real-time interactions (like voice agents) where latency is the top priority. The trade-off is a one-turn "lag" in recommendations.

Sync Mode​

In sync mode, the SDK awaits the Caesura analysis before forwarding the request to the LLM.

  1. Observe & Analyze: The SDK sends the conversation to Caesura and waits for the result.
  2. Inject: The recommendation is immediately injected into the prompt.
  3. Generate: The LLM request proceeds with the fresh context.

Best for: Short text conversations where you need the highest precision and immediate behavioral steering, and can tolerate a slight latency increase before the LLM begins streaming.

Rather than blocking your application's critical path to wait for complex psychological analysis, Caesura works out-of-band.

The Observation Cycle​

  1. Observe: Your application makes a standard call to a language model (e.g., via the Vercel AI SDK or OpenAI SDK). The Caesura middleware transparently observes the conversation history being sent.
  2. Analyze (Async): The middleware sends the conversation to the Caesura backend. Caesura analyzes the transcript for hidden motivations, avoided topics, and emotional undertones.
  3. Buffer: The resulting insights and recommendations are returned to your server and buffered locally in memory.
  4. Inject: The next time your application makes a language model call for that same conversation, the Caesura middleware injects the buffered recommendations directly into the model's system context.

Data Privacy & Flow​

When using the Caesura SDKs, your data flows securely:

  • Provider API Keys (e.g., OpenAI): These remain securely on your server and are sent only to the provider. They are never transmitted to Caesura.
  • Conversation Content: The conversation history is sent to both the provider (for generation) and the Caesura backend (for analysis).
  • Caesura API Keys: These are sent only to the Caesura backend.

To dive deeper into implementing this pattern, see the SDK Overview to choose your language integration.