Agent Configuration

An agent in Alquimia is fully described by an AssistantConfig JSON document. This document is stored in the registry and loaded at inference time.

Top-level structure

{
  "assistant_id": "my-agent",
  "nickname": "Helper",
  "description": "A helpful assistant.",
  "tags": ["support", "v2"],
  "channels": [...],
  "shields": {...},
  "empathy": {...},
  "response": {
    "provider_id": "alquimia",
    "config": {...},
    "profile": {...}
  }
}

Fields

Field	Type	Required	Description
assistant_id	string	Yes	Unique identifier
nickname	string	No	Display name (max 64 chars)
description	string	No	Human-readable description (max 3000 chars)
tags	string[]	No	Labels for filtering and discovery
channels	Channel[]	No	Messaging channel integrations (WhatsApp, Slack, Email)
shields	dict[str, Shield]	No	Pre-inference guard models
empathy	EmpathyEngine	No	Context-aware profile switching
response	ResponseProfile	Yes	The main LLM configuration and behavior profile

The response profile

The response field is the core of the agent configuration:

{
  "response": {
    "provider_id": "alquimia",
    "config": {
      "provider_id": "generative",
      "connector": {
        "provider_id": "openai",
        "model": "gpt-4o",
        "api_key": { "$secretRef": "OPENAI_API_KEY" }
      }
    },
    "profile": {
      "system_prompt": "You are a helpful assistant.",
      "evaluation_strategy": { "evaluation_strategy_id": "one-shoot" },
      "short_term_memory_strategy": [...],
      "long_term_memory_strategy": [...],
      "knowledge_base": [...],
      "tools": [...],
      "persistence_strategy": "INCREMENTAL"
    }
  }
}

Profile fields

Field	Type	Default	Description
system_prompt	string	null	Jinja2 template for the system message
prompt_clauses	dict[str, str]	null	Additional named sections injected into the system prompt
evaluation_strategy	EvaluationStrategy	one-shoot	How to interpret LLM responses
short_term_memory_strategy	ShortTermMemoryStrategy[]	null	Token windowing for conversation history
long_term_memory_strategy	LongTermMemoryStrategy[]	null	Summarization or erasure of old context
knowledge_base	KnowledgeBase[]	null	RAG sources (Qdrant vector stores)
tools	ToolConfig[]	null	MCP, Llama Stack, or A2A tool sources
persistence_strategy	string	INCREMENTAL	How to persist conversation state

Persistence strategies

Value	Behavior
INCREMENTAL	Append new messages to the existing session
FLUSH	Replace the session with the current conversation
EPHEMERAL	Do not persist — session is lost after inference

System prompt templating

System prompts are Jinja2 templates. Alquimia automatically injects:

• {{ rag_context }} — retrieved knowledge base chunks
• {{ attachment_context }} — uploaded file content
• {{ evaluation_strategy.prompt_clauses }} — strategy-specific instructions
• {{ prompt_clauses }} — custom named sections
• {{ runtime_context.prompt_clauses }} — dynamic runtime state (plan, condensed context)

Example:

You are a support agent for Acme Corp.

{% if rag_context %}
# Knowledge base
<context>{{ '\n'.join(rag_context) }}</context>
{% endif %}

Always respond in {{ language }}.

Secrets

Sensitive values are referenced with $secretRef markers:

{
  "api_key": { "$secretRef": "OPENAI_API_KEY" }
}

At runtime, the secret resolver substitutes the actual value. The resolver is selected via ALQUIMIA_REGISTRY_SECRET_RESOLVER:

Resolver	Backend	Key format
env	Environment variables	OPENAI_API_KEY
vault	HashiCorp Vault KV v2	OPENAI_API_KEY

Secrets are scoped:

Scope	Resolution pattern
global	{KEY}
shared	{realm}_{KEY}
local	{realm}_{assistant_id}_{KEY}

Shields

Shields are pre-inference classifiers that run before the main LLM call. Their output is available to the Empathy Engine for profile switching.

{
  "shields": {
    "language_detector": {
      "provider_id": "huggingface/text-classification",
      "model": "papluca/xlm-roberta-base-language-detection",
      "endpoint": "https://api-inference.huggingface.co/models/..."
    }
  }
}

Empathy Engine

The Empathy Engine evaluates rules against shield outputs and runtime context to dynamically switch the response profile:

{
  "empathy": {
    "rules": [
      {
        "rule_id": "spanish-override",
        "strategy": "merge",
        "conditions": ["shields['language_detector'].label == 'es'"],
        "requirements": ["shields"],
        "response": {
          "provider_id": "alquimia",
          "profile": {
            "system_prompt": "Eres un asistente útil. Responde siempre en español."
          }
        }
      }
    ]
  }
}

Rule strategies

Strategy	Behavior
none	Match but do not change the profile
override	Replace the entire response profile
merge	Deep-merge the rule’s profile into the main profile

Related pages

• Evaluation Strategies — one-shoot, native, raw
• Memory Strategies — max_tokens, summarizer, neuralyzer
• Tools Reference — MCP, Llama Stack, A2A