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.
- 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.
- 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 |
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, and knowledge bases are documented in the agent specification reference.
Example agent configurations are available in the example agent configurations page.