Agent Configuration

The type field determines how your agent executes. Connic supports three agent types:

• LLM: For tasks requiring AI reasoning, conversation, or complex decision-making
• Sequential: For multi-step workflows where agents need to work in sequence
• Tool: For deterministic operations that don't need AI reasoning

Type Comparison

Configuration Fields

Writing System Prompts

system_prompt: |
  This is a multi-line system prompt.
  
  You can write multiple paragraphs here.
  The pipe character (|) preserves newlines.
  
  Use this for complex instructions.

Best practices: Be specific about role and responsibilities, include examples, specify output formats for structured responses, mention available tools.

Referencing Tools

# Reference tools by exact module path under tools/
tools:
  - search.web_search            # tools/search.py -> web_search()
  - billing.calculator.add       # tools/billing/calculator.py -> add()
  - email.send_notification      # tools/email.py -> send_notification()
  - billing.*                    # all public functions in tools/billing.py
  - support.search_*             # functions starting with search_ in tools/support.py

Tools are Python functions in your tools/ directory. Top-level modules use refs like calculator.add, while nested modules use the full dotted path like billing.calculator.add. See the Write Tools guide.

Use wildcards to include multiple functions from a module without listing each one. Patterns use standard wildcard syntax: * matches any sequence of characters. For example, billing.* includes all public functions in tools/billing.py, and support.search_* includes only functions starting with search_. Wildcards also work with API spec tools (e.g., api:stripe.*). The deployment fails if a wildcard matches zero tools.

Conditional Tools

Tools can be made conditionally available per request. Instead of a plain string, use a mapping where the key is the tool reference and the value is a condition expression. If the condition evaluates to false, the tool is completely removed from the agent for that request.

# Conditional tools: only available when the expression evaluates to true.
# Uses Python expression syntax (and, or, not, ==, !=, >, <, >=, <=).
tools:
  - calculator.add                                              # always available
  - calculator.multiply: context.multiply_allowed               # available when middleware sets context.multiply_allowed
  - web_search: input.search_enabled                            # available when input JSON has search_enabled=true
  - admin.dangerous_tool: input.role == 'admin' or context.admin  # equality check with or
  - premium.tool: input.tier == 'pro' and context.feature_on    # and with equality
  - optional.tool: not context.disabled                         # negation

async def before(content: dict, context: dict) -> dict:
    # Set context values that tool conditions can check.
    payload = context.get("payload", {})
    context["multiply_allowed"] = True
    context["admin"] = payload.get("role") == "admin"
    return content

Discoverable Tools

When an agent has many tools, loading all of them into the LLM context increases token usage and can reduce accuracy. Discoverable tools solve this by keeping rarely-used tools out of context until the agent actively searches for them.

List tools under discoverable_tools instead of tools. They use the same syntax (strings, wildcards, conditions). At runtime, the framework indexes these tools and lets the agent find and call them on demand with a natural-language query.

version: "1.0"

name: multi-purpose-assistant
type: llm
model: gemini/gemini-2.5-pro
description: "Assistant that discovers tools on demand to keep context lean"

system_prompt: |
  You are a multi-purpose assistant with access to many tools.

  You always have basic math tools available. For anything else,
  the framework will find the right tool for you automatically.

# Always available in the LLM context
tools:
  - math.calculator.add
  - math.calculator.multiply

# Indexed for on-demand discovery at runtime
discoverable_tools:
  - math.calculator.calculate_tax
  - orders.*
  - social.twitter.post_tweet
  - assistant_tools.*

mcp_servers:
  - name: large-toolset
    url: https://mcp.example.com/tools
    discoverable: true   # tools indexed for search, not loaded upfront

Concurrency Rules

Concurrency rules let you ensure only one run per unique key value is active at a time. This is useful when an agent processes events for specific entities (e.g., a support process, a customer, an order) and you need to prevent parallel processing of events belonging to the same entity.

version: "1.0"

name: support-processor
type: llm
model: gemini/gemini-2.5-pro
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

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

Persistent Sessions

By default, every request creates a new, isolated session. With persistent sessions enabled, the agent maintains conversation history across multiple requests, enabling multi-turn conversations that survive restarts and redeployments.

version: "1.0"

name: support-bot
type: llm
model: gemini/gemini-2.5-pro
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

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

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

Custom OpenAI-Compatible Providers

You can connect any OpenAI-compatible endpoint (self-hosted models, inference proxies, etc.) as a custom provider. In Project Settings > LLM Provider, click Add Custom Provider and configure:

• Model Prefix - a unique lowercase prefix for this provider (e.g. ollama)
• API Base URL - the endpoint URL (e.g. https://my-llm.example.com/v1)
• API Key - optional, leave empty if the endpoint has no authentication

Then use your prefix in agent YAML just like any built-in provider:

# Custom provider configured with prefix "ollama"
model: ollama/llama3

# Custom provider configured with prefix "vllm"
model: vllm/mistral-7b

At runtime, the model string is routed to your endpoint via LiteLLM's OpenAI-compatible handler. The prefix must not collide with built-in provider names.

Example Usage

# Using OpenAI
model: openai/gpt-5.2

# Using Anthropic
model: anthropic/claude-opus-4-7

# Using Google Gemini
model: gemini/gemini-2.5-pro

# Using Azure OpenAI (use your deployment name)
model: azure/my-gpt5-deployment

# Using OpenRouter (provider/model format)
model: openrouter/anthropic/claude-sonnet-4.5

# Using AWS Bedrock
model: bedrock/us.anthropic.claude-opus-4-7-v1:0

# Using Google Vertex AI
model: vertex_ai/gemini-2.5-pro

# Using a custom OpenAI-compatible provider (configured in Project Settings)
model: ollama/llama3

Provider Documentation

• OpenAI Models
• Anthropic Models
• Google Gemini Models
• Azure OpenAI Models
• OpenRouter Models
• AWS Bedrock Models
• Google Vertex AI Models