Core SDK overview
alquimia-core is the Python SDK and command-line interface that implements the agent execution engine. It can be used directly in Python applications, embedded inside the runtime service, or paired with Studio for visual management.
SDK responsibilities
Section titled “SDK responsibilities”The core SDK provides:
- Agent registry — loading and validating agent configurations.
- Versioned registries — loading specific OCI-tagged agentspace snapshots without mutating the workspace
dist.json(0.5.2+). - Execution loop — the preprocess, process, and answer pipeline.
- Evaluation strategies — controlling when an agent stops reasoning and returns.
- Memory management — short-term context window control and long-term summarization.
- Tool integration — MCP servers, Llama Stack groups, A2A agents, and Python modules.
- Shields — guard models for input/output safety.
- Knowledge sources — RAG, on-demand search, direct file access, and Boltzmann Brains.
- Audio adapters and streaming channels — STT/TTS connectors for voice notes and
StreamingChannelBasefor held-open phone/WebRTC audio sessions. - Observability — OpenTelemetry metrics for the execution loop.
When to use the SDK directly
Section titled “When to use the SDK directly”Use alquimia-core directly when:
- You are building a Python service or data pipeline.
- You want full control over event handling and execution.
- You do not need the runtime’s HTTP API, multi-tenant session management, or channel adapters.
Installation
Section titled “Installation”Python 3.12 is required. Choose the extras that match the providers and tools you plan to use.
| Install command | Capabilities |
|---|---|
pip install alquimia-core | Base install (no LLM or tool execution) |
pip install "alquimia-core[core]" | Full agent runtime: LLMs, MCP tools, vector stores, Redis memory |
pip install "alquimia-core[cli]" | Command-line interface |
pip install "alquimia-core[registry]" | OCI push/pull, Vault, TinyDB registry |
pip install "alquimia-core[security]" | FastAPI and JWT helpers |
pip install "alquimia-core[identity]" | SPIFFE workload identity |
pip install "alquimia-core[aws]" | AWS connectors |
pip install "alquimia-core[tools]" | Schema extraction from Python functions |
pip install "alquimia-core[leviathan]" | HuggingFace, OpenVINO, Triton inference connectors, deployable self-hosted STT/TTS Triton backends, and miniaudio-backed MP3 decoding for TTS output |
For most use cases, install the full runtime plus the CLI:
pip install "alquimia-core[core,cli,registry]"CLI quick reference
Section titled “CLI quick reference”The alquimia CLI manages agentspaces, secrets, agents, tools, and brains locally.
| Command | Purpose |
|---|---|
alquimia registry create --name myspace | Create a local agentspace |
alquimia registry secrets add KEY --namespace myspace --scope global | Register a secret definition |
alquimia registry secrets put KEY value --namespace myspace | Store a secret value |
alquimia registry agents add agent.json --namespace myspace | Import an agent spec |
alquimia registry agents inspect my-agent --namespace myspace | Show an agent’s resolved configuration |
alquimia local chat my-agent --namespace myspace --interactive | Chat with an agent interactively |
alquimia registry tools add ... | Register a tool connection |
alquimia registry brains add ... | Register a Boltzmann Brain |
See Quickstart for a complete first conversation and the CLI reference for the full command set.
Configuration reference
Section titled “Configuration reference”The agent configuration format, provider options, evaluation strategies, memory strategies, decorators, channels, tools, knowledge bases, audio adapters, and streaming channels are documented in the agent specification reference.
Example agent configurations are available in the example agent configurations page.
Audio and voice
Section titled “Audio and voice”alquimia-core 0.5.1 added audio I/O adapters through the audio field on AssistantConfig. Version 0.5.2 extends them with an output_format field (wav or mp3) on TTS connectors, MP3 decoding via miniaudio, and updated OpenAI TTS defaults (gpt-4o-mini-tts model and alloy voice). Declare STT and TTS connectors to let an agent accept voice notes, produce audio replies, or both. The leviathan extra ships with cloud STT/TTS connectors and deployable self-hosted Triton backends. For held-open phone or WebRTC sessions, implement or configure a StreamingChannelBase subclass such as TwilioMediaStreamChannel.
Versioned registries
Section titled “Versioned registries”As of alquimia-core 0.5.2, you can load and run a specific OCI tag without overwriting the local workspace:
from alquimia.core import resolve_versioned_ref
registry, assistant_id = resolve_versioned_ref("production/support-bot:v1.2.0")load_version returns a registry pointed at an isolated snapshot, while parse_versioned_ref() and the VersionedRef helper parse references of the form <agentspace>/<assistant>[:<tag>]. The CLI exposes the same capability through alquimia registry fetch, alquimia registry versions, and alquimia local exec/chat.