Connic Composer SDK

What It Is

connic-composer-sdk is the Python SDK and CLI for Connic's code-first agent workflow.

Use it to:

• define agents in YAML
• write custom tools as plain Python functions
• add middleware, schemas, sessions, retries, concurrency, and guardrails
• connect MCP servers and use Connic's predefined tools
• validate projects locally before uploading anything
• run hot-reload test sessions in isolated cloud environments
• deploy to Connic from the CLI or through a connected Git repository

Installation

pip install connic-composer-sdk

Requires Python 3.10 or newer.

Quick Start

# Create a new project
connic init my-agents --skill
cd my-agents

# Authenticate this project with Connic
connic login

# Validate the project locally
connic lint

# Start a hot-reload dev session in Connic cloud
connic dev

# Run declarative test suites against an environment
connic test

The default scaffold is intentionally minimal. If you want a starter project with working examples, use templates:

connic init my-agents --templates=invoice,customer-support --skill

Browse available templates at connic.co/agents.

The optional --skill flag installs the Connic AI coding-agent skill into both .agents/skills/connic and .claude/skills/connic so supported coding agents can use the Connic project layout, YAML fields, CLI flags, connector patterns, and best practices while editing your repo. For an existing project, run:

connic skill

In an interactive terminal, both commands detect Codex and Claude Code and ask whether to install the full Connic plugin for each detected client. The plugin bundles the same skill with Connic MCP. Declining leaves the project-local skill installation unchanged. See AI agent setup for manual and client-specific paths.

The CLI checks for SDK, project skill, Codex plugin, and Claude Code plugin updates when commands run. It checks every installed Claude Code scope separately. To check without updating, including from an AI coding-agent session, run:

connic update --check

connic update --skill updates only the project skill copies and client plugins that are already installed; it does not add missing integrations.

Example Project

my-agents/
├── agents/
│   ├── _defaults.yaml          # optional — shared defaults for every agent
│   └── support-assistant.yaml
├── tools/
│   └── billing.py
├── middleware/
│   └── support-assistant.py
├── schemas/
└── requirements.txt

_defaults.yaml is optional and can live at any depth under agents/. Its values are merged into every agent at that directory level and below (deeper layers and the agent file itself override earlier ones). Lists like tools, mcp_servers, and guardrails.input/output concat with dedup-by-ref so children add to inherited entries. name and description are not allowed in defaults. Every agent file must still define version, name, and description.

agents/support-assistant.yaml

version: "1.0"

name: support-assistant
type: llm
model: connic/glm-5.2
description: "Customer support agent with billing and retrieval access"
system_prompt: |
  You are a concise support agent.
  Use tools when they help produce a more accurate answer.

tools:
  - billing.lookup_invoice
  - retrieval_query

session:
  key: input.user_id
  ttl: 86400

guardrails:
  input:
    - type: prompt_injection
      mode: block
  output:
    - type: system_prompt_leakage
      mode: block

tools/billing.py

def lookup_invoice(invoice_id: str) -> dict:
    """Look up invoice status by invoice ID.

    Args:
        invoice_id: The invoice identifier

    Returns:
        Invoice details for the requested invoice
    """
    return {
        "invoice_id": invoice_id,
        "status": "paid",
        "amount": 199.0,
        "currency": "USD",
    }

Run:

connic lint
connic tools
connic test

Core Concepts

Agent Types

See Agent Configuration for the full YAML reference.

• llm: an LLM-driven agent with prompts, tools, MCP servers, schemas, and guardrails
• tool: a direct wrapper around a Python tool
• sequential: a pipeline that executes multiple agents in order

Tools

Custom tools are plain Python functions discovered from tools/, including nested modules. Type hints and docstrings are used to generate tool schemas automatically. Positional-only parameters, *args, and **kwargs are not supported. See Writing Tools for details.

To return a file from a tool, wrap one explicit source in ToolFile:

from connic import ToolFile


def export_invoice(invoice_id: str) -> ToolFile:
    """Generate an invoice PDF."""
    pdf = build_invoice_pdf(invoice_id)
    return ToolFile(
        mime_type="application/pdf",
        name=f"invoice-{invoice_id}.pdf",
        data=pdf,
    )

ToolFile accepts exactly one of data (inline bytes) or uri. It also carries an optional name and size_bytes; inline byte size is inferred and an explicitly supplied size must match. A tool may return one ToolFile or include files alongside JSON and text values in a list or tuple. Raw bytes are rejected because they do not identify a MIME type; wrap them in ToolFile(data=..., mime_type=...).

The SDK also exposes predefined Connic tools such as the ones documented in Predefined Tools:

• trigger_agent
• trigger_agent_at
• retrieval_query
• retrieval_store
• retrieval_delete
• retrieval_list_namespaces
• web_search
• web_read_page
• db_find
• db_insert
• db_update
• db_upsert
• db_delete
• db_count
• db_list_collections

Middleware and Runtime Controls

Per-agent middleware lets you modify inputs, enrich context, attach files, stop execution early, and transform outputs. See Middleware.

The YAML model also supports:

• retries
• timeouts
• max iteration limits
• key-based concurrency control
• persistent sessions
• output schemas
• MCP server connections
• input and output guardrails

Related docs:

• MCP
• Guardrails
• Variables
• Retrieval Tools
• Database Tools

CLI Commands

Run connic <command> --help for flags and examples.

Development Workflow

Local Validation

connic lint loads your project locally and catches issues like:

• invalid YAML
• missing required agent fields
• unresolved tool references
• duplicate agent names
• schema and middleware loading problems

Hot-Reload Testing

connic dev creates an isolated development environment in Connic cloud and syncs local changes while you iterate.

This is the main development loop when you need real connectors, predefined tools, and environment-scoped services.

Use connic test for one-shot declarative test suites from tests/, including CI runs and deploy-gate parity.

Deployment

Deployment targets Connic-managed environments.

• If your Connic project is connected to a Git repository, push to the branch configured for the target environment.
• If the project has no connected Git repository, use connic deploy.

Documentation

Contributing

See CONTRIBUTING.md.

Support

• Issues: github.com/connic-org/connic-composer-sdk/issues
• Email: support@connic.co

License

MIT. See LICENSE.