Example agent configurations

These examples show complete agent specs you can adapt for common enterprise use cases. They illustrate patterns from the agent specification reference in real configurations.

Customer support bot via WhatsApp

A single agent that answers product questions over WhatsApp, maintains conversation history, and restricts access to whitelisted phone numbers.

{
  "assistant_id": "support-bot",
  "nickname": "Support Bot",
  "description": "Answers product support questions via WhatsApp",
  "tags": ["support", "production"],
  "channels": [
    {
      "provider_id": "whatsapp",
      "channel_id": "whatsapp-support",
      "template": "{{answer}}",
      "middleware": [
        {
          "provider_id": "alquimia:whitelist",
          "allowed_ids": { "$secretRef": "WHITELIST_MIDDLEWARE_ALLOWED_IDS" }
        }
      ],
      "whatsapp_assistant_phone_number_id": { "$secretRef": "WHATSAPP_PHONE_NUMBER_ID" },
      "whatsapp_verify_token": { "$secretRef": "WHATSAPP_VERIFY_TOKEN" },
      "whatsapp_access_token": { "$secretRef": "WHATSAPP_ACCESS_TOKEN" },
      "whatsapp_api_base_url": { "$secretRef": "WHATSAPP_API_BASE_URL" }
    }
  ],
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You are a helpful customer support assistant for Acme Corp.\n\nYou help customers with:\n- Product questions and specifications\n- Return and exchange policy\n- Order status and shipping\n- Store locations and hours\n\nAlways be friendly and concise. If you cannot answer a question, say so clearly and offer to escalate to a human agent.",
      "short_term_memory_strategy": [
        {
          "memory_strategy_id": "max_tokens",
          "memory_max_tokens": 8000
        }
      ],
      "evaluation_strategy": {
        "evaluation_strategy_id": "one-shoot"
      },
      "persistence_strategy": "INCREMENTAL"
    },
    "config": {
      "provider_id": "openai",
      "params": {
        "model": "gpt-4o-mini",
        "temperature": 0.3,
        "max_tokens": 512,
        "api_key": { "$secretRef": "RESPONSE_PROVIDER_API_KEY" }
      }
    }
  }
}

Tip

WHITELIST_MIDDLEWARE_ALLOWED_IDS must be a list dtype secret. Use ["*"] to allow all numbers during development.

Multi-agent feature delivery

A coordinator delegates tasks to specialist agents (coding, QA, technical writing, DevOps). Each specialist uses plan-mode to track its own work.

Coordinator

{
  "assistant_id": "feature-coordinator",
  "nickname": "Feature Coordinator",
  "description": "Coordinates software feature delivery across specialist agents",
  "tags": ["coordinator"],
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You are a senior engineering coordinator. Your job is to break down a feature request and delegate implementation to specialist agents.\n\nFor each feature:\n1. Analyze the requirements\n2. Create a plan with one task per specialist\n3. Delegate to each specialist in order: coding → qa → technical-writer → devops\n4. Pass the output of each specialist as context to the next\n5. Synthesize a final delivery summary\n\nAlways use plan-mode to track progress. Never skip a specialist.",
      "evaluation_strategy": {
        "evaluation_strategy_id": "native",
        "max_steps": 30,
        "max_concurrent_tools": 1,
        "decorators": [
          {
            "decorator_id": "plan-mode",
            "force_completion": true
          }
        ]
      },
      "tools": [
        {
          "provider_id": "a2a",
          "tools_id": "specialist-pool",
          "human_approval": "NONE",
          "selector": { "tags": ["specialist"] }
        }
      ],
      "persistence_strategy": "INCREMENTAL"
    },
    "config": {
      "provider_id": "openai",
      "params": {
        "model": "gpt-4o",
        "temperature": 0.1,
        "api_key": { "$secretRef": "RESPONSE_PROVIDER_API_KEY" }
      }
    }
  }
}

Coding specialist

{
  "assistant_id": "coding-specialist",
  "nickname": "Coding Specialist",
  "description": "Implements code changes given a task description and codebase access",
  "tags": ["specialist"],
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You are an expert software engineer. You receive a task description and implement the required code changes.\n\nAlways:\n1. Read the relevant files before making changes\n2. Make minimal, focused changes\n3. Follow existing code style and patterns\n4. Report exactly which files were changed and what was done",
      "evaluation_strategy": {
        "evaluation_strategy_id": "native",
        "max_steps": 40,
        "max_concurrent_tools": 1,
        "decorators": [
          {
            "decorator_id": "plan-mode",
            "force_completion": true
          }
        ]
      },
      "tools": [
        {
          "provider_id": "mcp",
          "tools_id": "filesystem",
          "human_approval": "NONE",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
          "transport": "stdio"
        }
      ],
      "long_term_memory_strategy": [
        {
          "long_term_memory_id": "summarizer",
          "interaction_threshold_tokens": 30000,
          "interaction_keep": 2,
          "cod_max_loops": 3,
          "instructions": "Preserve: files read, changes made, file paths, function names."
        }
      ],
      "persistence_strategy": "INCREMENTAL"
    },
    "config": {
      "provider_id": "openai",
      "params": {
        "model": "gpt-4o",
        "temperature": 0.0,
        "api_key": { "$secretRef": "RESPONSE_PROVIDER_API_KEY" }
      }
    }
  }
}

Note

Register additional specialists (QA, technical writer, DevOps) with the same tags: ["specialist"] pattern so the coordinator discovers them through the A2A selector.

Email ingestion and triage

An agent that polls an inbox, classifies emails by intent, auto-responds to common categories, and escalates complex requests.

{
  "assistant_id": "email-triage",
  "nickname": "Email Triage",
  "description": "Classifies and responds to inbound support emails",
  "tags": ["support", "email"],
  "channels": [
    {
      "provider_id": "email",
      "channel_id": "support-inbox",
      "read_mailbox": "inbox",
      "email_select_status": "UNSEEN",
      "flag_on_read": "(\\Seen)",
      "unflag_on_error": "(\\Seen)",
      "template": "<html><body>{{ answer | markdown_to_html }}</body></html>",
      "email_username": { "$secretRef": "EMAIL_USERNAME" },
      "email_password": { "$secretRef": "EMAIL_PASSWORD" },
      "email_smtp_server": { "$secretRef": "EMAIL_SMTP_SERVER" },
      "email_imap_server": { "$secretRef": "EMAIL_IMAP_SERVER" },
      "email_smtp_ssl": { "$secretRef": "EMAIL_SMTP_SSL" },
      "email_smtp_port": { "$secretRef": "EMAIL_SMTP_PORT" }
    }
  ],
  "shields": {
    "intent": {
      "provider_id": "alquimia",
      "profile": {
        "system_prompt": "Classify the email intent into exactly one category. Output only valid JSON.\n\nCategories:\n- order_status: asking about an order\n- return_request: requesting a return or refund\n- product_question: asking about a product\n- complaint: expressing dissatisfaction\n- escalation: requesting to speak to a manager\n- other: anything else\n\nEmail: {{query}}",
        "evaluation_strategy": {
          "evaluation_strategy_id": "one-shoot",
          "structured_output": {
            "method": "json_schema",
            "json_schema": {
              "type": "object",
              "properties": {
                "intent": {
                  "type": "string",
                  "enum": ["order_status", "return_request", "product_question", "complaint", "escalation", "other"]
                },
                "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
              },
              "required": ["intent", "confidence"]
            }
          }
        }
      },
      "config": {
        "provider_id": "openai",
        "params": {
          "model": "gpt-4o-mini",
          "temperature": 0.0,
          "api_key": { "$secretRef": "RESPONSE_PROVIDER_API_KEY" }
        }
      }
    }
  },
  "empathy": {
    "rules": [
      {
        "rule_id": "escalation-detected",
        "strategy": "override",
        "description": "Do not auto-respond to escalation requests",
        "requirements": ["intent"],
        "conditions": ["intent.get('intent') == 'escalation'"],
        "response": {
          "provider_id": "fixed",
          "message": "ESCALATION_REQUIRED: This email has been flagged for human review."
        }
      },
      {
        "rule_id": "low-confidence",
        "strategy": "override",
        "description": "Do not auto-respond when classification confidence is low",
        "requirements": ["intent"],
        "conditions": ["intent.get('confidence', 1.0) < 0.7"],
        "response": {
          "provider_id": "fixed",
          "message": "ESCALATION_REQUIRED: Low classification confidence — flagged for human review."
        }
      }
    ]
  },
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You are a customer support agent responding to emails.\n\nThe email intent has been classified as: {{ shields['intent']['intent'] if shields and 'intent' in shields else 'unknown' }}\n\nRespond appropriately:\n- order_status: Ask for order number and explain how to check status at orders.acme.com\n- return_request: Explain the 30-day return policy and provide the returns portal link\n- product_question: Answer based on your product knowledge\n- complaint: Acknowledge the issue, apologize, and offer a resolution path\n- other: Provide a helpful general response\n\nBe professional, concise, and empathetic. Sign off as 'Acme Support Team'.",
      "evaluation_strategy": {
        "evaluation_strategy_id": "one-shoot"
      },
      "persistence_strategy": "EPHEMERAL"
    },
    "config": {
      "provider_id": "openai",
      "params": {
        "model": "gpt-4o-mini",
        "temperature": 0.3,
        "api_key": { "$secretRef": "RESPONSE_PROVIDER_API_KEY" }
      }
    }
  }
}

Tip

EPHEMERAL persistence is correct for email triage because each email is an independent transaction. Do not use INCREMENTAL or unrelated emails will accumulate under the same session.

Agent with a registered model

Instead of embedding model credentials in every agent, reference a model registered in the agentspace.

{
  "assistant_id": "model-ref-bot",
  "role": "reader",
  "response": {
    "provider_id": "alquimia",
    "config": {
      "model_ref": "gpt-4o-mini",
      "params": {
        "temperature": 0.5
      }
    },
    "profile": {
      "system_prompt": "You are a concise assistant.",
      "evaluation_strategy": { "evaluation_strategy_id": "one-shoot" }
    }
  }
}

Register the model first with:

alquimia registry models add gpt-4o-mini --provider-id openai \
  --params '{"model": "gpt-4o-mini", "api_key": {"$secretRef": "RESPONSE_PROVIDER_API_KEY"}}'

Zero Trust tool reference

Reference a classified tool from the registry and narrow its tier grants for this agent.

{
  "assistant_id": "safe-file-browser",
  "role": "reader",
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You can only list and read files.",
      "evaluation_strategy": {
        "evaluation_strategy_id": "native",
        "max_steps": 5
      },
      "tools": [
        {
          "provider_id": "mcp",
          "tool_ref": "filesystem-tools",
          "tier_ceiling": ["reader"]
        }
      ]
    }
  }
}

The registry must classify list_* and read_* as read-only and grant reader. With tier_ceiling: ["reader"], any editor/operator operation is denied even if the registry would allow it.

Direct file access topic

Expose registered files as browseable tools instead of using vector search.

{
  "assistant_id": "doc-browser",
  "role": "reader",
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "Answer questions using the registered product documents.",
      "knowledge_base": [
        {
          "topic_id": "product-docs",
          "search_mode": "direct",
          "tier_ceiling": ["reader"]
        }
      ]
    }
  }
}

Upload and associate files via the runtime API or CLI:

alquimia registry topics add-file product-docs release-notes.pdf --hydrate

Content shield on a tool result

Attach a prompt-injection shield to a tool so dangerous tool outputs are sanitized before reaching the model.

{
  "assistant_id": "secure-browser",
  "role": "reader",
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "Browse the filesystem safely.",
      "tools": [
        {
          "provider_id": "mcp",
          "tool_ref": "filesystem-tools"
        }
      ]
    }
  }
}

The shield lives on the ToolRegistration:

{
  "registered_tool_id": "filesystem-tools",
  "provider_id": "mcp",
  "connection_config": { "url": "http://mcp-server" },
  "shields": {
    "prompt-injection": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia/prompt-injection-detection",
        "heuristic_weight": 0.3,
        "base_classifier_score": 0.0
      },
      "action": "block",
      "threshold": 0.5,
      "fail_closed": true,
      "block_message": "This tool result was removed by a safety policy."
    }
  }
}

Related pages

• Agent specification reference
• Shields & empathy
• Authorization policies
• How to register a model
• How to ingest files into a topic
• Create and publish an agent
• Connect a channel
• Add a tool
• Configure approvals
• Configure content shields