Skip to content
Alquimia Alquimia Alquimia

Tools & Integrations

Alquimia supports four tool backends. All are configured in the tools array of the agent’s Profile.

Tool backends

Section titled “Tool backends”

| Backend | provider_id | Discovery | Execution | |---|---|---|---| | MCP (Model Context Protocol) | mcp | ToolBank.from_mcp() | fastmcp.Client | | Llama Stack | llama-stack | ToolBank.from_llama_stack() | AsyncLlamaStackClient | | Python module | (built-in) | ToolBank.from_module() | Direct Python call | | A2A (Agent-to-Agent) | a2a | Registry query | Recursive evaluate() |

MCP tools

Section titled “MCP tools”

Connect any MCP-compatible server:

{
  "tools": [
    {
      "provider_id": "mcp",
      "url": { "$secretRef": "MY_MCP_SERVER_URL" },
      "auth": { "$secretRef": "MY_MCP_AUTH_TOKEN" },
      "human_approval": "NONE"
    }
  ]
}

For stdio-based MCP servers:

{
  "provider_id": "mcp",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": { "MY_VAR": "value" },
  "transport": "stdio"
}

MCPToolConfig fields

Section titled “MCPToolConfig fields”

| Field | Type | Description | |---|---|---| | provider_id | "mcp" | Required | | url | string \| SecretRef | MCP server URL (HTTP transport) | | auth | string \| SecretRef | Bearer token or auth method | | command | string | Command to launch (stdio transport) | | args | string[] | Arguments for the command | | env | dict[str, string] | Environment variables for the process | | transport | string | Transport type (http, stdio) | | headers | dict[str, string] | Additional HTTP headers | | human_approval | "NONE" \| "LAZY" \| "REQUIRED" | Human-in-the-loop approval |

Llama Stack tools

Section titled “Llama Stack tools”
{
  "tools": [
    {
      "provider_id": "llama-stack",
      "tool_group_id": "my-tool-group",
      "authorization": { "$secretRef": "LLAMA_STACK_PROVIDER_AUTHORIZATION" }
    }
  ]
}

Llama Stack tools are prefixed with llama_stack_ to avoid name collisions.

LlamaStackToolConfig fields

Section titled “LlamaStackToolConfig fields”

| Field | Type | Description | |---|---|---| | provider_id | "llama-stack" | Required | | tool_group_id | string | Filter tools by group | | authorization | string \| SecretRef | Provider authorization header | | extra_headers | dict[str, string] | Additional headers |

Agent-to-Agent (A2A) tools

Section titled “Agent-to-Agent (A2A) tools”

Expose other agents as tools. The calling agent can delegate tasks to specialized agents.

{
  "tools": [
    {
      "provider_id": "a2a",
      "selector": { "tags": ["specialist"] },
      "context": { "domain": "finance" }
    }
  ]
}

The registry is queried with selector to find matching agents. Each matching agent becomes a tool named agent_{nickname}.

A2AConfig fields

Section titled “A2AConfig fields”

| Field | Type | Description | |---|---|---| | provider_id | "a2a" | Required | | selector | dict | TinyDB-style filter to find agents | | context | dict | Extra context passed to the discovered agents |

A2A tool input schema

Section titled “A2A tool input schema”

When the LLM calls an A2A tool, it provides:

| Field | Type | Description | |---|---|---| | query | string | The full task to send to the other agent | | hands_off | bool | If true, the other agent responds directly to the user |

Human-in-the-loop approval

Section titled “Human-in-the-loop approval”

Set human_approval on any tool config to require approval before execution:

| Value | Behavior | |---|---| | NONE | Execute immediately (default) | | LAZY | Request approval but proceed if no response | | REQUIRED | Block execution until approved |

When REQUIRED, the runtime emits a HumanApprovalRequired event. The client must call POST /event/tool-approval to approve or reject.

Knowledge base as a tool

Section titled “Knowledge base as a tool”

When search_mode is "on_demand", the knowledge base is exposed as a search tool that the LLM can call explicitly:

{
  "knowledge_base": [
    {
      "collection_id": "product-docs",
      "search_mode": "on_demand",
      "top_k": 5
    }
  ]
}

The LLM sees a tool named search_product_docs and decides when to call it.

Section titled “Related pages”