Skip to main content

Tools

Tools are actionable capabilities that allow an AI agent to interact with external systems, retrieve data, or perform specific tasks during a conversation. Each tool represents a single action and consists of a YAML definition (configured within a plugin) and a Python implementation—the function that runs when the agent invokes the tool.

The AI agent chooses the appropriate tool based on its current task and the instructions provided in the prompt. If a tool is not explicitly made available in the agent's workflow, the LLM will not be able to call it, even if the tool is implemented on the server side.

Tool types​

Before configuring a tool, identify whether it is a system-provided feature or a custom integration:

  • System tools Native platform features, such as Knowledge Base search. You don't need to add a tool group to your agent—these tools are globally available. Learn more about all available system tools

  • Custom tools User-defined integrations with external APIs, CRMs, or databases. You must upload a custom tool as a plugin and add the corresponding tool group to your agent. Learn more about creating custom tools

Connect Tools to Your Agent​

Tools are not active by default. To enable a tool, you must complete a two-step configuration process: authorization (connecting the tool to the agent) and activation (enabling it in the workflow).

Step 1: Connect the tool to the agent (Authorization)​

Note: This step applies only to Custom Tools

  1. Go to AI Agents > Tools.
  2. Select Add tool group +.
  3. Upload your YAML definition and Python implementation files. If your code requires third-party libraries, include a requirements.txt file.
  4. Navigate to your specific Agent Settings.
  5. In the Tool Groups section, locate your group and set the toggle to On.

Step 2: Configure tool availability in the workflow (Activation)​

Note: This step is mandatory for both System and Custom tools.

An authorized tool will not be invoked unless it is explicitly enabled within the agent’s current workflow state. This allows you to restrict capabilities based on context. For example, a ProcessRefund tool should be available in a billing state, but disabled during the initial greeting.

  1. Open the Workflow configuration for your agent.
  2. Select the specific State where the tool should be used (for example, Support_State).
  3. In the available_tools property, add the unique name of your tool.
- process_name: CustomerSupport
  name: MainSupportState
  kind: StateConfig
  description: |
    ## When to use tools
    - Use CreateSupportTicket when customer describes a problem
    - Use CheckOrderStatus when customer asks about their order
    
  available_tools:
    SingleStatefulOutboundAgent:  # Your agent type
      - SendChatMessage          # System tool
      - CreateSupportTicket      # Your custom tool
      - CheckOrderStatus         # Another custom tool

Tip: Listing a tool in available_tools gives the agent permission to use it, but the agent still needs clear instructions in the description block explaining when to call it.

Tool Configuration Options​

Use available_tools when the agent should decide whether to trigger an action during a conversation. Use attached_tools when an action must run automatically during a state transition.

Unlike available_tools, which are defined at the state level, attached_tools are nested strictly inside the state_scenarios block. The agent does not choose to run them; the platform triggers them automatically when the transition occurs.

Example of attached_tools:

state_scenarios:
  - next_state: TransferToHuman
    transition_name: HandoffRequired
    description: "If user requests a human"
    attached_tools:
      SingleStatefulOutboundAgent:
        - FinishSession

For automatic background actions executed on state entry or exit, use Skills. attached_tools run a tool during a transition; Skills represent separate agent features. Learn more about Skills

Troubleshooting​

If your agent cannot see or use a tool despite being configured, check the following:

  • Workflow state: Verify the tool is declared in available_tools for the current state the agent is in.
  • Tool Group attachment: For custom tools, ensure the Tool Group containing the tool is toggled "On" in the agent's settings.
  • Naming consistency: Ensure the tool name in your YAML workflow matches the object_name in the plugin exactly (it is case-sensitive).
  • Instructions: Check if the state's description clearly tells the agent under what conditions to use the tool.
  • Restart: Always restart the agent (Stop -> Start) after making changes to workflows or tool groups.