Use cases

Alquimia Platform is not only a framework for building chatbots. It is a governed execution platform for agents that need to be correct, observable, and safe in production. Every use case below is built on the same set of platform primitives.

The registry-first pattern

The fastest way to make an agent fail in production is to let its configuration drift across environments. Alquimia Platform avoids that by making the registry the source of truth for anything an agent can touch.

1. Create an agentspace. A namespace for a team, tenant, or environment.
2. Register resources first. Tools, knowledge topics, files, models, and secrets are registered in the agentspace before any agent spec references them.
3. Reference them in specs. Agent configurations use stable IDs such as tool_ref and topic_id instead of embedding URLs, collection names, or credentials.
4. Promote through OCI. The whole agentspace is published as a versioned, signed OCI artifact and pulled into staging or production unchanged.

# 1. Create the agentspace
alquimia registry create --name support-prod

# 2. Register the resources the support bot will use
alquimia registry tools add crm-tools \
  --provider-id mcp \
  --connection-config '{"url": {"$secretRef": "CRM_MCP_URL"}}'

alquimia registry topics add policies \
  --severity read-only \
  --tier-grants reader,editor,operator

alquimia registry topics add-file policies ./policies/returns.md

alquimia registry secrets add CRM_MCP_URL --namespace support-prod --scope global
alquimia registry secrets put CRM_MCP_URL https://crm.internal/mcp --namespace support-prod

# 3. Add the agent spec (which only references registered IDs)
alquimia registry agents add support-bot.json --namespace support-prod

# 4. Publish the whole agentspace as a signed OCI artifact
curl -X PUT "http://runtime:8080/registry/publish?agentspace_id=support-prod&tag=v1.0.0" \
  -H "Authorization: Bearer $API_TOKEN"

Because the spec only points to registered resources, a promotion cannot accidentally point staging at the production CRM or embed a leaked API key.

Access roles are a ceiling, not a permission list

Every agent declares a role of reader, editor, or operator. This is an identity-plane ceiling, not a capability list. The real enforcement happens in the registry:

• Tool operations carry severity and tier_grants.
• Knowledge topics carry a TopicAccessPolicy with the same fields.
• Boltzmann Brain modules carry per-module grants.

Role	Typical scope
reader	Read-only tools and knowledge. Cannot invoke mutating operations.
editor	Can run recoverable mutations, such as drafting tickets or updating non-critical records.
operator	Can run destructive operations, such as deleting resources or processing refunds. Always forces human approval where configured.

If an agent has no declared role, or its role is not in the effective tier grants of a tool operation or topic, the call is denied by default.

Knowledge lifecycle

Knowledge in Alquimia Platform is curated, versioned, and auditable:

• Topics (topic_id) are stable handles for knowledge collections.
• Files are ingested into topics, content-addressed, and tracked as FileRegistration records.
• Vector collections are a deployment detail: the same topic_id resolves to qdrant in production and in_memory in tests.
• Boltzmann Brains provide immutable, content-addressed memory with provenance, ingestion gating, and retirement operations (drop, supersede, redact).

This means a knowledge change is a registry change. Roll back a topic policy, rebuild a collection, or pull an older agentspace tag, and every agent that references it sees the new state without redeploying code.

Shields: input and content

Shields are classifiers that run before the main LLM call and can enforce an action on their own:

• observe — record a verdict.
• flag — record a warning but continue.
• block — refuse the request and emit a shield.blocked.v1 worklog event.

They can also be attached to tool registrations and topic registrations to scan tool outputs and retrieved knowledge chunks before they reach the model context. When a content shield blocks, the offending result is replaced with a safe message.

Example: block prompt injection on user input

{
  "shields": {
    "prompt-injection": {
      "provider_id": "shield-config",
      "connector": {"provider_id": "alquimia/prompt-injection-detection"},
      "action": "block",
      "threshold": 0.5,
      "fail_closed": true,
      "block_message": "This request could not be processed for safety reasons."
    }
  }
}

Example: LLM classifier shield

{
  "shields": {
    "intent": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia",
        "profile": {
          "system_prompt": "Classify intent. Output JSON: {\"intent\": \"...\"}",
          "evaluation_strategy": {"evaluation_strategy_id": "one-shoot"}
        },
        "config": {"model_ref": "gpt-4o-mini-classifier"}
      },
      "action": "observe"
    }
  }
}

Example: content shield on a tool registration

{
  "registered_tool_id": "crm-tools",
  "provider_id": "mcp",
  "connection_config": {"url": {"$secretRef": "CRM_MCP_URL"}},
  "shields": {
    "pii-check": {
      "provider_id": "shield-config",
      "connector": {"provider_id": "alquimia/prompt-injection-detection"},
      "action": "block",
      "threshold": 0.4,
      "block_message": "Tool result removed by safety policy."
    }
  }
}

Example: content shield on a topic registration

{
  "topic_id": "contracts",
  "access_policy": {
    "severity": "read-only",
    "tier_grants": ["reader", "editor", "operator"]
  },
  "shields": {
    "privilege-check": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia",
        "profile": {
          "system_prompt": "Check if the text contains attorney-client privileged content. Output JSON: {\"privileged\": true|false}",
          "evaluation_strategy": {"evaluation_strategy_id": "one-shoot"}
        },
        "config": {"model_ref": "gpt-4o-mini-classifier"}
      },
      "action": "block",
      "threshold": 0.8,
      "block_message": "Privileged content removed from retrieval result."
    }
  }
}

Business use cases

Customer support automation

Multi-channel support with grounded answers, identity verification, and escalation gates.

IT operations & ticketing

Ticket-driven diagnostics and approved changes with least-privilege tool policies.

Document intelligence & RAG

Citable answers from curated topics, files, and Boltzmann Brains.

Multi-agent workflows

Specialized agents that discover and delegate to each other through the registry.

Human-in-the-loop approvals

Pause high-risk actions for human approval without leaving the channel.