.railway.internal` names. |
| Uploaded artifacts disappear after restart | Confirm volumes are attached to `runtime`, `qdrant`, `minio`, and `oras-registry`. |
# What is Alquimia
Source: https://docs.alquimia.ai/getting-started/what-is-alquimia
Understand the Alquimia ecosystem and how its products fit together.
**Alquimia** is a platform for running enterprise level AI assistants on your own infrastructure: you design how agents behave, you ground them in your documents when needed, and everything executes in one place behind the scenes.
**[Alquimia Studio](/products/studio/index)** is where you build and operate agents — the place teams live day to day for configuration and health.
**[InsightHub](/products/insight-hub/index)** is for knowledge work: topics, uploads, and guided exploration over your content, still powered by the same agents and execution stack.
**[Alquimia Core & Runtime](/platform/runtime)** is that shared execution layer — Core is the SDK that drives the inference pipeline, tool ecosystem, memory strategies, and agent registry; Runtime is the FastAPI service that runs it all in production, wiring multi-channel connectors and coordinating agent work over a CloudEvents-based event model.
## The ecosystem at a glance
| Piece | What it is |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Studio** | Where you create and manage agents and workspace settings. |
| **InsightHub** | Where you structure documents and explore them in conversation. |
| **Core & Runtime** | The inference and orchestration layer. **Core** is the SDK: inference pipeline (shields, generation, tools, memory, empathy engine), multi-provider LLM connectors, a unified tool layer (MCP, Llama Stack, built-ins, A2A), and the agent registry. **Runtime** is the FastAPI service that runs it: inference API, multi-channel connectors (Slack, WhatsApp, Email), and CloudEvents-based event orchestration. |
| **Twyd** | The knowledge service behind document ingestion and search used when answers must stay close to your files. |
## The agent lifecycle
When you build an agent in Studio, here's what happens end-to-end:
```mermaid theme={null}
flowchart LR
A["Studio\n(you configure)"] --> B["Runtime Registry\n(config stored)"] --> C["Runtime\n(agent executes)"]
```
1. You configure an agent in Studio.
2. That configuration is stored in the **Runtime Registry**.
3. When someone chats — in Studio, InsightHub, or a connected channel (Slack, WhatsApp, Email) — the Runtime loads that configuration and runs it through the Core inference pipeline end to end.
4. Usage and health show up in the observability setup your team configured; Studio is the usual place to review agent-focused metrics.
## Next steps
See every service, its port, and what it does.
Get the stack running locally with Docker Compose.
If you are extending, integrating, or deploying the execution layer itself, the reference material lives on the **[Alquimia Runtime documentation site](https://platform-docs.alquimia.ai/)** (CLI, SDK, HTTP API, and operations).
# Introduction
Source: https://docs.alquimia.ai/index
Documentation hub for the Alquimia ecosystem — Studio, InsightHub, and Runtime.
[Alquimia](https://alquimia.ai) is an **enterprise AI platform** built around a shared execution core. You configure AI agents and knowledge experiences in the product interfaces, and a single backend — the **Runtime** — handles all execution: inference, memory, tool calls, multi-channel delivery, and agent-to-agent orchestration. Your data and agent configuration stay in your infrastructure.
## Products
The backend execution engine. Every inference call, channel message, and agent-to-agent workflow runs through the Runtime.
Build, configure, and deploy AI agents. Studio is the visual interface for creating agents, connecting tools and channels, and monitoring agent health.
Organize documents into topics and explore them through streaming AI conversation. InsightHub is the knowledge exploration front end powered by the Runtime.
## Where to go next
* **[Platform overview](/platform/overview)** — How Studio, InsightHub, and Runtime fit together and depend on each other.
* **[Applications catalog](/platform/applications)** — Status and documentation links for all products.
* **[Studio documentation](/products/studio/index)** — Full Studio manual. Also reachable via the **product switcher** at the top of the page.
* **[InsightHub documentation](/products/insight-hub/index)** — Full InsightHub manual. Also reachable via the product switcher.
# InsightHub
Source: https://docs.alquimia.ai/platform/insight-hub
Turn documents into a conversational knowledge base your team can explore through AI.
InsightHub is a knowledge exploration platform. Users create topics — structured containers for a knowledge domain — upload documents into them, and explore that knowledge through streaming AI conversation grounded in their own content.
It is purpose-built for teams that need to make large or fragmented document collections accessible without building custom search or chatbot infrastructure.
## What you do in InsightHub
* **Create topics** — define a knowledge domain and give it a name and description; topics act as scoped containers that keep exploration answers focused and relevant
* **Upload documents** — add PDFs, Markdown, and plain text files; they are ingested, chunked, embedded, and indexed automatically
* **Explore** — open a conversation against any topic and ask questions in natural language; responses stream in real time and are grounded in the indexed documents
* **Inspect reasoning** — see which document passages were retrieved, what tools were invoked, and how the AI reached its answer before the response completes
* **Use voice** — dictate questions with speech-to-text and hear responses read back with text-to-speech
## Studio + InsightHub
Topics require an agent from the Runtime registry to power their explorations — and that agent comes from Alquimia Studio. Every topic is wired to a registered agent: its model, system prompt, tools, memory, and behavior are all configured there.
This means you get both layers working together: the dynamic document context that InsightHub provides through RAG, and a specialized agent tailored to your domain, tone, and workflow. A customer support agent that knows your product documentation. A research assistant trained to reason like your team. An onboarding bot grounded in your actual processes.
InsightHub handles the knowledge layer, Studio handles the agent layer, and the Runtime executes both together.
## How it connects to the Runtime
InsightHub does not run inference itself. Every exploration message is sent to the Alquimia Runtime, which queries Twyd (the knowledge service) for relevant document chunks, executes any tools the agent needs, and streams the full response — including intermediate reasoning steps — back to the InsightHub interface.
[Open InsightHub documentation](/products/insight-hub/index)
# Overview
Source: https://docs.alquimia.ai/platform/overview
How Studio, InsightHub, and the Runtime fit together.
## What Alquimia is
Alquimia is an enterprise AI platform built around a shared execution backend. The product interfaces — Studio and InsightHub — let teams build agents and explore knowledge. Everything those products do at runtime flows through a single backend: the **Alquimia Runtime**.
Your data and agent configuration stay in your own infrastructure. The platform is built for teams that need AI that is governed, auditable, and deployed on their own terms.
## How the pieces fit
| Component | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Runtime** | The execution engine every product calls. Handles AI inference (REST + SSE streaming), manages the agent registry (models, prompts, tools, secrets, channels), runs connectors for Slack, WhatsApp, and Email, and coordinates agent-to-agent (A2A) calls. |
| **Studio** | The application for building agents. You define agents — model, system prompt, tools, memory, knowledge, and channels — and Studio stores that configuration in the Runtime's registry. Agents live and execute in the Runtime; Studio is where you author and manage them. Agent health dashboards surface telemetry from across the stack via the shared OTel pipeline. |
| **InsightHub** | The knowledge exploration front end. Users create topics, upload documents, and explore them through streaming AI conversation. InsightHub sends every query to the Runtime, which retrieves relevant document chunks (via Twyd), executes any tools, and streams the response back. |
| **Twyd** | The knowledge service. Handles document ingestion, chunking, embedding, and vector search. InsightHub indexes documents through Twyd; the Runtime queries it for RAG retrieval during explorations. |
| **Observability pipeline** | Runtime, Studio, and InsightHub each export logs, traces, and metrics via **OpenTelemetry**. Metrics are scraped by **Prometheus** and surface in Studio's agent health dashboards. Traces and logs are forwarded to any OTLP-compatible backend (Grafana Tempo, Jaeger, etc.). No single product owns the pipeline — each service is an independent exporter. |
## How they connect
```
Studio
│ authors agents → stores config in Runtime Registry
▼
Alquimia Runtime ◀──── Redis · S3 · Vault
▲ agents live and execute here (inference, A2A, connectors)
│
InsightHub
│ sends every chat message to inference API
│
▼
Twyd (document indexing + vector search)
```
* **Studio** is the application for building agents. Every agent you define in Studio is stored in the Runtime's **Registry** and executes in the Runtime.
* **InsightHub** calls the Runtime's **inference API** for every exploration message. The Runtime queries Twyd for relevant document passages and streams the response back to the InsightHub UI.
* **Both products share the same Runtime deployment.** Model credentials, secrets, and workspace configuration set up once in Studio are available to any product calling that Runtime.
## Observability
Runtime, Studio, and InsightHub all instrument their own telemetry using **OpenTelemetry** — logs, traces, and metrics are exported from each service independently to a shared collector in the ecosystem. No single product owns the observability pipeline; each one is an exporter.
Metrics flow through **Prometheus**, which feeds Studio's agent health dashboards — the primary surface for reviewing activity, latency, and usage across agents. Traces and logs are forwarded to any OTLP-compatible backend.
## Authentication
Both Studio and InsightHub support **Keycloak** (enterprise SSO) or a lightweight local credentials mode. The Runtime itself supports API token, JWT, or Keycloak authentication — the product front end handles the user session and passes the appropriate token to the Runtime on each request.
## Related reading
* [Applications catalog](/platform/applications)
* [Runtime](/platform/runtime) — how the execution layer fits the platform (links out to full technical docs)
* [Alquimia Runtime documentation](https://platform-docs.alquimia.ai/) — CLI, SDK, HTTP API, deployment
* [Studio documentation](/products/studio/index)
* [InsightHub documentation](/products/insight-hub/index)
# Runtime
Source: https://docs.alquimia.ai/platform/runtime
Alquimia Core and Alquimia Runtime — SDK, service, and where to read the full technical documentation.
**Alquimia Core** is the SDK and runtime framework for building, configuring, and orchestrating assistants. It includes the inference pipeline (shields, generation, tools, empathy rules, and memory), pluggable model connectors, a unified tool layer across MCP, Llama Stack, built-ins, and agent-to-agent calls, a registry for agent definitions with OCI-style distribution, memory strategies for short- and long-term context, an empathy engine for response profiles, OpenTelemetry instrumentation, and FastAPI-oriented security (JWT and API tokens).
**Alquimia Runtime** is the FastAPI service that runs that stack in production: orchestrating inference, serving the agent registry, wiring multi-channel connectors (Slack, WhatsApp, Email), and coordinating work over a CloudEvents-style event model — with Redis, object storage, and Vault in a typical deployment. Current release line: **0.2.0**, **Python 3.12**, **GPL v3**.
## Documentation
Full guides, HTTP API reference, CLI, configuration, integrations, and deployment.
# Studio
Source: https://docs.alquimia.ai/platform/studio
The visual interface for building, managing, and monitoring AI agents on your own infrastructure.
[Open Studio documentation](/products/studio/index)
Alquimia Studio is the application for creating and operating AI agents. You define each agent's model, system prompt, tools, memory strategy, knowledge base, and integration channels — Studio stores that configuration in the Alquimia Runtime registry, where agents live and execute.
Studio is built for teams that want full control without writing infrastructure code. Business users can configure agents through the UI; operators monitor health and usage through built-in dashboards powered by Prometheus, which collects metrics from across the platform via OpenTelemetry.
## What you do in Studio
* **Build agents** — compose an agent from a model, a system prompt, MCP tools, memory, a knowledge base, and integration channels (Slack, WhatsApp, Email) through a step-by-step interface
* **Manage workspaces** — organize agents into workspaces with their own model registry, MCP servers, embedding models, and secrets
* **Publish and discover** — package workspaces as OCI artifacts and share them through the Discover catalog; install community-published agents into your own environment
* **Monitor** — track agent activity, latency, and usage through Prometheus-backed dashboards; Runtime, Studio, and InsightHub all export metrics via OpenTelemetry to the shared collector
## How it connects to the Runtime
Studio does not execute agents — it authors them. Every agent you save in Studio is written to the Runtime's registry. When a user interacts with an agent (through any channel or integration), the Runtime reads that configuration and handles the full inference lifecycle: pre-processing, retrieval, LLM calls, tool execution, and response delivery.
# RAG
Source: https://docs.alquimia.ai/products/insight-hub/core-concepts/rag
How retrieval-augmented generation works in InsightHub explorations.
**RAG** (Retrieval-Augmented Generation) is the technique that grounds InsightHub's answers in your documents rather than relying on what the language model learned during training.
## How it works
Instead of asking the AI to answer from memory, RAG works like this:
1. Your question is converted into a vector — a numerical representation of its meaning
2. The system searches the topic's indexed documents for passages semantically similar to your question
3. The most relevant passages are included in the AI's context
4. The AI generates its answer using those passages as reference material
The result is an answer drawn from your actual documents, with traceable sources.
## What you see in InsightHub
During an exploration, the **Thinking** indicator shows you:
* **Retrieved passages** — which document chunks were fetched for your query
* **Source attribution** — which document each passage came from
* **Tool steps** — any additional calls the AI made to gather information
This transparency is intentional: you can see where an answer came from and notice when the AI is filling gaps versus citing your documents directly.
## Why document quality matters
Retrieval is only as good as the documents you provide:
| Factor | Impact |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Relevance** | Documents that match the topic's subject produce better results than loosely related files |
| **Text quality** | Clean text extracts more accurately than scanned images or heavily formatted PDFs |
| **Coverage** | If the answer is in a document you haven't uploaded, the AI cannot retrieve it |
If answers are vague or off-target, review the documents in your topic. Add missing files, verify all documents have **Ready** status, and make sure your question falls within the scope of the available content.
## Next steps
Manage the documents that RAG searches during explorations.
See RAG in action during a live conversation.
# Topics and documents
Source: https://docs.alquimia.ai/products/insight-hub/core-concepts/topics-and-documents
How topics and documents work together as InsightHub's core building blocks.
Everything in InsightHub is organized around two building blocks: **topics** and **documents**.
## Topics
A topic represents a knowledge domain — a subject area you want to explore. It is the container for a set of related documents and the entry point for starting explorations.
A well-scoped topic makes exploration answers more precise because the AI searches within a bounded, relevant set of documents. Rather than putting everything into one topic, create separate topics for distinct domains:
* "Product specs — v2.3"
* "Q4 investor materials"
* "Customer onboarding guides"
## Documents
Documents are the source material inside a topic. When you upload a file, InsightHub processes it into a form the AI can work with:
```
Upload
↓
Text extraction
↓
Chunking (split into passages)
↓
Embedding (passages converted to vectors)
↓
Indexed in the vector store
```
When the AI answers a question during an exploration, it searches these indexed passages — not the raw files. The answer is assembled from retrieved chunks, not recalled from general training knowledge.
## How they shape exploration answers
The AI during an exploration only has access to documents within the current topic. This means:
* **Answers are scoped** — the AI answers from your documents, not general knowledge alone
* **Boundaries matter** — if a relevant document is not in the topic, the AI cannot reference it
* **Document quality counts** — clean, on-topic files improve retrieval accuracy
If an exploration answer seems incomplete or off-target, check that the relevant documents are uploaded, fully processed (**Ready** status), and belong to the correct topic.
## Next steps
Understand how the AI retrieves and uses document passages to answer questions.
# First steps
Source: https://docs.alquimia.ai/products/insight-hub/getting-started/first-steps
Log in to InsightHub and create your first topic.
With InsightHub running, open it in your browser:
**[http://localhost:3000](http://localhost:3000)**
## Logging in
InsightHub supports **Keycloak** (enterprise SSO) or **Lite** login (local credentials), depending on how your instance is configured.
Enter your credentials. After logging in, you land on the topics grid.
## The topics grid
The topics grid is your home screen. It shows all topics available to you in the current tenant. On a fresh install it is empty.
## Creating your first topic
Click **New Topic** in the top-right corner of the grid. A dialog opens asking for a name and description.
Give the topic a clear name that reflects its knowledge domain — for example, "Product Documentation" or "Q3 Research Papers".
Click **Create**. The topic appears in the grid.
## Adding documents
Click on your topic to open the topic detail view. From there, you can upload the files that will form the knowledge base for that topic.
Supported formats: PDF, Markdown (`.md`), plain text (`.txt`).
Uploaded files are processed asynchronously. The status updates from **Processing** to **Ready** once indexing is complete.
## Starting your first exploration
Once the topic has at least one document with **Ready** status, click **New Exploration** to open the AI chat interface.
Type a question related to your uploaded content and send it. The AI retrieves relevant passages and responds in real time.
## Next steps
Manage your topics and their settings.
Upload and manage documents within a topic.
# Quick start
Source: https://docs.alquimia.ai/products/insight-hub/getting-started/quick-start
Get InsightHub running locally with or without an external database.
InsightHub is a Next.js application. The fastest way to run it locally is **Lite mode**, which uses a built-in SQLite database and local credentials — no external services required beyond an Alquimia Runtime instance.
## Prerequisites
* **Node.js 20+**
* A running **Alquimia Runtime** instance (its URL becomes `ASSISTANT_BASEURL`)
## Lite mode (no database setup)
Lite mode replaces PostgreSQL with SQLite and Keycloak with local-credentials login. It is designed for development and demos — zero infrastructure besides Node.
```bash theme={null}
npm install
```
```bash theme={null}
cp .env.example .env.local
```
Open `.env.local` and set at minimum:
```bash theme={null}
# Lite database — no PostgreSQL needed
DB_STRATEGY=lite
DATABASE_URL=file:.data/lite.db
# Lite auth — local credentials
AUTH_STRATEGY=lite
AUTH_LITE_USERS='[{"id":"1","name":"Admin","email":"admin@example.com","password":"changeme","role":"admin"}]'
# Alquimia Runtime
ASSISTANT_BASEURL=http://localhost:8080
ALQUIMIA_ASSISTANT_API_KEY=your-api-key
# NextAuth
NEXTAUTH_SECRET=a-random-secret-string
NEXTAUTH_URL=http://localhost:3000
```
```bash theme={null}
npm run dev
```
Open [http://localhost:3000](http://localhost:3000).
The SQLite database and tables are created automatically on first startup. You do not need to run migrations in Lite mode.
## Production setup (PostgreSQL + Keycloak)
For production deployments with a real database and enterprise SSO:
```bash theme={null}
npm install
```
Copy `.env.example` to `.env.local`. Set `DB_STRATEGY=postgres` with a valid `DATABASE_URL`, and `AUTH_STRATEGY=keycloak` with your Keycloak credentials.
```bash theme={null}
npm run db:deploy
```
```bash theme={null}
npm run build && npm run start
```
## Key environment variables
| Variable | Description |
| ---------------------------- | ---------------------------------------------------------------- |
| `DB_STRATEGY` | `postgres` (default) or `lite` (SQLite) |
| `DATABASE_URL` | PostgreSQL connection string, or `file:.data/lite.db` for SQLite |
| `AUTH_STRATEGY` | `keycloak` or `lite` |
| `NEXTAUTH_SECRET` | NextAuth signing secret |
| `NEXTAUTH_URL` | App base URL (e.g. `http://localhost:3000`) |
| `ASSISTANT_BASEURL` | Alquimia Runtime base URL |
| `ALQUIMIA_ASSISTANT_API_KEY` | Alquimia API key |
| `AUTH_LITE_USERS` | JSON array of users *(lite only)* |
| `AUTH_KEYCLOAK_ID` | Keycloak client ID *(keycloak only)* |
| `AUTH_KEYCLOAK_SECRET` | Keycloak client secret *(keycloak only)* |
| `AUTH_KEYCLOAK_ISSUER` | Keycloak issuer URL *(keycloak only)* |
See `.env.example` for the full list, including optional observability variables.
## Docker
If you prefer Docker:
```bash theme={null}
docker build -t insight-hub .
docker run -p 3000:3000 --env-file .env.local insight-hub
```
## Next steps
Log in and create your first topic.
# What is InsightHub
Source: https://docs.alquimia.ai/products/insight-hub/getting-started/what-is-insight-hub
How InsightHub fits into the Alquimia ecosystem and what it does.
InsightHub is the knowledge exploration front end of the Alquimia platform. It is not an observability tool or an agent builder — it is a place to turn documents into a conversational knowledge base that anyone on your team can explore.
## Where InsightHub fits
| Component | What it does |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **InsightHub** | The interface you work in — create topics, upload documents, start explorations. |
| **Alquimia Runtime** | The execution layer behind every conversation — retrieves relevant document passages, runs tools, and streams responses back. |
| **Twyd** | The knowledge service that handles document ingestion, chunking, and vector indexing. |
You do not interact with the Runtime or Twyd directly. InsightHub communicates with them on your behalf. You need a running Alquimia Runtime instance pointed to by `ASSISTANT_BASEURL`.
## How an exploration works
When you send a message in an exploration:
```mermaid theme={null}
flowchart TD
A["Your message"] --> B["Alquimia Runtime receives the query"]
B --> C["Twyd retrieves relevant document chunks (RAG)"]
C --> D["Runtime calls the LLM with retrieved context"]
D --> E["Response streams back to InsightHub"]
E --> F["Retrieval steps and tool calls surface in the UI"]
```
Responses are grounded in your uploaded documents — not generated from scratch. InsightHub shows you which documents were used and what reasoning steps the AI took.
## Multi-tenant and roles
InsightHub supports multiple tenants in a single deployment. Each tenant's topics and documents are scoped and isolated. Within a tenant, access is controlled by roles assigned to users.
If you are deploying InsightHub for your organization, your administrator configures tenants and user roles. You do not need to manage this yourself unless you are the operator.
## Next steps
Get InsightHub running locally.
Understand the core building blocks.
# InsightHub
Source: https://docs.alquimia.ai/products/insight-hub/index
Organize knowledge into topics, upload documents, and explore them through AI-powered conversations.
InsightHub is an AI-powered knowledge exploration platform. You create **topics** — containers for a specific knowledge domain — upload documents into them, and explore that knowledge through a streaming conversational interface backed by the Alquimia Runtime.
## What you can do
* **Create topics** — structured knowledge containers scoped to a subject or project
* **Upload documents** — PDFs, Markdown, and text files are processed and indexed automatically
* **Explore through conversation** — ask questions and get answers grounded in your documents
* **Inspect AI reasoning** — see retrieval steps and tool calls as they happen in real time
* **Use your voice** — speak questions and hear responses with built-in speech-to-text and text-to-speech
## Use cases
Ask questions across your team's internal docs without hunting through folders.
Upload papers and reports, then explore findings through conversation.
Give support teams a grounded AI assistant trained on your product knowledge.
Let reps explore product documentation and competitive intel conversationally.
## Where to start
Get InsightHub running locally in a few minutes.
Understand where InsightHub fits in the Alquimia ecosystem.
# Documents
Source: https://docs.alquimia.ai/products/insight-hub/platform/documents
Upload and manage the documents that form a topic's knowledge base.
Documents are the source material for a topic. When you upload a file, InsightHub sends it for processing: the content is extracted, split into passages, and indexed for semantic retrieval. Once processed, the document is available to the AI during explorations.
## Uploading documents
Open a topic and drag files into the upload area, or click to browse.
**Supported formats:**
* PDF
* Markdown (`.md`)
* Plain text (`.txt`)
Processing happens asynchronously. For large files, it may take a moment before the status updates to **Ready**.
## Document status
| Status | What it means |
| -------------- | --------------------------------------------------------------------------- |
| **Processing** | The file has been received and is being ingested. |
| **Ready** | The document is indexed and available for explorations. |
| **Failed** | Processing encountered an error. Check the file format and try reuploading. |
## Viewing document details
Click on a document to see its metadata: filename, upload date, file size, and processing status.
## Removing a document
To remove a document from a topic, open its menu and select **Delete**. The AI will no longer reference it in new explorations.
Deleting a document is permanent. Existing exploration history that referenced it is preserved, but new explorations will no longer have access to that content.
## Tips for better retrieval
The quality of exploration answers depends directly on the documents you upload:
* **Use clean text** — scanned images in PDFs or heavily formatted layouts extract less accurately than plain text
* **Keep topics focused** — loosely related documents add noise to retrieval results
* **Check status before exploring** — only documents with **Ready** status are searchable
## Next steps
Once your documents are indexed, explore the topic through AI conversation.
# Exploration
Source: https://docs.alquimia.ai/products/insight-hub/platform/exploration
Start an AI conversation grounded in a topic's documents.
An **exploration** is a conversational AI session scoped to a specific topic. You ask questions in natural language and the AI responds with answers grounded in the topic's documents. Every retrieval step and tool call is visible as it happens.
## Starting an exploration
From the topic detail view, click **New Exploration**. You can also open an existing exploration from the explorations list to continue a previous conversation.
The exploration view opens with a chat interface pre-scoped to the current topic.
## Sending a message
Type your question in the input field and press **Enter** (or click **Send**). The AI:
1. Retrieves the most relevant passages from the topic's documents
2. Constructs a response grounded in that content
3. Streams the answer back in real time
## Reasoning steps and tool calls
While a response is streaming, expand the **Thinking** indicator to see what the AI is doing:
* Which document passages were retrieved
* What tools were invoked and what they returned
* The reasoning the AI applied before forming its answer
This gives you full visibility into how the answer was formed — not just the final text output.
The underlying execution is handled by the Alquimia Runtime. InsightHub renders the live event stream from the Runtime, so what you see is exactly what is happening at each step.
## Voice interaction
InsightHub supports voice input and output:
* **Speech to text** — click the microphone icon to dictate your question instead of typing
* **Text to speech** — toggle the speaker icon to have responses read aloud
## Exploration history
Explorations are saved automatically. Return to any topic to see previous explorations listed, and click one to continue the conversation from where you left off. Each exploration maintains its own history independently.
## Next steps
Understand how topics and documents shape what the AI knows.
Learn how retrieval-augmented generation powers exploration answers.
# Topics
Source: https://docs.alquimia.ai/products/insight-hub/platform/topics
Create and manage topics — knowledge containers for your documents and explorations.
A **topic** is a knowledge container. It holds a collection of related documents that you want to explore together through AI conversation. Think of it as a folder with intelligence — you upload your files and ask questions across all of them.
## The topics grid
The grid shows every topic you have access to in the current tenant. Each card displays:
* **Name** and description
* **Document count**
* **Last updated**
Click a topic card to open the topic detail view.
## Creating a topic
Click **New Topic** to open the creation dialog.
| Field | Description |
| --------------- | ------------------------------------------------------------- |
| **Name** | Required. A clear, descriptive name for the knowledge domain. |
| **Description** | Optional. Helps collaborators understand the topic's purpose. |
After creating the topic, you land on the topic detail view where you can start uploading documents.
## Topic detail view
The topic detail view has two main areas:
* **Documents** — upload, view, and manage the files in this topic
* **Explorations** — start or resume AI conversations scoped to this topic
## Defining good topic scope
A well-scoped topic produces better exploration answers because the AI searches within a bounded, relevant set of documents. Instead of uploading everything into one topic, create separate topics for distinct domains:
* "Product specs — v2.3"
* "Q4 investor materials"
* "Customer onboarding guides"
## Filtering and search
The topics grid supports filtering by name to help you find topics quickly across large collections.
## Next steps
Upload and manage the documents inside a topic.
Start an AI conversation grounded in a topic's documents.
# Agents
Source: https://docs.alquimia.ai/products/studio/core-concepts/agents
What an agent is, how it runs, and how to control its reasoning behavior.
An **agent** is a configurable AI assistant. It combines a language model with instructions, optional tools, memory, and knowledge — packaged as a reusable unit that the Alquimia Runtime can execute.
## What makes up an agent
| Component | What it does | Required |
| ------------------------ | ------------------------------------------------------------------- | ------------------------------ |
| **Language model** | The LLM that generates responses | Yes |
| **System prompt** | Identity, personality, rules, and purpose | Yes (auto-generated or custom) |
| **MCP tools** | External services the agent can call | No |
| **Agent-to-Agent** | Other agents the agent can delegate to | No |
| **Memory** | Conversation history (short-term) or persistent context (long-term) | No |
| **Knowledge base** | Document collection for RAG-based answers | No |
| **Integration channels** | WhatsApp, Email — external communication interfaces | No |
| **Pre-processor** | Sentinels and empathy rules that run before the agent | No |
## How agents run
When a user sends a message:
```
User message
↓
Pre-processor (sentinels, empathy rules) — optional
↓
Memory retrieval — inject relevant history
↓
Knowledge retrieval — inject relevant document passages
↓
LLM call — prompt + context + tool schemas
↓
Tool execution (if needed) — ReAct loop
↓
Response returned to user
```
The Runtime handles all of this automatically based on the agent's configuration. You don't write any of this logic — you configure it in Studio.
## Evaluation strategies
The evaluation strategy controls how the agent **thinks**. This is one of the most important settings for an agent.
| Strategy | Description | Best for |
| ----------- | ----------------------------------------------- | ------------------------------------- |
| `off` | Single LLM call, no reasoning loop | Simple Q\&A, content generation |
| `one-shoot` | One call with tool schemas injected | Structured output, simple tool use |
| `tools` | LLM calls tools in a single round | Deterministic, tool-first workflows |
| `react` | ReAct loop: reason → act → observe → repeat | Multi-step tool use, complex tasks |
| `long-task` | Extended planning for complex, multi-step tasks | Research agents, autonomous workflows |
When you add MCP servers or other agents to your agent, Studio automatically switches the evaluation strategy to `react`. This ensures the agent can actually use its tools. You can override this manually in [Dev Mode](/platform/agent-creation/dev-mode).
### The ReAct loop explained
`react` is the most powerful strategy. The agent follows this cycle:
1. **Reason** — "I need to look up the user's account to answer this"
2. **Act** — calls the `get_account` tool from an MCP server
3. **Observe** — receives the tool result
4. **Reason again** — "Now I have the account info, I can answer"
5. **Respond** — generates the final answer
This continues until the agent has enough information to respond or hits its reasoning limit.
## Next steps
Step-by-step walkthrough of the agent creation wizard.
Take full control of the system prompt and evaluation strategy.
# Secrets
Source: https://docs.alquimia.ai/products/studio/core-concepts/secrets
How Studio stores and reuses sensitive credentials securely across agents.
Secrets are named handles for sensitive values — API keys, passwords, tokens — that agents and settings need at runtime. **The actual material lives in a secret vault**, not inline in your agent or settings documents. The registry saves values to the vault and only keeps **references** (names) in configuration.
## Why secrets matter
Without secrets, every agent that uses Anthropic's API would need a copy of your API key in its configuration. If the key changes, you'd update every agent individually.
With secrets:
1. `ANTHROPIC_API_KEY` is stored **once** in the secret vault
2. Every agent that needs it references `$ANTHROPIC_API_KEY`
3. If the key rotates, update the secret — all agents pick up the new value automatically
## The `$secretRef` pattern
When you see a value like `$ANTHROPIC_API_KEY` in a field that normally holds a credential, that's a secret reference. The `$` prefix tells the Runtime to resolve the value from the **secret vault** at execution time.
The raw secret is **not kept inside agent configuration**. It isn't written to logs and isn't shown in the Studio UI after you save; only the vault holds the sensitive payload.
## How secrets are created
### Automatically (recommended)
When you add a model in **Settings → Models Registry** and enter an API key, Studio automatically:
1. Writes the key into the secret vault under a name (e.g., `ANTHROPIC_API_KEY`)
2. Replaces the raw key in the model config with `$ANTHROPIC_API_KEY`
### Manually
You can manage secrets directly from the Settings → Models Registry page. Edit a model and enter a new API key to rotate the secret.
## Reusing secrets
Secrets are reusable across all configurations in a workspace:
* **Models** — API keys for LLM providers
* **MCP Servers** — credentials for authenticated MCP endpoints
* **Integration Channels** — WhatsApp access tokens, SMTP passwords
When a field in a modal shows a placeholder like `"Leave blank to keep existing value"`, it means the field already holds a secret reference. You only need to enter a value if you want to **replace** it.
When configuring WhatsApp or Email integration channels, you'll notice credential fields don't show the stored value — only a `$secretRef` placeholder. This is intentional: credentials are write-only after they're saved.
## Secret scope
Secrets are scoped to a workspace. A secret created in one workspace is not available in another.
## Next steps
See how API keys become secrets when you add a model.
Configure WhatsApp and Email with secret-backed credentials.
# Workspaces
Source: https://docs.alquimia.ai/products/studio/core-concepts/workspaces
Isolated environments for organizing agents, settings, and configurations by team or use case.
A **workspace** is an isolated container for everything in Studio: agents, models, MCP servers, embeddings, and sentinels. Think of it as a project or environment.
## Why workspaces exist
Different teams, clients, or use cases need separate configurations. A customer support team and a finance team shouldn't share the same agents, models, or API keys. Workspaces enforce this separation cleanly.
## Switching workspaces
Use the **workspace switcher** at the top of the sidebar to switch between workspaces.
Everything you see in Studio — agents, settings, the Discover feed — is scoped to the active workspace. Switching workspaces is like switching projects.
When you switch workspaces, the models, MCP servers, embeddings, and sentinels you see all change. Each workspace starts with its own empty settings configuration.
## OCI addressing
Workspaces use OCI (Open Container Initiative) addressing — the same convention used by container registries like Docker Hub.
Each workspace has:
* **Namespace** — your organization scope (e.g., `alquimia`, set by `NEXT_PUBLIC_DEFAULT_NAMESPACE`)
* **Name** — workspace identifier (e.g., `customer-support`)
* **Full address** — `namespace/name` (e.g., `alquimia/customer-support`)
This addressing enables the [Discover & Publish](/platform/discover) feature — workspaces can be published to an OCI registry and installed by others, just like container images.
## Workspace naming rules
Workspace names are sanitized to OCI format automatically:
* Lowercase only
* Letters, numbers, hyphens, dots, and underscores allowed
* Spaces become hyphens
The display name is restored to title case in the UI. The raw name stored in the registry is always OCI-compliant.
## Roles within a workspace
Access to a workspace is controlled by your RBAC role. If your deployment uses Keycloak, roles are assigned there. See [Roles & Permissions](/reference/roles-and-permissions) for the full breakdown.
## Next steps
Publish your workspace or install from the community catalog.
Control who can access and modify your workspaces.
# Ecosystem Overview
Source: https://docs.alquimia.ai/products/studio/getting-started/ecosystem-overview
All the services that make up the Alquimia stack, their ports, and what they do.
The Alquimia stack is a set of services that work together. When you run `docker compose up`, all of these start automatically. You only need to interact with Studio and occasionally the others when debugging.
## Services at a glance
| Service | Default URL | Description |
| --------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Runtime** | [http://localhost:8080](http://localhost:8080) | Event-driven agent execution platform. Orchestrates multi-agent LLM runs in containerized environments, including context-aware prompting, memory strategies, RAG-aware retrieval flows, and complex tool execution. Designed for Kubernetes and OpenShift. Visit `/docs` for the Swagger API. |
| **Twyd** | [http://localhost:8000](http://localhost:8000) | Knowledge base service. Manages topics, file ingestion, and vector search for RAG. |
| **Studio** | [http://localhost:3001](http://localhost:3001) | This app — the visual agent builder. Login via Keycloak or Lite. **Observability:** agent metrics dashboards here, on OpenTelemetry standards, backed by **Prometheus** metrics. |
| **Insight Hub** | [http://localhost:3000](http://localhost:3000) | Knowledge exploration — Topics, documents, and streaming AI chat (separate from agent observability). |
| **MinIO** | [http://localhost:19001](http://localhost:19001) | S3-compatible object storage for files and documents. Console at port 19001. |
| **Qdrant** | [http://localhost:6333](http://localhost:6333) | Vector database for **Knowledge Base** semantic search and related runtime retrieval (e.g. summarized context when using strategies that persist to collections). |
| **Postgres** | internal | Relational database used by Twyd and Insight Hub. |
| **Redis** | internal | Cache and message queue used by the Runtime. |
| **MongoDB** | localhost:27017 | Studio's database. Stores models, MCP servers, embeddings configurations, and settings. |
You don't need to interact with most of these services directly. Studio orchestrates everything through the Registry API. Use **Studio** for building agents and for **metrics dashboards**; open **Insight Hub** (3000) when you want topic-based knowledge exploration and chat.
## Port configuration
All ports are configurable via environment variables in your `.env` file before running `docker compose up`.
| Variable | Default | Service |
| ----------------------- | ------- | ----------------------------- |
| `RUNTIME_HOST_PORT` | 8080 | Runtime |
| `STUDIO_HOST_PORT` | 3001 | Studio |
| `INSIGHT_HUB_HOST_PORT` | 3000 | Insight Hub |
| `OLLAMA_HOST_PORT` | 11434 | Ollama (local models profile) |
## Data storage
The stack persists data in Docker volumes:
* **MongoDB** — Studio's settings (models, MCP, embeddings)
* **Postgres** — Twyd and Insight Hub application data (topics, documents, tenants, chat-related persistence)
* **Qdrant** — Vector storage/search for knowledge base and workloads that use embeddings-backed retrieval
* **MinIO** — Uploaded documents and files
Running `docker compose down -v` removes all volumes and **deletes all persisted data**, including your agents, settings, and knowledge base. Use `docker compose down` (without `-v`) to stop services while keeping data.
## Next steps
Get the full stack running with a single command.
# First Login
Source: https://docs.alquimia.ai/products/studio/getting-started/first-login
Log in to Alquimia Studio for the first time and get oriented.
With the stack running, open Studio in your browser:
**[http://localhost:3001](http://localhost:3001)**
## Logging in
Studio supports **Keycloak** (enterprise SSO) or **Lite** login (local credentials), depending on how your stack is configured.
Enter the credentials configured in your `.env` file (the defaults are in `.env.example`). After logging in, you'll land on the Studio dashboard.
## The onboarding tour
On your first visit, Studio starts an onboarding tour automatically. It highlights the key areas of the app:
1. **Dashboard** — your agent feed
2. **Settings** — where you configure models, MCP servers, and more
3. **Discover** — the community agent catalog
You can dismiss the tour at any time and restart it from the sidebar if needed.
## Before creating your first agent
The **Create Agent** button in the sidebar is **disabled until at least one model is configured**. Go to Settings → Models Registry and add a model first.
If the models list is empty, [add a model in Settings](/platform/settings/models) before creating an agent.
## The sidebar
The sidebar is your main navigation:
* **Dashboard** — view and manage your agents
* **Create Agent** — open the agent creation wizard (disabled without a model)
* **Discover** — browse and install community agents
* **Settings** — models, MCP servers, embeddings, sentinels
* **Workspace switcher** (top of sidebar) — switch between workspaces
## Next steps
Configure the building blocks before creating your first agent.
Walk through the agent creation wizard.
# Installation
Source: https://docs.alquimia.ai/products/studio/getting-started/installation
Get the full Alquimia stack running locally with Docker Compose.
The Alquimia stack runs entirely via Docker Compose. No local builds, no dependency management — just pull and run.
## Prerequisites
* **Docker Desktop** (v24+) or Docker Engine + Docker Compose v2
* **Git**
* **8 GB RAM** minimum (16 GB recommended if using local models with Ollama)
## Quick start
```bash theme={null}
git clone https://github.com/alquimia-ai/alquimia-local.git
cd alquimia-local
cp .env.example .env
docker compose up -d
```
Studio is now running at **[http://localhost:3001](http://localhost:3001)**.
On first startup, give the stack **30–60 seconds** to finish bootstrapping before logging in.
## Cloud and custom models
**Studio is where you register cloud LLMs** (Anthropic, OpenAI, Groq, etc.): open **Settings → Models Registry**, add each model, and paste the API key—credentials are stored as [secrets](/core-concepts/secrets). Use **Base URL** when you point at OpenAI-compatible gateways, proxies, or self-hosted endpoints; you are not limited to a fixed list baked into `.env`.
(The optional Ollama workflow below still uses Compose for local pull-and-register—see [Local models with Ollama](#local-models-with-ollama).)
## Local models with Ollama
The stack includes optional Ollama support for running inference locally (CPU-based):
```bash theme={null}
# Add to .env before starting
OLLAMA_MODELS=qwen2.5:0.5b nomic-embed-text
# Start with the local models profile
docker compose --profile with-local-models up -d
```
Naming convention for `OLLAMA_MODELS`:
* Models with **`embed`** in the name → registered as **Embeddings Models** in Studio
* All others → registered as **chat models**
Ollama runs on CPU inside Docker. Models larger than 3B parameters require significant RAM. Recommended: use 0.5B–3B models for local development.
### Adding Ollama models without restarting
```bash theme={null}
# Pull a new model into the running Ollama container
docker compose exec ollama ollama pull llama3.2:3b
# Re-run studio-init to register it in Studio
docker compose --profile with-local-models run --rm studio-init
```
## Useful commands
```bash theme={null}
# View logs for all services
docker compose logs -f
# View logs for a specific service
docker compose logs -f studio
# Stop all services (data is preserved)
docker compose down
# Stop and delete all data (volumes)
docker compose down -v
# Restart a single service
docker compose restart studio
```
## Next steps
Log in to Studio and take the onboarding tour.
# What is Alquimia
Source: https://docs.alquimia.ai/products/studio/getting-started/what-is-alquimia
Understand the Alquimia ecosystem and how Studio fits into it.
Alquimia is a complete AI runtime ecosystem for building and running enterprise-ready AI agents with a focus on transparency, consistency, and flexibility. **Studio** is the visual interface where you configure agents. The **Runtime** is where they actually run. These two work together — you don't need to know about the others to build agents, but understanding the big picture helps.
## The ecosystem at a glance
| Component | Role |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Studio** | Agent builder — this app. Design, configure, and manage agents. View agent metrics and health here: dashboards are fed by metrics and follow **OpenTelemetry** conventions. |
| **Runtime** | Event-driven execution platform for agents in containerized environments. Orchestrates multi-agent runs, context-aware prompting, memory strategies, and complex tool execution. Built on Knative for Kubernetes and designed for OpenShift deployments. |
| **Twyd** | Knowledge base service. Handles document ingestion, topic management, and vector search. |
| **Insight Hub** | AI-powered knowledge exploration — **Topics**, document upload, and streaming chat over the runtime (not an observability product). |
## The agent lifecycle
When you build an agent in Studio, here's what happens end-to-end:
```
Studio → Registry API → Runtime
(you configure) (config stored) (agent executes)
```
**Observability** stays on OpenTelemetry-style traces, metrics, and logs. **Prometheus** metrics feed the **agent metrics dashboards in Alquimia Studio** — that is where you review agent health and usage, not in Insight Hub.
1. You configure an agent in Studio (model, system prompt, tools, memory, etc.)
2. Studio saves the configuration to the **Registry API** — the central store for all agent configs
3. When a user sends a message, the Runtime fetches the agent config from the Registry
4. The Runtime executes the agent: constructs the prompt, calls the LLM, runs tools if needed, applies memory
5. Telemetry from the run is available through the observability pipeline above; use Studio’s dashboards to dig into metrics tied to your agents
## How Studio fits in
Think of **Studio** as where you design and operate agents, and the **Runtime** as where they come to life. Both are part of the same product story—you stay in Studio for the full workflow; the Runtime is the engine behind it.
**Studio** is your home for:
* **Designing agents** — everything you set in the UI becomes runtime-ready configuration in the Registry (model, prompts, tools, memory, channels, and more).
* **Workspace operations** — models, MCP servers, embeddings, sentinels, and workspace boundaries, in one place.
* **Observability** — metrics and health for your agents, surfaced in Studio’s dashboards.
**The Runtime** carries the load for a live conversation: it loads config from the Registry, calls the LLM, runs tools and memory, and streams replies. When you use **Try Me**, Studio is your console—the chat itself is powered by the Runtime, so what you see is what end users get under the same stack.
You rarely need to call the Runtime, Registry, or Twyd APIs by hand; Studio talks to them for you. When something misbehaves, it helps to know which layer owns what so you know where to look next.
## Next steps
See every service, its port, and what it does.
Get the stack running locally with Docker Compose.
# Alquimia Studio
Source: https://docs.alquimia.ai/products/studio/index
Enterprise-ready AI agent builder. Build, configure, and deploy production AI agents on your own infrastructure.
Alquimia Studio is a no-code/low-code platform for building, configuring, and deploying enterprise AI agents on your own infrastructure. Whether you're a business user with no ML background or a developer who wants full control, Studio gets you from idea to production agent without friction.
## What you can build
* **Conversational assistants** — customer support, internal helpdesk, onboarding bots
* **Multi-agent setups** — connect your agent to other agents when you need specialized capabilities
* **RAG-powered knowledge bots** — agents that answer questions from your documents
* **Tool-augmented agents** — agents connected to external APIs, databases, and services via MCP
* **Channel-connected agents** — agents that receive and respond via WhatsApp, Email or Slack
## Why Alquimia
Self-hosted. Your data never leaves your environment. Deploy on any server, cloud, or on-premise setup.
Built-in authentication (Keycloak or Lite login), role-based access control, full observability on OpenTelemetry standards with agent metrics dashboards inside Studio, and safety guardrails via Sentinels.
Assistants can work together out of the box: when a job suits another agent better, they hand it off directly—no extra coordinator in the middle.
MCP (Model Context Protocol) for tool integration, OCI-based workspace publishing, and OpenAI-compatible model APIs.
## Where to start
Get the full Alquimia stack running locally in minutes with Docker Compose.
Understand how Studio fits into the broader Alquimia ecosystem.
# Agent-to-Agent
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/agent-to-agent
Let this agent reach other agents in the same workspace when the task fits—no coordinator layer, peers calling peers.
Agent-to-Agent (A2A) links the current agent agent to other agents in the same workspace. At runtime the model may **invoke another agent** the same way it can invoke an MCP tool—because those peers are exposed as callable capabilities.
## Use cases
**Shared workspace, different expertise**\
One agent handles the thread until the user’s goal clearly matches another agent’s description—for example billing vs. technical support—then **hands off** by calling that peer.
**Splitting concerns**\
Agents stay small and focused. Several agents can each link to the others they need, symmetrically, instead of a single “top” controller.
**Intent-based routing**\
An intake-style agent classifies what the user wants and **calls** the workspace agent whose description best matches—without a separate orchestration service.
## Selecting agents
Choose from other agents in the current workspace. You can add multiple.
Adding agents here automatically switches the **evaluation strategy to `react`** — the same as adding MCP tools. Other agents are surfaced as callable actions inside that reasoning loop; that is wiring, not a parent/child relationship between agents.
## What the model sees for each linked agent
Each linked agent is presented to **this** agent as a callable capability with:
* **Name** — slug-style identifier the model uses when calling it
* **Description** — taken from the agent’s **Profile**
Clear **descriptions** matter: they tell the model **when** calling that peer is appropriate.
**Good description**: *"Handles billing inquiries including invoice questions, payment failures, subscription changes, and refund requests. Use when users ask about charges, payments, or their subscription."*
**Vague description**: *"Billing agent."*
## Mixing MCP tools and agents
You can combine MCP tools and other agents on the same agent. The model chooses among those capabilities from the same loop—**tools and peer agents are options**, not tiers of control.
## Next steps
Add external tool integrations alongside agent calls.
Write agent descriptions that make peer calls easy to choose correctly.
# Dev Mode
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/dev-mode
Advanced editing for custom clauses (dynamic fields or raw JSON), manual system prompt, and evaluation strategy.
Dev Mode is for operators who need full control over **Custom Rules** (custom clauses), the **system prompt**, and **evaluation strategy** without the normal guardrails.
Turn **Dev Mode (advanced)** on with the switch in the **Custom Rules** header. That single flag unlocks advanced clause editing and, farther down the Profile section, the **evaluation strategy** selector and **system prompt** controls that are hidden in standard mode.
## Custom clauses: Dynamic Fields vs Raw JSON
With Dev Mode on, **Custom Rules** no longer use the compact default form. Instead you choose an **Editing mode**:
| Mode | What you do |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dynamic Fields** | Every clause is its own **large text field**. You can **edit any value**, **remove a field** (including standard ones you do not need), and use **Add custom field** to create **new clause keys** beyond identity, personality, purpose, etc. |
| **Raw JSON** | Edit the entire `custom_clauses` map as **JSON** in the code editor (valid object of string values). Use this for bulk copy/paste, merges, or scripted content. |
In both modes the clauses object is **fully yours**: nothing is read-only, and fields you do not want can be **deleted** (Dynamic: per-field delete; Raw: remove keys from the JSON).
**Standard mode** only supports the usual fixed clause keys. Dev Mode is what makes **arbitrary keys** and **removals** possible.
## Manual system prompt
With Dev Mode enabled, the **System Prompt** block appears. Turn on **Manage system prompt manually** to write the prompt yourself in the textarea instead of using auto-generated text from the clauses.
You can still insert `{{identity}}`, `{{personality}}`, etc. from the tag helper so the manual prompt **pulls live values** from whatever keys exist in Custom Rules (including custom keys you added in Dynamic Fields or Raw JSON).
## System prompt variables
| Variable | Typical source clause |
| --------------------- | --------------------- |
| `{{identity}}` | `identity` |
| `{{personality}}` | `personality` |
| `{{purpose}}` | `purpose` |
| `{{knowledge}}` | `knowledge` |
| `{{rules}}` | `rules` |
| `{{response_format}}` | `response_format` |
If you add custom clause keys, reference them in the manual prompt with the same `{{key}}` pattern.
Example:
```
You are {{identity}}.
Tone: {{personality}}
Your primary objective: {{purpose}}
Domain knowledge:
{{knowledge}}
Operating rules:
{{rules}}
Output format:
{{response_format}}
```
This pattern works well for Claude-style models with clear XML sections. You keep clause content in **Dynamic Fields** or **Raw JSON**, and structure the prompt manually above.
## Evaluation strategy override
With Dev Mode on, Studio **stops auto-forcing** `react` when you add MCP servers or Agent-to-Agent links. You set **evaluation strategy** explicitly and it stays where you put it until you change it.
## Leaving Dev Mode
**Disabling Dev Mode** returns Custom Rules to the **standard form**. If you added **extra clause keys** (not in the default set), Studio warns you that those fields will be **dropped** when you confirm; only the default clause keys are kept, with your values merged in. If you need that data, **copy Raw JSON** before switching off.
Turning Dev Mode off also **replaces a fully manual system prompt** with the **auto-generated** prompt from your clauses unless you have handled that separately — **copy anything you must keep** before toggling.
## When to use Dev Mode
* You need **custom clause keys** or want to **remove** standard clauses you do not use.
* You want **full JSON** control over clauses for migrations or diffs.
* You need a **fixed evaluation strategy** that must not be overridden by tool/A2A autoswitching.
* You are **authoring the system prompt by hand** and still want clause variables injected.
## Next steps
Review the full wizard overview and what’s available in each step.
# Integration Channels
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/integration-channels
Connect the agent to external communication platforms like WhatsApp and Email.
Integration Channels let your agent send and receive messages through external platforms — beyond the Studio test interface and direct API calls.
## WhatsApp
Connects via the **WhatsApp Business API** (Meta Cloud API or on-premise).
| Field | Description |
| ------------------- | ---------------------------------------------------------------------------------- |
| **API Base URL** | Your WhatsApp Business API endpoint (e.g., `https://graph.facebook.com/v18.0`) |
| **Access Token** | Meta API token with `whatsapp_business_messaging` permissions. Stored as a secret. |
| **Phone Number ID** | The numeric ID of the phone number linked to your WhatsApp Business account |
## Email
Connects via **SMTP** for outbound email delivery.
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------- |
| **Username** | SMTP authentication username. Stored as a secret. |
| **Password** | SMTP authentication password. Stored as a secret. |
| **Server** | SMTP hostname (e.g., `smtp.gmail.com`, `smtp.sendgrid.net`) |
| **Port** | SMTP port (typically `587` for TLS, `465` for SSL, `25` for plain) |
| **SSL** | Enable TLS/SSL encryption |
| **Response Template** | Jinja2 HTML template for outgoing emails. Use `{{ response }}` to inject the agent's reply. |
### Email template example
```html theme={null}
Hello,
{{ response }}
Best regards,
Acme Support
```
## Credential handling
All credential fields in integration channels are write-only after saving. The stored value is replaced with a `$secretRef`. This means:
* The field will appear **empty** when you edit the channel
* **Leave it blank** to keep the existing secret
* **Enter a new value** only if you want to replace the credential
If you edit an integration channel and accidentally enter an empty value in a credential field, the existing secret will be cleared. Always leave credential fields blank when editing unless you intend to rotate them.
## Next steps
Understand how credentials are stored and referenced securely.
# Knowledge Base
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/knowledge-base
Connect your agent to documents so it can answer questions using your content.
The Knowledge Base gives your agent access to a collection of documents. When a user asks a question, the agent retrieves the most relevant passages and uses them to construct an accurate, grounded answer. This technique is called **RAG** — Retrieval-Augmented Generation.
## Prerequisites
None — embeddings are handled automatically by the Alquimia runtime. Just open the Knowledge Base step and start uploading.
## Uploading documents
Drag and drop files into the upload area or click to browse. Uploaded documents are:
1. Processed and chunked into passages
2. Embedded by the runtime engine
3. Stored in the vector database (Qdrant)
## Retrieval parameters
These parameters control how the agent searches your documents when answering a question.
### Search type
| Type | Description | Best for |
| ------------ | -------------------------------------------------------------- | --------------------------------------------- |
| `similarity` | Pure semantic similarity — finds the most relevant chunks | Specific, focused questions |
| `mmr` | Maximal Marginal Relevance — balances relevance with diversity | Broad questions, avoiding repetitive passages |
### Parameters
| Parameter | Default | Description |
| ------------------- | ------- | ------------------------------------------------------------------- |
| **K** | 4 | Number of document chunks retrieved per query |
| **Score Threshold** | none | Minimum similarity score (0.0–1.0). Chunks below this are excluded. |
| **Fetch K** | — | MMR only: candidates to evaluate before selecting the final K |
| **Lambda Mult** | — | MMR only: diversity weight (0 = max diversity, 1 = max relevance) |
Start with `similarity`, K=4, and no threshold. Run a few test queries in the Test Drawer. If answers are repetitive, switch to `mmr`. If answers include irrelevant content, add a score threshold (try 0.7 first).
## How retrieval works at runtime
When the agent receives a message:
1. The query is embedded by the runtime using the same model that indexed the documents
2. The vector database finds the K most similar document chunks
3. Those chunks are injected into the agent's prompt as context
4. The LLM uses this context to generate a grounded answer
The agent cites information from your documents rather than relying solely on what the LLM learned during training.
## Next steps
Add conversation memory alongside document retrieval.
Choose the LLM that generates grounded answers from retrieved context.
# MCP Tools
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/mcp-tools
Connect the agent to external services it can call during a conversation.
**MCP Tools** assigns external tool servers to the agent. When configured, the agent can call these tools during a conversation to fetch data, take actions, or interact with external systems.
## Selecting MCP servers
Choose from the list of servers registered in [Settings → MCP Servers](/platform/settings/mcp-servers). You can assign multiple servers to a single agent.
Each selected server exposes its full set of tools to the agent at runtime.
Adding MCP servers automatically switches the **evaluation strategy to `react`**. This is required — `react` is the strategy that enables the tool-use loop where the agent reasons, calls tools, observes results, and repeats. You can override this in [Dev Mode](/platform/agent-creation/dev-mode).
## How tool use works at runtime
When the agent receives a message:
1. The Runtime fetches tool schemas from all assigned MCP servers
2. These schemas (tool names, descriptions, input parameters) are injected into the LLM prompt
3. If the LLM decides to call a tool, the Runtime executes it and returns the result
4. The LLM incorporates the result and continues reasoning
5. This loop repeats until the agent has enough information to respond
## Writing good tool descriptions
The agent decides **which tool to call and when** based on tool names and descriptions. If a tool description is vague, the agent may misuse it or ignore it entirely.
Good tool description: *"Retrieves a customer's order history. Input: customer\_id (string). Returns: list of orders with status, date, and amount."*
Bad tool description: *"Gets orders."*
Tool descriptions are set in the MCP server itself, not in Studio.
## Next steps
Delegate tasks to other agents instead of tools.
Override the evaluation strategy or customize how tools are presented in the prompt.
# Memory
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/memory
Give the agent memory across a conversation or across multiple sessions.
Memory lets the agent maintain context beyond the current message — either within a single conversation or across multiple sessions over time.
## Memory strategies
### None (default)
No memory. Each message is treated as an independent, stateless interaction. The agent has no awareness of previous turns.
**Best for**: Single-turn tasks, lookup agents, classification agents, any use case where conversation history doesn't matter.
***
### Short-term memory
The agent remembers the current conversation session. Previous messages in the same session are injected into the prompt context.
| Parameter | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Max Tokens** | Maximum token budget for injected history. Older messages are dropped when the budget is exceeded. |
| **Metadata Filter** | Optional filter to scope memory retrieval by session metadata (e.g., only recall messages tagged with a specific topic) |
**Best for**: Customer support conversations, multi-turn Q\&A, any interaction where the agent needs to remember what was said earlier in the same session.
***
### Long-term memory
The agent persists context **across sessions** using one of two runtime strategies — **Neuralyzer** or **CoD Summarizer** (`cod-summarizer`). These are summarization / compression pipelines managed by the platform.
Choose **Memory Strategy**:
| Strategy | What it does |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Neuralyzer** | Continuously **summarizes and compresses** conversation history so older turns collapse into durable context instead of growing without bound. |
| **CoD Summarizer** | **Chain-of-Density** summarization: builds compact summaries and can **store them in a knowledge-base collection** you name (see **Collection ID** below). |
**Shared parameters** (both strategies):
| Parameter | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Interaction Threshold (Qty)** | Number of interactions before a summarize step runs. Use **-1** for no limit (always follow runtime defaults). |
| **Interaction Threshold (Tokens)** | Token budget threshold before summarizing. Use **-1** for unlimited. |
| **Interaction Keep** | How many **recent** interactions to leave **unsummarized**. `0` means everything eligible can roll into summarized form. |
**CoD Summarizer only**:
| Parameter | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Collection ID** | Knowledge-base collection where summaries are written (must match how your runtime/knowledge stack expects storage). |
| **CoD Max Loops** | Maximum refinement loops for the Chain-of-Density pass (default in UI: `5`). |
**Best for**: Assistants that should remember a user or account across returning sessions, without relying on raw transcript replay alone.
Long-term behavior is **strategy-driven** (Neuralyzer vs. CoD Summarizer), not “pick Top K / similarity on an embeddings index” in Studio. If you need retrieval over **uploaded documents**, that is [Knowledge Base](/platform/agent-creation/knowledge-base) + [Embeddings](/platform/settings/embeddings).
## Combining memory with knowledge base
Short- or long-term memory and **Knowledge Base** (RAG over documents) can be active together: the agent can combine **conversation-side context** with **document embeddings** in the same reply. CoD Summarizer in particular may **write** summaries into a collection that participates in your knowledge stack; that is separate from configuring an embeddings model *for* long-term memory in the Memory UI.
## Next steps
Access advanced controls for the system prompt and agent configuration.
# Inference
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/model-selection
Select the model connection that powers the agent and configure its runtime parameters.
**Inference** selects which model connection the agent uses and lets you fine-tune its behavior with model parameters.
## Model connection
The **Model connection** dropdown lists all connections registered in [Settings → Model Connections](/platform/settings/models). Select the one this agent should use — credentials are inherited from the connection; you do not re-enter API keys here.
Each option shows the connection name, type, and model ID (e.g., **GPT-4o Production — OpenAI** with `gpt-4o` below).
Different agents in the same workspace can use different connections. Common patterns:
* Use a powerful model (e.g., Claude Sonnet, GPT-4o) for complex reasoning agents
* Use a fast, cheap model (e.g., Groq Llama, Claude Haiku) for simple classification or routing agents
* Use a custom endpoint for local development and testing
If the dropdown is empty, no model connections have been configured yet. Go to [Settings → Model Connections](/platform/settings/models) and add at least one.
## Model parameters
Model parameters are optional key-value pairs passed to the LLM at inference time. They let you tune the model's behavior per-agent without changing the connection itself.
Common parameters:
| Parameter | Type | Description |
| ------------------- | --------------- | ---------------------------------------------------------------------------- |
| `temperature` | float (0.0–2.0) | Creativity vs. determinism. `0` = highly deterministic, `1+` = more creative |
| `max_tokens` | integer | Maximum number of tokens in the response |
| `top_p` | float (0.0–1.0) | Nucleus sampling. Alternative to temperature for controlling randomness |
| `top_k` | integer | Limits sampling to the top K most likely tokens |
| `frequency_penalty` | float | Reduces repetition of frequently used words |
| `presence_penalty` | float | Encourages the model to introduce new topics |
Supported parameters vary by connection type. Unsupported parameters are silently ignored by the runtime. Refer to your provider's API documentation for the full list.
## Next steps
With a model connection selected, your agent is ready to run. From here you can optionally add:
Connect external tools and APIs.
Add document retrieval for RAG-based answers.
# Creating an Agent
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/overview
Walk through the agent creation wizard and understand what each step configures.
Click **Create Agent** in the sidebar to open the wizard. If the button is disabled, you need to [add a model to Settings](/platform/settings/models) first.
## Baseline vs. a strong agent
To **create and save** an agent in Studio you must set at least a **name** (Profile), a description and most importantly choose a **model** (Inference). That is enough for the app to store a valid configuration — think of it as the technical floor, not the goal.
For an agent that will hold up in production, treat the rest of the wizard as **expected work**, not extras: a clear **profile** (purpose, behavior, evaluation strategy, system prompt), **knowledge** (RAG) when answers must be grounded, **MCP tools** when the agent must act on systems, **memory** when conversations need continuity, **channels** when users reach you outside Studio, and **pre-processors / sentinels** when safety or policy matters. Start with name + model if you need to move fast, then fill these in before you call the agent done.
## Wizard steps
| Step | What it configures | When you need it |
| ------------------------ | --------------------------------------------------------- | ----------------------------------------------- |
| **Profile** | Identity, personality, evaluation strategy, system prompt | Always |
| **Inference** | Which LLM powers the agent | Always |
| **MCP Servers** | External tools the agent can call | When you want tool use |
| **Agent-to-Agent** | Other agents this agent can call in the workspace | When you want peer agents available to this one |
| **Knowledge** | Document retrieval (RAG) | When agents should answer from documents |
| **Integration Channels** | WhatsApp, Email delivery | When agents should send/receive outside Studio |
| **Pre-processor** | Sentinels and empathy rules | When you need safety or input filtering |
| **Memory** | Short-term or long-term conversation memory | When context persistence matters |
## Test at any time
The **Try Me** button in the top-right corner opens the Test Drawer at any point during configuration. You can test the agent with its current settings by saving first.
## Editing existing agents
Editing an existing agent from the Dashboard opens the same wizard, pre-populated with the agent's current configuration. Changes are saved in real time.
## Next steps
Start with the most important steps:
Define the agent's identity, personality, and reasoning strategy.
Select the model that powers the agent.
# Pre-processor
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/pre-processor
Filter, classify, and transform user requests before they reach the main agent.
The Pre-processor runs before the main agent sees a user message. Use it to enforce safety policies, classify intent, or apply deterministic rules — without changing the main agent's logic.
## Sentinels
Sentinels are mini-agents that evaluate the incoming message using an LLM. They can block, tag, or transform the request based on their classification.
Select one or more Sentinels from those configured in [Settings → Sentinels](/platform/settings/sentinels).
**Execution order**: Sentinels run sequentially in the order they're listed. If a sentinel **blocks** a request, subsequent sentinels and the main agent are skipped. The blocking sentinel's configured response is returned to the user.
Common sentinel use cases:
* Block off-topic or harmful inputs before they reach the agent
* Classify intent and tag the request for downstream logic
* Detect language and route accordingly
## Empathy Rules
Empathy Rules are condition-based rules that run **without an LLM call** — they're evaluated deterministically based on patterns, keywords, or metadata. Much faster and cheaper than sentinels.
Each rule consists of:
* **Condition** — what to match (keyword in message, metadata value, user attribute)
* **Action** — what to do (respond with a fixed message, tag the request, escalate)
Example rules:
* IF message contains "cancel my account" → respond with "Please contact our retention team at..."
* IF message contains profanity → block with "Please keep the conversation respectful"
* IF user\_language = "es" → tag as `spanish` and forward
Use **Empathy Rules** for simple, predictable patterns you can express as exact conditions — greetings, out-of-scope topics, keyword triggers. Use **Sentinels** for nuanced classification that requires understanding context and intent.
## Combining sentinels and empathy rules
Both can be active simultaneously. The execution order is:
1. Empathy Rules (instant, no LLM)
2. Sentinels (LLM-powered, sequential)
3. Main agent
This ordering minimizes cost — deterministic rules catch the easy cases before any LLM is invoked.
## Next steps
Create and configure sentinels before assigning them here.
Configure conversation memory for the agent.
# Profile
Source: https://docs.alquimia.ai/products/studio/platform/agent-creation/profile
Define the agent's identity, personality, purpose, and reasoning behavior.
**Profile** is where your agent gets its character. It controls who the agent is, how it behaves, and how it thinks.
## Basic information
| Field | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | The agent's display name. Shown on the dashboard card, in the test drawer, and in any UI that lists agents. |
| **Description** | A short summary of what the agent does. Shown on the dashboard and used as the agent's description when it's used in Agent-to-Agent configurations. |
| **Tags** | Optional labels for organizing agents (e.g., `support`, `finance`, `internal`, `v2`). |
## Custom Clauses
Custom Clauses are the six building blocks of an agent's system prompt. When Dev Mode is off, Studio assembles these into a complete system prompt automatically.
| Clause | What it defines | Example |
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Identity** | Who the agent is | "You are Maya, a customer support assistant for Acme Corp" |
| **Personality** | Tone, style, and communication approach | "You are warm, concise, and professional. Avoid jargon." |
| **Purpose** | The agent's primary goal | "Your goal is to help customers resolve billing questions and account issues" |
| **Knowledge** | What the agent knows and doesn't know | "You have expertise in our product catalog and pricing. You do not have access to real-time inventory." |
| **Rules** | Behavioral constraints and guardrails | "Never share other customers' data. Always escalate legal questions to the legal team." |
| **Response Format** | How answers should be structured | "Respond in plain text. Use bullet points for multi-step instructions. Keep answers under 200 words." |
You don't need to fill all six clauses. **Identity** and **Purpose** are the most impactful starting points. Add others as you find the agent behaving in unexpected ways.
## Evaluation strategy
Controls how the agent reasons and whether it can use tools. See [Agents → Evaluation Strategies](/core-concepts/agents#evaluation-strategies) for the full breakdown.
This field is set automatically when you add MCP servers or other agents to your configuration. Studio switches to `react` to enable the tool-use loop. You can override this manually in [Dev Mode](/platform/agent-creation/dev-mode).
## Structured output
An optional JSON schema that forces the agent to return data in a specific format instead of free-form text.
Use this when:
* The agent feeds into another system or pipeline that expects structured data
* You want to extract specific fields from the agent's analysis
* You're building a classification or extraction agent
Example: An agent that always returns `{ "intent": "...", "confidence": 0.0, "suggested_action": "..." }`.
## Next steps
Select the model that powers this agent.
# Dashboard
Source: https://docs.alquimia.ai/products/studio/platform/dashboard
Your agent feed — open agents, manage runtime state, and jump to metrics from the workspace home.
The Dashboard is the home screen of Studio. It lists every agent in your active workspace as a card grid.
## Agent cards
Each card shows:
* **Name** and **description**
* **Status** — Running, Paused, or Stopped (whether the agent is live for the runtime)
* **Tags** (when set)
* **Last active** (when available)
**Click anywhere on the card** to open the [agent detail page](#agent-detail-page). Use the **⋯** button in the top-right to open the card menu without leaving the dashboard.
## Card menu (⋯)
| Item | What it does |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **View details** | Opens the agent detail page (same as clicking the card). |
| **Metrics** | Opens the agent metrics dialog for that agent (Prometheus-backed charts for the selected assistant). |
| **Edit** | Opens the agent detail page in **edit** mode. Shown when your role allows editing. |
| **Start agent** | Brings the agent online for the runtime when it is not Running. Shown when your role allows editing. |
| **Stop agent** | Pauses the agent for the runtime while keeping its configuration. Shown when the agent is Running and your role allows editing. |
| **Copy ID** | Copies the full assistant identifier (including workspace scope) to the clipboard. |
| **Copy Slack connector** | Copies the Slack inbound connector URL for this agent. |
| **Delete** | Starts delete confirmation; permanently removes the agent when confirmed. Shown when your role allows deleting. |
**Start** / **Stop** change whether the runtime will serve the agent; they do not delete configuration. Use **Stop** for maintenance or temporarily taking an agent offline.
## Agent detail page
After you open an agent from the dashboard, the detail page is where you review each configuration area (profile, model, tools, memory, and so on) and change configuration when you have edit access.
**Try Me** lives in the **header** of this page (not in the dashboard card menu). It opens the **Test Drawer** — a side panel chat wired to the live runtime so you can exercise the agent with its current saved configuration.
* **Try Me** is available when you are **not** in edit mode; while you are editing, finish or cancel edits first so the drawer matches the saved agent.
* Inside the drawer, traffic hits the Runtime with the agent’s resolved config (model, prompts, tools, memory, etc.), which makes it a practical sanity check before you share or publish the agent.
## Publishing
The **Publish** button in the header lets you publish your entire workspace to the [Discover catalog](/platform/discover). This packages your agents so others can install them.
## Empty state
If no agents exist yet, the dashboard shows an empty state with a prompt to create your first agent.
The **Create Agent** button in the sidebar stays disabled until at least one model is configured in Settings. If it is grayed out, [add a model first](/platform/settings/models).
## Next steps
Build your first agent with the creation wizard.
Configure models, MCP servers, and more.
# Discover
Source: https://docs.alquimia.ai/products/studio/platform/discover
Browse, install, and publish agent workspaces from the community catalog.
The Discover page is a catalog of published agent workspaces. Browse ready-made agents from your organization or the community, install them into your workspace, or publish your own configurations for others to use.
## Browsing the catalog
* **Grid / List toggle** — switch between card grid and compact list view
* **Search** — find agents by name or description
Click any card to open the **Agent Detail Modal**.
## Agent detail modal
The detail modal shows:
* Agent name, description, and publisher
* Tags and capabilities overview
* **Version picker** — if the publisher has released multiple versions (tags), select which one to install
## Installing agents
Two installation modes:
### Add to workspace
Copies the agents from the published workspace into your **current active workspace**. Your existing agents are unaffected — this is an additive operation.
Use this when you want to pull in specific agents from a template and combine them with your own.
### Clone full workspace
Creates a **brand-new workspace** based on the published one. All agents, settings, and configurations from the source are cloned.
Use this when you want a complete starting point — a new workspace with everything already configured.
Cloned workspaces are independent copies. Changes you make to your clone don't affect the original, and updates to the original aren't pushed to your clone.
## Publishing your workspace
Share your agents with others by publishing your workspace to the catalog.
Click **Publish** from the Dashboard header or from inside the Discover page.
Fill in the publish form:
| Field | Description |
| --------------- | --------------------------------------------------------------------------------------------- |
| **Name** | OCI-compatible name (lowercase, hyphens allowed, no spaces). E.g., `customer-support-starter` |
| **Tag** | Version label. Use semantic versioning (e.g., `1.0.0`) or `latest` |
| **Description** | What this workspace contains and who it's for |
| **Logo** | Optional image representing the workspace in the catalog |
When you publish with a versioned tag (e.g., `1.0.0`), Studio also publishes `latest` automatically. This ensures users who install without specifying a version always get the most recent one.
Published workspaces are visible to anyone with access to your registry. Secrets are stored as `$secretRef` references — not raw values — so they're safe to publish. However, avoid publishing proprietary system prompts or sensitive business logic you don't want shared.
## Version management
Each published workspace can have multiple tags (versions). The detail modal's version picker lets installers choose which tag to install.
To publish a new version of an existing workspace, use the same workspace name with a new tag (e.g., `1.1.0`). The `latest` tag is updated automatically.
## Next steps
Understand how workspaces and OCI addressing work.
Manage and test agents in your workspace.
# MCP Servers
Source: https://docs.alquimia.ai/products/studio/platform/settings/mcp-servers
Register external tool servers that agents can call to interact with the world.
MCP (Model Context Protocol) is an open standard for connecting AI agents to external tools and services. Each MCP server exposes a set of callable functions — tools — that agents can use during a conversation.
Examples: GitHub operations, ClickUp task management, database queries, calendar access, custom internal APIs.
## Adding an MCP server
Click **Add MCP Server** and configure both the staging and production stages:
| Field | Description |
| ------------------ | ---------------------------------------------------------------- |
| **Name** | Display name used when selecting MCP servers in agent creation |
| **Description** | What tools this server provides. Helps you identify it later. |
| **Staging URL** | Endpoint for the test/development MCP server |
| **Production URL** | Endpoint for the live MCP server |
| **Transport** | Protocol for communicating with the server |
| **Credentials** | Auth credentials if the server requires them (stored as secrets) |
## Transport types
| Transport | Description | Use when |
| --------- | ---------------------------- | -------------------------------- |
| `sse` | Server-Sent Events over HTTP | Remote MCP servers (most common) |
| `http` | Plain HTTP requests | Simple REST-style MCP servers |
| `stdio` | Standard input/output | Local process-based MCP servers |
## Staging vs Production stages
Each MCP server has two stages with independent URLs and credentials:
* **Staging** — used during agent development and testing
* **Production** — used when the agent goes live
This lets you point agents at a test MCP server during development without risking production data. Toggle the active stage per server independently.
Agents always use whichever stage is currently marked active on the MCP server. You don't need to update agents when you switch a server from staging to production.
## Health check
Studio periodically checks the server's availability. A **green indicator** means the server is reachable. A **red indicator** means the server is down or unreachable — agents using this server may fail to call its tools.
## Credentials
If the MCP server requires authentication (API key, bearer token, etc.), enter the credentials when configuring the server. They're stored as secrets and injected at runtime via the `$secretRef` pattern.
## Using MCP servers in agents
Once registered here, MCP servers appear under **MCP Tools** during agent creation. See [MCP Tools](/platform/agent-creation/mcp-tools) for how to assign them to agents.
## Next steps
Add registered MCP servers to an agent.
# Model Connections
Source: https://docs.alquimia.ai/products/studio/platform/settings/models
Register reusable model connections so agents can use them for inference.
Model Connections tell agents which model to use, where it is hosted, and how to authenticate. Each entry is reusable across multiple agents in your workspace.
## Adding a model connection
Click **Add Model Connection** and fill in the form:
| Field | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | A friendly name shown in the agent builder (e.g., "GPT-4o Production", "Claude Sonnet Production") |
| **Connection type** | Where the model is hosted — OpenAI, Anthropic, Groq, OpenShift AI, Hugging Face, or Custom endpoint |
| **Model ID** | The identifier your provider expects (e.g., `gpt-4o`, `claude-sonnet-4-20250514`, `meta-llama/Llama-3.1-8B-Instruct`) |
| **Endpoint** | Shown based on connection type — custom URL for OpenShift or self-hosted servers; optional for Hugging Face dedicated endpoints |
| **Credentials** | API key stored as a [secret](/core-concepts/secrets) in the vault |
Studio configures the technical connection for you. You choose where the model lives; agents reference the connection by name.
## Connection types
| Connection type | When to use | Example Model IDs |
| ------------------- | -------------------------------------------------- | ------------------------------------------------------- |
| **OpenAI** | OpenAI or OpenAI-compatible cloud APIs | `gpt-4o`, `gpt-4o-mini` |
| **Anthropic** | Claude models | `claude-sonnet-4-20250514`, `claude-3-5-haiku-20241022` |
| **Groq** | Groq-hosted models | `llama-3.3-70b-versatile`, `mixtral-8x7b-32768` |
| **OpenShift AI** | Models served in your OpenShift cluster | `llama-3-8b-instruct`, `mistral-7b-instruct` |
| **Hugging Face** | Dedicated Inference Endpoints or Hub repo IDs | `meta-llama/Llama-3.1-8B-Instruct` |
| **Custom endpoint** | vLLM, TGI, LM Studio, or other self-hosted servers | `llama-3`, `mistral-7b` |
For local or self-hosted OpenAI-compatible servers (Ollama, vLLM, TGI), choose **Custom endpoint** and set the full base URL (e.g., `http://localhost:11434/v1`).
## Credentials become secrets
When you save a model connection with a new API key, Studio:
1. Stores the key in the Registry secrets store with a suggested name (e.g., `OPENAI_API_KEY`, `OPENSHIFT_AI_API_KEY`)
2. References the secret in the connection config — the raw key is never stored in plain text
See [Secrets](/core-concepts/secrets) for how this works.
**To rotate a key**: Edit the connection and enter a new secret value. All agents using that connection pick up the new key automatically.
## Endpoint guidance
| Connection type | Endpoint behavior |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| **OpenAI** | Default endpoint works for api.openai.com; use custom URL only for proxies or gateways |
| **Anthropic** | Endpoint is configured automatically |
| **Groq** | Default Groq endpoint is used automatically |
| **OpenShift AI** | Base URL of your model's inference route in the cluster (usually ending in `/v1`) |
| **Hugging Face** | Required for dedicated Inference Endpoints; leave empty for serverless Hub models using `org/model` IDs |
| **Custom endpoint** | Full base URL of your server (e.g., `http://localhost:11434/v1`) |
## Using connections in agents
When creating or editing an agent, select an existing model connection from the inference tab. You do not re-enter credentials — agents inherit authentication from the connection.
## Next steps
Once you have a model connection, you are ready to create your first agent.
# Settings Overview
Source: https://docs.alquimia.ai/products/studio/platform/settings/overview
Configure the building blocks that agents are assembled from.
Settings is where you configure the infrastructure your agents depend on. **Before creating your first agent, configure at least one model here.**
Think of Settings as the toolbox. Agents are built from the tools in the box. You define the tools once, and any agent in the workspace can use them.
## The settings sections
Register LLM providers and their API credentials. Every agent needs a model.
Connect external tools — APIs, databases, and services agents can call.
Define safety and pre-processing agents that intercept requests before your main agent runs.
Embeddings for the **Knowledge Base** are managed automatically by the Alquimia runtime — there is no embeddings model to configure here.
## Recommended setup order
1. **Models** — required to create any agent
2. **MCP Servers** — required if you want agents to use external tools
3. **Sentinels** — optional, for safety and moderation workflows
All settings are scoped to the active workspace. If you switch to a different workspace, you'll start with an empty settings configuration for that workspace.
## Bootstrap from Docker Compose
Cloud models are not pre-filled from `.env`—add them in **Settings → Models Registry**. If you use the **`with-local-models`** profile and set `OLLAMA_MODELS` in `.env`, `studio-init` can register those Ollama models for you; still confirm they appear under Models before you create an agent.
# Sentinels
Source: https://docs.alquimia.ai/products/studio/platform/settings/sentinels
Pre-processor agents that intercept and evaluate requests before your main agent runs.
A **Sentinel** is a mini-agent that runs **before** the main agent processes a user message. It intercepts the input, applies a classification or safety check, and can block, transform, or tag the request.
## Use cases
* **Content moderation** — block harmful or off-topic inputs
* **Intent classification** — tag the request type for downstream routing
* **PII detection** — flag or redact personal information
* **Language detection** — route to a language-specific agent
* **Topic enforcement** — ensure users stay within the agent's defined scope
## Sentinel vs Safeguard Model
These are two distinct concepts:
| Term | What it is |
| ------------------- | -------------------------------------------------------------------------- |
| **Safeguard Model** | The LLM configuration used by the sentinel — its "brain" |
| **Sentinel** | The complete pre-processor: a safeguard model + system prompt + conditions |
Think of the safeguard model as the engine and the sentinel as the car.
## Adding a sentinel
Click **Add Sentinel**:
**Profile section** — defines what the sentinel does:
* **System Prompt** — instructions for the sentinel's LLM. E.g.: *"You are a content moderator. Classify the following user input as `safe` or `unsafe`. Return only the classification label."*
**Config section** — which model powers the sentinel:
* References a **Safeguard Model** registered in Settings
**Conditions section** — what happens based on the sentinel's output:
The visual condition builder lets you define rules like:
* IF sentinel returns `unsafe` → block the request with a fixed message
* IF sentinel returns `billing` → tag the request and allow through
* IF sentinel returns `escalate` → forward to a human handoff flow
Sentinels run synchronously before the main agent. Every user message waits for the sentinel to complete. Use small, fast models (e.g., 7B or smaller) for classification tasks to keep latency low.
## Using sentinels in agents
Once a sentinel is created here, it becomes available under **Pre-processor** during agent creation. Multiple sentinels can be chained — they run in order, and if one blocks the request, subsequent sentinels and the main agent are skipped.
See [Pre-processor](/platform/agent-creation/pre-processor) for how to assign sentinels to agents.
## Next steps
Add sentinels and empathy rules to an agent.
# Ecosystem Services Reference
Source: https://docs.alquimia.ai/products/studio/reference/ecosystem-services
All services in the Alquimia stack, their default ports, and key environment variables.
## Services
| Service | Default Port | URL | Description |
| --------------- | ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Runtime** | 8080 | [http://localhost:8080](http://localhost:8080) | Event-driven agent execution platform. Orchestrates multi-agent LLM runs (prompting, memory, tool execution, and retrieval flows). |
| **Twyd** | 8000 | [http://localhost:8000](http://localhost:8000) | Knowledge base service — topics, files, vector search. |
| **Studio** | 3001 | [http://localhost:3001](http://localhost:3001) | Agent builder. Login via Keycloak or Lite. In-app metrics dashboards for agents (OpenTelemetry; Prometheus-backed). |
| **Insight Hub** | 3000 | [http://localhost:3000](http://localhost:3000) | Knowledge exploration app — Topics, document ingestion, and streaming AI chat over the Alquimia runtime. |
| **MongoDB** | 27017 | — | Studio's database (models, MCP, sentinels, settings). |
| **Ollama** | 11434 | [http://localhost:11434](http://localhost:11434) | Local LLM inference (with-local-models profile only). |
## Environment variables
All configuration lives in `.env` in the `alquimia-local` directory.
### Shared
| Variable | Description |
| ------------------- | ------------------------------------------ |
| `API_TOKEN` | Internal API token shared between services |
| `AUTH_PROVIDER` | Authentication provider identifier |
| `ASSISTANT_BASEURL` | Registry API base URL (used by Studio) |
### Models (cloud & custom endpoints)
Cloud providers, API keys, and **Base URL** overrides (including OpenAI-compatible proxies and local inference URLs) are configured in **Studio → Settings → Models Registry**, not via provider blocks in `.env`.
### Runtime
| Variable | Description |
| ----------------------- | ----------------------------------------------------- |
| `RUNTIME_HOST_PORT` | External port for the Runtime service (default: 8080) |
| `K_SINK` | Event sink URL for async messaging |
| `ALQUIMIA_REGISTRY_DIR` | Directory for local registry storage |
### Router
| Variable | Description |
| -------------------------------- | ---------------------------------------------------- |
| `ROUTER_HOST_PORT` | External port for the Router service (default: 8081) |
| `ALQUIMIA_RUNTIME_URL` | URL the Router uses to reach the Runtime |
| `ROUTER_RUNTIME_TIMEOUT_SECONDS` | Request timeout in seconds |
### Studio
| Variable | Description |
| ------------------------ | ---------------------------------------- |
| `STUDIO_HOST_PORT` | External port for Studio (default: 3001) |
| `AUTH_KEYCLOAK_ID` | Keycloak client ID |
| `AUTH_KEYCLOAK_SECRET` | Keycloak client secret |
| `AUTH_KEYCLOAK_ISSUER` | Keycloak issuer URL |
| `STUDIO_NEXTAUTH_SECRET` | NextAuth.js session secret |
### Database
| Variable | Description |
| ---------------------------- | ---------------------- |
| `POSTGRES_USER` | Postgres username |
| `POSTGRES_PASSWORD` | Postgres password |
| `POSTGRES_DB` | Postgres database name |
| `MONGO_INITDB_ROOT_USERNAME` | MongoDB root username |
| `MONGO_INITDB_ROOT_PASSWORD` | MongoDB root password |
### MinIO
| Variable | Description |
| --------------------- | -------------------------------------------- |
| `MINIO_ROOT_USER` | MinIO admin username |
| `MINIO_ROOT_PASSWORD` | MinIO admin password |
| `BLOB_S3_*` | S3-compatible storage configuration for Twyd |
### Ollama (local models profile)
| Variable | Description |
| ------------------ | ------------------------------------------------ |
| `OLLAMA_MODELS` | Space-separated model names to pull and register |
| `OLLAMA_HOST_PORT` | External port for Ollama (default: 11434) |
| `OLLAMA_BASE_URL` | Base URL used by the Runtime to call Ollama |
### Insight Hub
Insight Hub is the knowledge-exploration UI (topics, documents, streaming chat). It is not the observability surface for agents — that lives in Studio (see Studio row above).
| Variable | Description |
| --------------------------- | --------------------------------------------- |
| `INSIGHT_HUB_HOST_PORT` | External port for Insight Hub (default: 3000) |
| `INSIGHT_HUB_AUTH_PROVIDER` | Auth provider for Insight Hub |
All port variables follow the pattern `{SERVICE}_HOST_PORT`. Override them in `.env` before running `docker compose up` — changing them after containers are created requires `docker compose down` first.
# Roles & Permissions
Source: https://docs.alquimia.ai/products/studio/reference/roles-and-permissions
Access control roles in Alquimia Studio and what each can do.
Studio uses role-based access control (RBAC). When using **Keycloak**, roles and groups are read from the JWT token at login — no additional configuration needed in Studio.
## Roles
| Role | Scope | Description |
| ---------------- | ------------- | ------------------------------------------------------------------------------------------------ |
| `platform-admin` | Platform-wide | Full access to everything. Can manage workspaces, users, and all platform settings. |
| `org-admin` | Organization | Can manage workspace settings, agents, and workspace members within their organization. |
| `editor` | Workspace | Can create, edit, and delete agents and workspace settings (models, MCP, embeddings, sentinels). |
| `viewer` | Workspace | Read-only access. Can view agents and settings but cannot create, edit, or delete anything. |
## Permissions matrix
| Action | viewer | editor | org-admin | platform-admin |
| ---------------------------- | ------ | ------ | --------- | -------------- |
| View agents | ✅ | ✅ | ✅ | ✅ |
| Test agents (Try Me) | ✅ | ✅ | ✅ | ✅ |
| Create agents | ❌ | ✅ | ✅ | ✅ |
| Edit agents | ❌ | ✅ | ✅ | ✅ |
| Delete agents | ❌ | ✅ | ✅ | ✅ |
| Enable/disable agents | ❌ | ✅ | ✅ | ✅ |
| View settings | ✅ | ✅ | ✅ | ✅ |
| Add/edit models | ❌ | ✅ | ✅ | ✅ |
| Add/edit MCP servers | ❌ | ✅ | ✅ | ✅ |
| Add/edit embeddings | ❌ | ✅ | ✅ | ✅ |
| Add/edit sentinels | ❌ | ✅ | ✅ | ✅ |
| Publish workspace | ❌ | ✅ | ✅ | ✅ |
| Manage workspace members | ❌ | ❌ | ✅ | ✅ |
| Create/delete workspaces | ❌ | ❌ | ✅ | ✅ |
| Platform-wide administration | ❌ | ❌ | ❌ | ✅ |
## Assigning roles
If you're using **Keycloak**, roles are assigned there:
1. Log in to the Keycloak admin console
2. Navigate to your realm → Users
3. Select the user → Role mappings
4. Assign the appropriate role from the client roles list
If a UI element is greyed out or a feature is missing from your view, your role doesn't have permission for that action. Contact your platform administrator to request elevated access.
## Groups
In addition to roles, **Keycloak groups** (when enabled) are extracted from the JWT and available in the session. Groups can be used for workspace isolation and organizational scoping. Consult your platform administrator for your organization's group structure.