Agents & configuration

import { Aside } from “@astrojs/starlight/components”;

An agent in Alquimia Platform is fully described by a configuration document. This document is stored in the registry and loaded at inference time. Because the spec is explicit and versioned, you can hold, release, dry-run, and audit agent behavior without changing code.

What a configuration declares

An agent spec answers four questions:

Who is the agent? — identity, nickname, description, tags.
How does it reason? — model connector, system prompt, evaluation strategy.
What can it use? — tools, knowledge bases, memory strategies, channels.
How is it protected? — shields, empathy rules, human approval, role tier.

A minimal configuration looks like this:

{
  "assistant_id": "support-bot",
  "nickname": "Support Bot",
  "description": "Answers product questions",
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You are a helpful support assistant. Answer concisely.",
      "evaluation_strategy": { "evaluation_strategy_id": "one-shoot" },
      "persistence_strategy": "INCREMENTAL"
    },
    "config": {
      "provider_id": "openai",
      "model": "gpt-4o-mini",
      "api_key": { "$secretRef": "OPENAI_API_KEY" }
    }
  }
}

Identity and metadata

Field	Purpose
`assistant_id`	Unique identifier used in API calls and observability
`nickname`	Human-readable display name
`description`	What the agent does, useful for discovery and A2A delegation
`tags`	Labels for filtering and grouping agents
`role`	Zero Trust capability tier: `reader`, `editor`, or `operator`

The response profile

The response section is the core of the agent. It has two parts:

Profile — behavior directives such as the system prompt, evaluation strategy, memory, knowledge bases, and tools.
Connector — the LLM provider and model to use.

System prompt

The system prompt is a template that defines the agent’s persona, constraints, and instructions. It can include dynamic sections such as retrieved knowledge, attachment context, and runtime state.

Evaluation strategy

The evaluation strategy controls when the agent stops reasoning and returns a final answer. Common strategies include:

Strategy	Behavior
`one-shoot`	Return after a single LLM call
`native`	Enable native tool use with a step limit
`raw`	Parse tool calls from unstructured text for models without native function calling

Memory

Memory strategies decide what the LLM sees in its context window and how older conversation history is managed. See Memory & context for details.

Knowledge base

Agents can retrieve context from registered topics or Boltzmann Brains. Knowledge sources support several access patterns:

Search mode	Behavior
`rag`	Always retrieve relevant chunks for the prompt
`on_demand`	Expose a search tool the agent invokes explicitly
`direct`	Expose file-listing and reading tools
`brain`	Query a Boltzmann Brain with per-module authorization

Tools

Tools connect agents to external systems. Alquimia Platform supports MCP servers, Llama Stack tool groups, Python modules, and other agents via A2A. See Tools & integrations.

Shields

Shields are guard models that run before the main LLM call. They can observe, flag, or block requests:

Action	Behavior
`observe`	Record the verdict and leave the request unchanged
`flag`	Record a warning without terminating inference
`block`	Halt the request and return a rejection before invoking the LLM

A typical configuration registers a prompt-injection detector in block mode and a content classifier in observe mode.

Empathy engine

The Empathy Engine evaluates rules against shield outputs and runtime context to switch the response profile dynamically. For example, a language-detection shield can trigger a rule that loads a Spanish-language system prompt.

Rules can override or merge profiles, so agents adapt to the conversation without hard-coding branches.

Secrets

Sensitive values such as API keys are never embedded directly in the agent spec. They are referenced by name and resolved at runtime from HashiCorp Vault or environment variables.

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

This separation lets you rotate credentials without redeploying agents and keeps secrets out of version control.

Channels

Channels declare how external messaging providers reach the agent. A single agent can have multiple channels — for example, WhatsApp, Slack, and Email — all feeding the same inference pipeline. The channel adapter normalizes provider-specific payloads into the standard request format.

Versioning and promotion

Because agent specs live in a registry, you can:

Validate a new spec before publishing it.
Put an agent on hold to temporarily disable it.
Publish an agentspace as an OCI artifact and pull it into another environment.
Compare agent versions to detect behavior drift.