Studio overview

Alquimia Studio is the web-based visual interface for designing, testing, publishing, and operating agents on Alquimia Platform. It connects to alquimia-runtime and lets teams build production-grade conversational and autonomous agents through a wizard-driven UI, without writing code for every configuration change.

Use Studio when you want:

• A visual agent creation workflow with live validation and interactive testing.
• A central place to manage models, MCP servers, embeddings, and integration channels.
• Multi-agent orchestration with Agent-to-Agent (A2A) delegation.
• A registry and publishing workflow for agentspaces.
• Operator-friendly controls for runs, approvals, knowledge sources, and observability.

Note

Studio does not replace the SDK or API. It is a management layer that stores configuration and publishes agents to the runtime. Developers can still manage agents as code through alquimia-core and the runtime REST API.

What Studio provides

Agent creation wizard

Studio guides users through a step-by-step wizard to define an agent:

1. Basic configuration — name, purpose, personality, and utility description.
2. Model selection — choose from OpenAI, Anthropic, Google, Meta, Mistral AI, Cohere, Groq, or custom OpenAI-compatible endpoints.
3. MCP integration — connect Model Context Protocol servers for tools and data access.
4. Agent-to-Agent (A2A) — delegate tasks to sub-agents by ID or capability tags.
5. Knowledge base — attach RAG-powered document collections.
6. Advanced settings — memory strategies, evaluation criteria, custom clauses, and developer-mode system prompts.

Multi-agent orchestration

Studio supports true agentic AI through A2A delegation:

• Intelligent delegation — primary agents route tasks to specialized sub-agents.
• Tag-based selection — dynamically choose agents by capability tags.
• Expert modules — augment agents with domain-specific expertise.
• Coordinated workflows — build multi-step flows across teams of agents.

Integration channels

Connect agents to external communication platforms from the same UI:

• WhatsApp Business API — respond to WhatsApp messages.
• Email (SMTP) — send automated responses with Jinja2 HTML templates.

Each channel supports staging and production endpoints, real-time validation, and encrypted credential storage.

Knowledge base and RAG

Studio integrates with the Alquimia knowledge base service for retrieval-augmented generation:

• Upload documents (PDF, text, and more).
• Select embedding models and providers.
• Configure semantic search and retrieval parameters.
• Organize knowledge by topics and domains.

Test and iterate

The Try Me feature lets operators chat with an agent in real time before publishing:

• Interactive chat with full agent capabilities.
• Conversation history and context persistence.
• Live configuration updates during testing.

Publish and discover

Studio includes a publishing workflow for sharing agents and workspaces:

• Publish to OCI registry — one-click publish with version tagging and latest dual-push.
• Discover catalog — browse published agentspaces by category.
• Two install modes — add agents to an existing workspace or clone a full workspace.
• Namespace isolation — agentspaces are scoped by organization namespace (namespace/name:tag).

Trust and observability

Studio is integrated with the platform’s observability stack:

• Alquimia TrustLens — optional automated conversation evaluation with Gaussia benchmarks. TrustLens consumes signed runtime webhooks, scores sessions on humanity, context, conversational quality, bias, and toxicity, and exposes Prometheus metrics that Studio renders in the Agent Humanity view.
• OpenTelemetry — distributed tracing, automatic instrumentation, custom metrics, and OTLP export to Jaeger, Tempo, Honeycomb, DataDog, and other backends.

Configure telemetry with environment variables such as:

OTEL_ALQUIMIA_SERVICE_NAME=alquimia-studio
OTEL_COLLECTOR_ENDPOINT_TRACES=http://collector-endpoint/v1/traces
OTEL_COLLECTOR_ENDPOINT=http://collector-endpoint/v1/metrics
OTEL_EXPORTER_INTERNAL_MILIS=5000

Architecture

Studio is a Next.js 15 application with a layered architecture:

┌─────────────────────────────────────────┐
│             Frontend                    │
│  ┌────────────────────────────────┐     │
│  │  React 19 + TypeScript         │     │
│  │  Atomic Design Components      │     │
│  │  Shadcn/ui + Radix UI          │     │
│  └────────────────────────────────┘     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│      Server Actions & API Routes        │
│  ┌────────────────────────────────┐     │
│  │  Next.js Server Actions        │     │
│  │  API Proxy for Runtime         │     │
│  └────────────────────────────────┘     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Business Logic Layer            │
│  ┌────────────────────────────────┐     │
│  │  Agent Service                 │     │
│  │  Settings Service              │     │
│  │  Registry Service              │     │
│  └────────────────────────────────┘     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│          Data Access Layer              │
│  ┌────────────────────────────────┐     │
│  │  Agent Repository              │     │
│  │  Model Repository              │     │
│  │  MCP Repository                │     │
│  └────────────────────────────────┘     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│    MongoDB or NeDB (DB_STRATEGY)        │
│  • Settings (Models, MCPs, Embeddings)  │
│  • Sentinels                            │
└─────────────────────────────────────────┘

External integrations:

• Alquimia Runtime — inference orchestration and agent execution.
• Knowledge Base Service — document storage and embeddings.
• Keycloak — authentication and authorization.
• Trust Lens — observability and metrics.

Tech stack

Layer	Technology
Framework	Next.js 15 with App Router
Language	TypeScript
UI library	React 19
Styling	Tailwind CSS
Components	Shadcn/ui + Radix UI
State management	TanStack Query (React Query)
Forms	React Hook Form + Zod
Backend	Next.js Server Actions + API proxy
Database	MongoDB with Mongoose, or NeDB (DB_STRATEGY=lite)
Authentication	NextAuth.js with Keycloak provider
Observability	OpenTelemetry

Installation

Prerequisites

• Node.js 18+ and Yarn
• MongoDB instance, or set DB_STRATEGY=lite to use embedded NeDB with no external database
• Keycloak instance, or set AUTH_STRATEGY=lite for self-contained authentication
• A running alquimia-runtime deployment
• Environment variables configured

Install and run

# Clone the repository
git clone https://github.com/Alquimia-ai/studio.git
cd studio

# Install dependencies
yarn install

# Configure environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Run development server
yarn dev

Open http://localhost:3000 to access Alquimia Studio.

Production scripts

yarn build   # Build for production
yarn start   # Start production server
yarn lint    # Run ESLint

Configuration

The following environment variables configure Studio:

# Database strategy: "mongo" (default) or "lite" (NeDB, no MongoDB required)
DB_STRATEGY=mongo
MONGODB_URI=mongodb://localhost:27017/alquimia-studio

# Authentication (Keycloak)
KEYCLOAK_ISSUER=https://your-keycloak-instance/realms/your-realm
KEYCLOAK_CLIENT_ID=alquimia-studio
KEYCLOAK_CLIENT_SECRET=your-secret
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-nextauth-secret

# Alquimia Runtime
ASSISTANT_BASEURL=https://runtime.your-domain.com
ALQUIMIA_ASSISTANT_API_KEY=your-runtime-api-key

# OCI / Organization
NEXT_PUBLIC_DEFAULT_NAMESPACE=alquimia

# Knowledge Base Service
KNOWLEDGE_BASE_API_URL=https://kb.your-domain.com
KNOWLEDGE_BASE_API_KEY=your-kb-api-key

# OpenTelemetry (optional)
OTEL_ALQUIMIA_SERVICE_NAME=alquimia-studio
OTEL_COLLECTOR_ENDPOINT_TRACES=http://your-otel-endpoint/v1/traces
OTEL_COLLECTOR_ENDPOINT=http://your-otel-endpoint/v1/metrics
OTEL_EXPORTER_INTERNAL_MILIS=5000

Tip

Use DB_STRATEGY=lite and AUTH_STRATEGY=lite for the fastest local evaluation. For team or production deployments, use MongoDB and Keycloak.

Creating your first agent in Studio

1. Log in and open the Settings tab to add at least one LLM model and any MCP servers you need.
2. Create a new agent from the Agents dashboard (/dashboard/agents/new).
3. Configure basic information — name, description, purpose, and utility.
4. Select a model and configure provider-specific parameters.
5. Add tools and integrations — connect MCP servers, A2A sub-agents, or integration channels.
6. Attach a knowledge base — upload documents and configure retrieval.
7. Tune advanced settings — memory, evaluation strategies, custom clauses, and system prompts.
8. Test with Try Me — validate behavior before publishing.
9. Publish — deploy the agent to the runtime and monitor via Trust Lens.

Agent lifecycle states

State	Meaning
Stopped	Agent is saved but not published to the runtime.
Running	Agent is active and handling requests.
Paused	Agent is temporarily inactive.

Operators can edit, publish, unpublish, or delete agents from the Studio UI.

Security

• Server-side validation for all mutations.
• Authentication required for all routes via Keycloak or the lite auth strategy.
• Role-based access control.
• Secrets and API keys encrypted at rest and never exposed to the client.
• Input sanitization and CSRF protection through NextAuth.js.

Next steps

• Installation — install the runtime and Studio.
• Platform overview — how Studio, runtime, and core fit together.
• Runtime API overview — the HTTP API that Studio uses under the hood.
• Create and publish an agent — agent workflow from configuration to production.