Overview
How the Connic Composer SDK works: the project structure, the building blocks you compose into agents, and how your repository connects to Connic.
Define agents in YAML, write tools in Python, and manage everything with version control. Push to deploy. Review in PRs. Roll back with git revert. Iterate with the cloud dev server and gate every release with tests.
Why Code-First?
Track changes, review PRs, rollback deployments
Same config in dev, staging, and production
Write Python functions your agents can call
Connect external MCP servers for additional tools
Store API keys and credentials safely
Have teammates review agent configurations
SDK Building Blocks
Everything you can compose into an agent, from the tools it calls to the safety nets around it.
Tools your agents can call
Custom Tools
Plain Python functions become tools. Type hints turn into a JSON schema automatically.
API Spec Tools
Point at an OpenAPI spec and Connic generates callable tools, with auth, wildcards, and per-tool overrides included.
Database Tools
Built-in persistent collections. No hosting, no migrations, no schema setup.
Knowledge Tools
Query, store, and delete entries in your knowledge base from inside an agent.
MCP Servers
Connect any Model Context Protocol server to expose its tools to your agents.
Predefined Tools
Web search, knowledge retrieval, and triggering other agents. Built in and ready to use.
Shape how agents run
Output Schema
Force structured JSON output with JSON Schema for reliable downstream parsing.
Guardrails
Input validation, output filtering, PII redaction, and prompt-injection detection. Configured in YAML.
Context
A shared dictionary that lives for an entire run. Accessible from middleware, prompts, and tools.
Middleware
Run code before and after agent execution to enrich inputs or post-process outputs.
Hooks
Wrap individual tool calls to log, validate, or short-circuit each invocation.
Variables
Per-environment secrets injected at runtime. Different keys for staging vs production.
Get started in seconds
Install the Connic Composer SDK using pip:
pip install connic-composer-sdkOptional but recommended
The Connic team maintains an open SKILL.md-format skill that teaches AI coding agents how to write idiomatic Connic projects — the full project layout, every YAML key, all eleven connectors, the real CLI flags, and the team's recommended best practices for guardrails, tests, and tool wrapping. It works with Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini, and any other agent that supports the SKILL.md standard.
Install for any supported agent:
npx skills add connic-org/connic-skillOr, inside Claude Code, install the plugin from the marketplace:
/plugin marketplace add connic-org/connic-skill
/plugin install connic@connicView the skill on GitHub for the layout, per-agent install paths, and the evaluation suite used to keep it in sync with the SDK.
CLI Commands
The SDK provides a command-line interface to scaffold and validate your agent projects:
See Dev Server for the iteration loop, and Testing for the test framework and deploy gate.
Project Structure
For simple projects, keeping agent YAMLs and tool modules at the top level of agents/ and tools/ is usually the easiest option. Larger projects can optionally organize both directories into subfolders.
YAML files that define your agents. Each file represents one agent with its model, system prompt, and tool configuration. Subfolders are optional for larger projects.
Python modules containing custom tools your agents can use. Any Python function can be used as a tool, and nested modules are supported when you want more structure.
Optional Python modules that run before and after agent execution. See middleware. Auto-discovered by agent name.
Optional Python modules that run before and after each tool call. See tool hooks. Auto-discovered by agent name.
Agent Types
Connic supports three types of agents for different use cases
Standard AI agents powered by language models
Chain multiple agents together in a pipeline
Execute tools directly without AI reasoning
See the Agent Configuration Reference for detailed configuration of each type.
Secure secrets management
Configure environment variables in the dashboard under Settings → Variables. These are injected into your agent containers at runtime and accessible via os.environ.get().
Variables are environment-specific. Use different API keys for staging vs production.
Connect Your Repository
# Initialize git repository
git init
# Add your files
git add .
git commit -m "Initial agent setup"
# Add your connected repository as remote
git remote add origin <your-connected-repo-url>
# Push to trigger deployment
git push origin <your-deployment-branch>Once your repository is connected to a Connic project, pushing changes to your configured deployment branch will automatically trigger a new deployment.
Connic deploys your agents whenever you push to your connected repository. Push to your configured deployment branch and the platform handles the rest: building, deploying, and scaling.
Learn about deployment options