Runtime Controls

Concurrency rules

Concurrency rules ensure that only one run per unique key is active at a time. Use them when an agent processes events for a specific support process, customer, or order and parallel processing would conflict.

Queue mode (default)

When another event arrives for an active key, it waits until the first run finishes and then starts automatically.

version: "1.0"

name: support-processor
type: llm
model: connic/gpt-5.6-terra
description: "Processes support tickets one at a time per process"
system_prompt: "You are a support agent. Process the incoming ticket."

# Only one run per process_id at a time. Additional runs wait in queue.
concurrency:
  key: "process_id"
  on_conflict: queue

Drop mode

When another event arrives for an active key, the new run is cancelled immediately. Use this when duplicate work would be wasteful.

version: "1.0"

name: notification-handler
type: tool
description: "Handles notifications, skipping duplicates"
tool_name: notifications.handle

# Drop duplicate runs for the same customer while one is active.
concurrency:
  key: "data.customer_id"
  on_conflict: drop

Coalesce mode

When another event arrives for an active key, its run waits as in queue mode, but only one run per key can wait. A newer event replaces the waiting run, so a burst of events during a long run leads to a single follow-up run with the latest payload. Use this when every event asks the agent to re-check the same state.

The replaced run is cancelled. Its context contains superseded_by_concurrency_rule and superseded_by, the ID of the run that replaced it.

version: "1.0"

name: process-agent
type: llm
model: connic/gpt-5.6-terra
description: "Re-evaluates the current process step on every status event"
system_prompt: "Check the current step of the process and act on it."

# Events that arrive during a run collapse into one follow-up run.
concurrency:
  key: "process_id"
  on_conflict: coalesce

Key extraction

The key uses dot notation to read the trigger payload. If a Kafka payload is {"data": {"customer_id": "abc"}}, use data.customer_id. If the path does not exist, concurrency enforcement is skipped for that run.

Interaction with max_concurrent_runs

Both constraints apply. With max_concurrent_runs: 5 and concurrency.key: "process_id", five process IDs can run in parallel, but only one run per process ID can be active. Runs waiting for their key do not take a slot.

Waiting runs

• Waiting runs are persisted. They survive restarts and deployments and start on the active deployment.
• A key stays held during a deployment. A run still finishing on the previous deployment keeps its key until it ends.
• A run paused for an approval keeps its key. After the decision, it resumes before any waiting run.
• In queue mode, waiting runs start in the order their events arrived.
• There is no limit on how many runs can wait and no wait timeout. Waiting time does not count toward timeout, and a run uses no Project credit before it starts. Runs cancelled by drop or coalesce never start.

Persistent sessions

Set session: true for one shared session across the agent’s runs. An object without key or with key: null uses the same shared session. false, null, or omitting session disables persistence.

version: "1.0"

name: support-bot
type: llm
model: connic/gpt-5.6-terra
description: "A support chatbot that remembers conversation history"
system_prompt: |
  You are a helpful support agent. Use the conversation history
  to provide contextual responses.

# Maintain persistent sessions keyed by chat ID from middleware
session:
  key: context.chat_id
  ttl: 86400  # Sessions expire after 24 hours of inactivity

# Keep long conversations within the model context window
context_compression:
  enabled: true
  # Optional model for compression summaries; defaults to the agent model
  model: connic/gpt-5.6-luna
  keep_recent_messages: 12
  # Optional early compression based on model-reported prompt usage
  max_prompt_tokens: 100000

History and browser state

history and browser both default to true. This example retains cookies and local storage for each chat while starting every run with fresh conversation history. With browser: false, browser tools still work but start with fresh browser state.

session:
  key: context.chat_id
  ttl: 86400
  history: false
  browser: true

Session key

The optional key separates sessions by a resolved value. When provided, it must use one of two prefixes:

• context.<path> resolves from middleware context, including keys derived from request data.
• input.<path> resolves from the raw connector payload before middleware. It requires valid JSON and supports nested paths.

Set the key in middleware

async def before(content: dict, context: dict) -> dict:
    # Extract a stable identifier for this conversation from the connector payload.
    payload = context.get("payload", {})
    context["chat_id"] = payload.get("chat_id")
    return content

Use an input key

# When the connector payload is JSON like {"user_id": "u123", "message": "..."}
session:
  key: input.user_id

TTL and session management

The optional ttl expires sessions after that many inactive seconds. The minimum is 60 seconds; without a TTL, sessions never expire. View and delete active sessions in the dashboard under Storage > Sessions. Sessions are scoped per environment.

Runs that share a session are not serialized. If two runs for the same session overlap, the run that writes second fails. When that can happen, add a concurrency rule on the field that identifies the session, for example concurrency.key: conversation_id with session.key: input.conversation_id.

Context compression

Enable context_compression to shorten conversation history when a provider reports that the context window is full. connic compresses before switching to a fallback, then makes one additional request to the same model with the shortened history. Each model call in the agent loop allows at most one such repair request, outside the normal attempt count. It keeps the original run deadline and the attempts already used. If repair fails, the normal retry or fallback policy continues. Set context_compression.model to use a separate summary model; the repair request uses the model that rejected the context. Set max_prompt_tokens to compress earlier using reported prompt usage. Use session_history.interval when stored history should also be compacted between runs.

Stored history has no limit on total size or number of runs; each stored message can be up to 5 MB. With session_history.interval: 4, every fourth run ends by summarizing older history and keeps the last keep_recent_runs runs (default 1) verbatim. Without it, every run loads the full stored history, and compression only shortens the request, not the stored session.