Tools & integrations

A tool is any external capability an agent can invoke during execution. Tools turn a conversational agent into an action-oriented system: they can query databases, call APIs, read files, send messages, or trigger business workflows.

Why tools matter

Without tools, an agent is limited to the knowledge in its model and the context provided in the conversation. With tools, an agent can:

Retrieve live data that was not available at training time.
Perform actions on behalf of a user or process.
Enforce business rules by interacting with systems of record.
Provide grounded, verifiable answers instead of guesses.

How tools are used

When an agent receives a request, the runtime decides whether a tool is needed and, if so, which one. The result of the tool call is returned to the agent and used to produce the final answer.

User request
    │
    ▼
Agent evaluates need for a tool
    │
    ├─ No tool needed ──► direct answer
    │
    └─ Tool needed
          │
          ▼
    Runtime invokes tool
          │
          ▼
    Result returned to agent
          │
          ▼
    Final answer

A single conversation may involve multiple tool calls. The runtime manages sequencing, retries, and error handling.

Categories of tools

Category	Examples
Data access	Query a CRM, search a knowledge base, read a document store
Action	Create a ticket, send a notification, update an order status
Computation	Run a calculation, validate data, transform formats
Human-in-the-loop	Request approval, escalate to a person, confirm a sensitive action

Integration patterns

Tools can be integrated in several ways depending on who owns the system and how closely it needs to be governed.

Built-in providers

Alquimia Platform includes adapters for common services. These are configured declaratively and are managed by the runtime.

Custom tools

You can register your own tools by exposing them through a standard interface. This is useful when the capability is specific to your business or when you need fine-grained control over behavior.

MCP servers

Model Context Protocol (MCP) servers provide a standardized way to expose tools to agents. MCP tools can be shared across agents and environments, and they support features such as typed schemas and human approval.

Designing good tools

Well-designed tools make agents more reliable and easier to maintain.

Single responsibility — each tool should do one thing. Composable tools are easier to test and reuse.
Clear descriptions — the agent chooses tools based on their names and descriptions. Be explicit about inputs, outputs, and side effects.
Idempotency — where possible, make repeated calls safe. This helps when the runtime retries a failed invocation.
Bounded scope — a tool should return only the data the agent needs. Large responses waste context and can reduce answer quality.
Error signals — return structured errors so the agent can explain what happened or try again.

Governance and approvals

Not every tool should run automatically. Alquimia Platform supports approval workflows for sensitive tools. When configured, the runtime pauses execution, asks a human for confirmation, and only proceeds after receiving an explicit decision. Approvals can be delivered through the same channel the user is already on, such as WhatsApp or Email.

Observability

Every tool invocation is traced as part of the agent execution. This lets you audit what actions were taken, by which agent, and in response to which request.