Platform overview

Alquimia Platform is built from three complementary components. Understanding how they relate helps you choose the right deployment pattern for your team.

alquimia-core: the execution engine

alquimia-core is a Python SDK that implements the agent execution engine. It is responsible for everything that happens after an inference request is accepted:

• Loading and validating agent configurations from a registry
• Running the execution loop through preprocessing, processing, and answer stages
• Managing short-term and long-term memory
• Discovering and invoking tools (MCP servers, Llama Stack, other agents, Python modules)
• Enforcing shields that classify or block unsafe inputs and outputs
• Persisting conversation state and emitting the audit worklog

Use alquimia-core directly when:

• You are building a Python application that embeds agent logic.
• You want full control over the execution loop and event handling.
• You do not need an external HTTP service or multi-tenant session management.

alquimia-runtime: the service layer

alquimia-runtime is a FastAPI service that wraps alquimia-core in an HTTP API. It is responsible for everything at the platform boundary:

• Authenticating inbound requests via API token, JWT, or Keycloak OIDC
• Accepting inference requests and streaming progress back via SSE
• Managing session context, blob storage, and the knowledge base
• Maintaining the registry of agents, tools, models, and secrets
• Routing events between master and worker instances through an event bus
• Exposing health, metrics, and webhook endpoints

Use alquimia-runtime when:

• You want to expose agents as a service to multiple applications or channels.
• You need horizontal scaling, persistent audit logs, and enterprise auth.
• You are deploying to Kubernetes or running a multi-channel agent.

alquimia-studio: the visual management layer

alquimia-studio is the web-based visual interface for Alquimia Platform. It is a Next.js application that connects to alquimia-runtime and provides a wizard-driven workflow for building, testing, publishing, and operating agents without requiring every change to be made in code. See the Studio overview for a full feature list and installation steps.

Studio provides:

• Agent creation wizard — step-by-step configuration of identity, model, tools, A2A delegation, knowledge base, memory, and evaluation strategies.
• Multi-agent orchestration — visually wire primary agents to sub-agents by ID or capability tags.
• Integration channels — configure WhatsApp Business API and Email (SMTP) endpoints.
• Knowledge base and RAG — upload documents, select embedding models, and manage topics.
• Try Me testing — interact with an agent in real time before publishing.
• Registry publishing — publish agentspaces to an OCI registry with version tags, or discover and install published agentspaces.
• Trust Lens and OpenTelemetry — monitor inference quality, token usage, traces, and audit trails.

Use alquimia-studio when:

• You want a visual interface for managing agents, registries, and knowledge sources.
• You are prototyping agent behavior before committing configuration to code.
• Your operators need to inspect runs, approvals, knowledge sources, and integration channels without using the CLI or API directly.

Typical deployment topology

                         External clients
              (web apps, Slack, WhatsApp, Email)
                              │
                              ▼
                 ┌────────────────────────┐
                 │   alquimia-runtime     │
                 │   master (HTTP API)    │
                 └───────────┬────────────┘
                             │ events
                             ▼
                 ┌────────────────────────┐
                 │      event bus         │
                 │      (Kafka)           │
                 └───────────┬────────────┘
                             │ events
                             ▼
                 ┌────────────────────────┐
                 │   alquimia-runtime     │
                 │   worker (executor)    │
                 │  uses alquimia-core    │
                 └───────────┬────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
         PostgreSQL      Redis           Qdrant
        (audit/logs)  (state/cache)   (vectors/RAG)

The master handles external traffic and publishes events. Workers consume events and execute agents using the core engine. This separation lets you scale inference workers independently from the API front end. Studio connects to the runtime’s HTTP API and is typically deployed as a separate web service or consumed through a browser.

Deployment patterns

Pattern	Components	Best for
Embedded SDK	alquimia-core only	Python applications, custom services, local prototyping
Single-node service	alquimia-runtime in all mode	Local development, small teams, Railway-style templates
Distributed service	Master + workers + Kafka + PostgreSQL + Redis	Production workloads, horizontal scaling, enterprise auth
Studio-managed service	Runtime + Studio	Visual management, operator workflows, team collaboration

Tip

The all mode runs master and worker in the same process. It is convenient for getting started, but production deployments should use separate master and worker replicas for independent scaling and failure isolation.

Integration points

• LLM providers are connected through provider-specific connectors. You can use OpenAI, Anthropic, Ollama, vLLM, or any OpenAI-compatible endpoint.
• Tools are connected through MCP, Llama Stack, A2A, or plain Python modules.
• Channels normalize inbound messages from WhatsApp, Slack, Email, and web into the same inference pipeline.
• Secrets are resolved at runtime from HashiCorp Vault or environment variables.
• Observability is exported through OpenTelemetry metrics, traces, and logs.
• Studio connects over HTTP to the runtime API and uses the same bearer tokens, JWT, or Keycloak OIDC for authentication.

Next steps

• Quickstart — run your first agent conversation.
• Architecture — dive into the event-driven execution model.
• Deployment guides — run the full platform stack.