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 Coding 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 concatenate with key-aware deduplication: tools, discoverable_tools, and approval.tools by tool reference; approval.inputs by input-tool name; mcp_servers by server name; and guardrails.input/output by rule name when present. 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

Set session: true to share one persistent session across all runs of an agent. An object without key does the same; use key: input.user_id or key: context.chat_id to keep separate sessions by value. history and browser both default to true: set either to false to disable saving conversation history or browser cookies and local storage across runs. ttl is optional; without it, the session does not expire. session: false disables persistence.

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

Enable the browser tools together:

tools:
  - web_browser_*

This includes web_browser_open, web_browser_observe, web_browser_act, web_browser_screenshot, web_browser_mouse, web_browser_tabs, web_browser_dialog, web_browser_upload, web_browser_download, and web_browser_close. Individual tool names are also supported.

Each run uses one browser, selected automatically for every browser tool call. Calling web_browser_open again returns "Browser already open"; use web_browser_tabs for additional pages. The browser closes when its run ends. Runs attached to the same Connic session reuse saved cookies and local storage when session.browser is enabled.

The agent can type into the focused field, hold and release keys, double-click, switch tabs and popups, and handle browser dialogs. Screenshots are sent as images to vision-capable text and voice models.

web_browser_download(target, include_content=...) keeps the downloaded file in the browser session and returns download_id, name, and mime_type. Set include_content=True to also return the file as an attachment, or False for metadata only. web_browser_upload(target, download_id) selects that file for upload in the same session. Files are limited to 25 MiB and remain available until the browser session closes.

Human Input and Approvals

approval:
  tools:
    - auth.just_needs_approval
  inputs:
    - get_mfa:
        prompt: Use this tool when authentication requires an MFA code.
        label: MFA code
        sensitive: true
        params:
          - reason: str
          - account_email: str
  timeout: 300

approval.tools requires approval before executing existing tools, including conditional entries such as billing.refund: param.amount > 50.

approval.inputs generates tools on LLM agents that collect required text and return it to the agent. No Python function or top-level tools entry is needed. prompt describes the tool to the agent; label names the human input field and accepts at most 200 characters. sensitive defaults to false; enable it to mask the input and protect the response in storage and logs.

Input names such as get_mfa are exposed unchanged. They must be unique ASCII identifiers of at most 64 characters, cannot be search_tools or use_tool, and cannot collide with tools, discoverable_tools, or approval.tools. Generated input tools count toward the 100-tool agent limit.

Optional params declares arguments the agent supplies with the request. Supported types are str, int, float, and bool; every declared argument is required, and extra arguments are rejected. Omit params for a tool with no arguments. Parameter names must be unique ASCII identifiers and cannot be Python keywords; context is reserved.

Scripted test approvals accept response: "012345" alongside decision: approve for input tools.

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 opens a menu with a reusable development environment selected by default. Use Up/Down to move and Enter to select, then enter a name for a new reusable environment. The CLI saves the preferred reusable environment in .connic; when valid, it appears first and is selected by default on the next run. The CLI then syncs local changes while you iterate.

Quick tests are deleted when the session ends and leave the preferred reusable environment unchanged. Named environments retain their data, variables, and connectors. Use connic dev --quick or connic dev my-feature to select either mode directly; use one of these explicit choices for unattended runs.

Changes under the standard source directories hot-reload. Dependencies are installed from requirements.txt when the session starts, so changing that file requires stopping and recreating the dev session.

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. Use Up/Down to choose an environment by name and Enter to select it, then confirm the deployment summary before uploading.

connic deploy --list lists available targets without deploying. Use connic deploy --env staging to select a target by name; environment IDs remain supported. For CI, pass both an explicit target and confirmation: connic deploy --env staging --yes.

Documentation

Contributing

See CONTRIBUTING.md.

Support

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

License

MIT. See LICENSE.