Skip to main content

Dynamic Tools

Dynamic Tools allow agents to search for and load tools as needed, rather than having all tools available at once. This approach reduces agent confusion and improves performance when working with large tool collections.

Prerequisites​

  • Agent workflow configuration access
  • Embedder Model integration for vector search
  • Mail service integration (for email confirmations)

When to Use Dynamic Tools​

Use Dynamic Tools when:

  • You have more than 15-20 tools total
  • Tools are situation-specific
  • You want to reduce agent confusion from too many options

Setup Requirements​

Step 1: Add Search Tool​

Add the SearchTool to your available tools configuration:

available_tools:
  SingleStatefulOutboundAgent:
    - SearchTool  # Enable dynamic tool search

Step 2: Configure System States​

Add these required states to your workflow:

# Add these states to your workflow
- name: ToolPickingState
  kind: StateConfig
  process_name: <Name of your process>
  prompt_label: "#### Confirmation instructions"
  description: |
    Human selected some action.

    # Instructions:
    Your task to interpret Human answer - if he wants to perform selected action or not.
    Use tool system answer with only one word:
    "Yes" - if Human agrees.
    "No" - if not.
  # System state for tool selection

- name: ConfirmationState
  kind: StateConfig
  process_name: <Name of your process>
  prompt_label: "#### Picking instructions"
  description: |
    A list of available options has been provided in the observation.

    ### Instructions:
    Using the **system answer tool**, select and return **only one** option number from the observation that best matches the Human's request

    - Respond **only with the option number** (as listed in the observation).
    - If no option fully satisfies the request, return the **Fallback Option** (number 0) instead.
    - **Do not select** an intermediate step — only pick an option that directly fulfills the request.
    - **Do not send a message to the Human.**
    - **Do not choose a tool** for sending a message to the Human.
    - If a tool is more general than the user's request and is the most appropriate option available, use that tool.
  # System state for confirmations

Step 3: Set Up Transitions​

Add hidden transitions to pass workflow validation:

state_scenarios:
  - next_state: ConfirmationState
    description: None
    hidden: true
  - next_state: ToolPicking
    description: None
    hidden: true
  • Add an Embedder Model integration to your configuration
  • Tools will be automatically indexed for search

How Dynamic Tools Work​

  1. Agent recognizes it needs a capability not in current tools
  2. Uses SearchTool to find relevant tools
  3. System presents top 15 matching tools
  4. Agent selects the most appropriate tool
  5. Selected tool becomes available for use

Best Practices​

  • Write clear, detailed descriptions for all tools to improve search accuracy
  • You can adjust state descriptions to better suit your specific needs
  • Test the tool selection process with various user requests

Tool Confirmation Methods​

For critical actions, use confirmation methods to avoid hallucinated tool calls. Two confirmation methods are available:

Import Statement​

# Import special methods
from src.flow.tool_flow_instances import confirmation, email_confirmation

Standard Confirmation​

async def confirmation(
    message: str,
    flow_config: FlowConfig,
    confirmation_code: str | None = None
) -> tuple[bool, str | None]:

Parameters:​

  • message: str – Message displayed to the user alongside a Confirm button.
  • flow_config: FlowConfig – The flow configuration of the current session.
  • confirmation_code: str | None = None – Internal parameter used by email_confirmation. Do not set manually.

Returns:​

  • bool: True if user confirmed, False otherwise
  • str | None: User's reply (may be None if user just clicked Confirm)

Email Confirmation​

async def email_confirmation(
    subject: str,
    message: str,
    format_email_fn: Callable,
    flow_config: FlowConfig,
    **kwargs
) -> tuple[bool, str | None]:

This variant sends a confirmation code via email that the user must enter in the chat.

Parameters:​

  • subject: str – Email subject line
  • message: str – Message explaining the need to confirm via emailed code
  • format_email_fn: Callable – Function that formats the email body (accepts **kwargs)
  • flow_config: FlowConfig – Current session's flow configuration
  • **kwargs – Additional arguments forwarded to format_email_fn

Returns:​

A tuple:

  • bool: True if the user entered the correct code, False otherwise.
  • str | None: The user’s response to the confirmation message.