Skip to main content

Tools and Knowledge

Tools let an agent reach your own systems in the middle of a conversation. A vet clinic's agent might call the booking system to check free appointments, or a helpdesk agent might look up an order before replying. Frontline agents also have a knowledge setting that can be switched on or off.

Before You Start​

  • Role: Admin or Organisation Admin. See Roles and Permissions.
  • The details of the system to call. Each tool needs the web address the agent should call, the method it accepts, and how it signs in, such as an API key. Ask whoever runs the system for these.

How Tools Work​

A tool is a description of one action in one of your systems: what it does, where it lives, and what information it needs. During a call or run, the agent reads the tool descriptions and decides when one would help. It then calls the system, reads the reply, and carries on.

The agent relies on the tool's description to know when to use it, so write it in plain words, for example "Checks which appointment times are free on a given day."

Connecting a System in the Builder​

When IQ builds an agent, it lists the systems the agent seems to need under Connecting Your Systems in the review. Each shows To set up until it is connected. See Building an Agent with IQ.

  1. Select Set up beside the system. The Connect form opens, named after the system.

  2. What it does. Check the Name and What it does. Tell the agent when to use it, in plain words.

  3. Where it lives. Enter the Endpoint URL, the full address the agent calls, starting with https://. Choose the Method: GET looks something up, POST sends something new.

  4. Sign-in. Choose how the system signs in under How it signs in:

    • None, for a system that needs no sign-in
    • API key, then enter the Header name your system reads the key from (X-API-Key unless told otherwise) and the API key
    • Bearer token, then enter the Token

    The key or token is stored with the agent and only sent to this address.

  5. Check it. Optionally select Send test request to try the connection. "Test request worked" means the system answered. "The test request didn't go through" shows the reply code to pass to whoever runs the system.

  6. Select Save connection.

To leave a system for later, select Skip for now. The agent is built without it, and the tool can be added later in the editor.

Adding and Editing Tools​

In the Agent Editor​

  1. Open the agent in the editor and go to Tools.
  2. Select Add external tool.
  3. Fill in the tool:
    • Tool name: a short name such as check_availability. Use letters, numbers, underscores and hyphens, up to 64 characters. Each tool on an agent needs its own name.
    • Method: GET, POST, PUT, PATCH or DELETE. The default is POST.
    • URL: the full address to call, starting with http:// or https://.
    • Description: when the agent should use the tool, in plain words.
    • Input schema: the information the tool needs, written in JSON. Whoever runs the system can usually supply this.
    • Headers: select Add header for each header the system expects, such as an API key. Each needs a Header name and a Header value.
  4. The draft saves on its own. Publish to make the tool live.

To remove a tool, select Remove tool. To remove a header, select Remove beside it.

In Quick Config​

On a published agent, the Quick Config tab shows each tool as a card.

  1. Select Add Tool, or select an existing card to edit it.
  2. Fill in the same details in the side panel.
  3. Select Done. This keeps the change in the draft. Nothing is published until you publish a version.

A card can show:

BadgeMeaning
NewAdded in the draft and not yet published
ChangedEdited since the live version
Needs a name and a URLNot finished. The draft cannot be published until it is.
Removed on publishRemoved in the draft. Select Keep it to undo.

See Quick Config.

Fixing Tool Problems​

Publishing checks every tool. If one is not ready, the checklist says what to fix, for example:

  • "This tool isn't set up yet. Add the address it should call."
  • "Another tool already uses this name."

A tool's Headers cannot set the standard connection headers, such as Host or Content-Length, and a header value cannot be empty or span more than one line.

If a tool is set up but the agent does not use it when expected, make the Description more specific about when it applies, then test again in the playground. If the agent uses it but gets an error back, open the session to see what happened. See Sessions.

Giving an Agent Knowledge​

Frontline agents have a knowledge setting, described as "Allow the agent to consult the configured knowledge base." It is on by default.

  • In the builder: under Recording & knowledge in the review, switch Knowledge on or off.
  • In the editor: in the Model section, switch Knowledge base agent on or off.

Both switches change the same setting. Background agents do not have it. To give any agent facts it needs, such as opening hours or policies, put them in its instructions, or give it a tool that looks them up.

What Happens Next​