Tools and Skills: Extending Agent Capabilities

Tools are the primary way for your FlameTree agents to interact with external systems and perform actions beyond simple conversation. Think of tools as specific capabilities you give your agent - like sending emails, creating support tickets, or checking information in databases.

Prerequisites

• Basic understanding of FlameTree AI agents
• Familiarity with YAML configuration
• Python programming knowledge for custom tool implementation
• Access to FlameTree portal for plugin management

Key Concepts

What are Tools?

• Tools are actions: Each tool represents one specific action your AI agent can trigger during a conversation. It consists of:
  • YAML description (within a plugin)
  • Python implementation — a function that the AI agent calls when invoking the tool
• Agent-initiated: The agent decides when to use a tool based on the conversation context
• External interactions: Tools connect your agent to APIs, databases, and other systems

Common Tool Uses

• Send templated messages with buttons
• Create tickets in support systems (Jira, ServiceNow, etc.)
• Check customer information in databases
• Schedule appointments in calendars
• Send emails or SMS messages
• Transfer conversations to human operators

Tools vs Skills: Understanding the Difference

While both Tools and Skills extend agent capabilities, they serve different purposes:

Tools:

• Called by the agent during conversation when needed
• Agent decides when to use them based on context
• Appear in workflow's available_tools section
• Example: "Create a support ticket when customer reports an issue"

Skills:

• Executed automatically at specific points
• Triggered by system events (session start/end, state transitions)
• Configured in init_skills or final_skills sections
• Example: "Load customer data when conversation starts"

Simple Rule: If the agent needs to decide when to use it, it's a Tool. If it happens automatically, it's a Skill.

Creating Tools

Basic Plugin Structure

Tools are defined in Plugin files (YAML format) that contain both the tool configuration and reference to its implementation code.

kind: Plugin
name: Customer Support Tools
description: Tools for customer service operations
dependencies:
  - customer_tools_impl.py  # Python file with tool implementations
tools:
  - kind: Tool
    object_name: CreateSupportTicket
    name: CreateSupportTicket
    description: Creates a support ticket when customer reports an issue
    parameters:
      - name: issue_summary
        type: string
        description: Brief summary of the customer's issue
      - name: issue_details
        type: string
        description: Detailed description of the problem
    implementation: customer_tools_impl.create_ticket

Tool Configuration Fields

Each tool requires the following fields:

Required Fields:

• kind: Always "Tool"
• object_name: Unique identifier for the tool (no spaces, use PascalCase)
• name: Name the agent sees and uses
• description: Clear explanation of what the tool does
• parameters: List of inputs the tool needs (can be empty list [])
• implementation: Reference to the Python function

Parameter Fields:

• name: Parameter identifier
• type: Data type (string, integer, boolean, etc.)
• description: What this parameter should contain
• optional: Whether the parameter is required (default: false)

How to define and receive tool parameters:

If a tool needs input (e.g., email, ID, dates), specify them clearly in the parameters list. Each parameter must include:

parameters:  
  - name: email    
    type: string    
    description: "Email address to send the notification to"  
  - name: customer_name    
    type: string    
    description: "Customer name"

All YAML parameters are automatically passed to the Python function as named arguments (**kwargs).

Tool Implementation

Tool implementations are Python functions that perform the actual work. Here's a simple example:

async def create_ticket(issue_summary: str, issue_details: str, **kwargs):
    # Tool logic here
    # Access to conversation data through kwargs
    
    # Return a message that will be shown to the agent
    return f"Support ticket created with ID: TICKET-123"

Important: The function must:

• Be async (use async def)
• Accept parameters matching those defined in YAML
• Accept **kwargs for system parameters
• Return a string describing the result

Standard Arguments Passed to Tools

When an LLM agent triggers a tool, it passes data into a Python function using named arguments. All arguments must be explicitly named.

Standard arguments passed to tools:

Argument	Purpose
agent_name	AI Agent name
raw_agent_answer	Raw response from the LLM
knowledge_vdb	Vector knowledge base
hip	Shared dictionary for tool interaction
scratchpad	AI Agent action history
conversation_memory	Conversation history
system_parameters	Session-related constants
flow_config, agent_config	Current process and AI agent configurations

Complete Tool Example: RetrieveMenu

This example shows a tool that extracts data from an external text file located in the AI agent's resources.

YAML Definition:

- kind: Tool  
  object_name: RetrieveMenu  
  name: retrieve_menu  
  description: Retrieves positions in the restaurant's menu available for ordering in advance  
  parameters: []  
  implementation: restaurant_tools.retrieve_menu

Field Explanation:

Field	Description
object_name	Unique system name of the tool (RetrieveMenu)
name	Name visible to the LLM agent (retrieve_menu)
description	Short description of what the tool does (without usage instructions)
parameters	Empty list — the tool doesn't require additional input
implementation	Reference to the Python function (restaurant_tools.retrieve_menu)

Python Implementation:

import os
from pathlib import Path

async def retrieve_menu(**kwargs) -> str:
    available_menu = (Path(os.environ["RESOURCE_PATH"]) / "restaurant_menu.txt").read_text()
    if available_menu:
        return f"Positions available for ordering in advance: {available_menu}"
    return "No positions are available for ordering in advance right now"

Key points:

• Uses the RESOURCE_PATH environment variable to locate AI agent resources
• Loads content from restaurant_menu.txt
• Returns menu items or fallback message

Example contents of restaurant_menu.txt:

Salads: Greek salad, Caesar salad.
Greek starters: hummus, tzatziki, olives, fried halloumi.
Tartare: tuna tartare, shrimp tartare.
Ceviche: salmon ceviche, tuna ceviche.
Drinks: still and sparkling water.
Soft drinks: Coca-Cola, Coca-Cola Light, Coca-Cola Zero, apple juice, orange juice, tomato juice.

Overall Tool Flow for RetrieveMenu:

LLM agent → Chooses the retrieve_menu tool
     ↓
retrieve_menu function reads restaurant_menu.txt
     ↓
Generates a response with available menu items
     ↓
Sends the result to the user

Using Tools in Workflows

Tools must be explicitly made available to agents in specific workflow states:

- 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

Key Points:

• Tools are state-specific - only available in states where they're listed
• The agent will only see and use tools in available_tools
• Include clear instructions in the state description about when to use each tool
• SingleStatefulOutboundAgent is the system name of the AI agent type

How to Use Tools

To allow an LLM agent to use a built-in tool (e.g., SendChatMessage, FinishSession, SingleSearchFaq), you need to:

1. Specify the tool in the available_tools section of the YAML workflow

Each workflow state must explicitly list the tools available to the AI agent in that state.

Example:

available_tools:
  SingleStatefulOutboundAgent:
    - SendChatMessage
    - FinishSession
    - SingleSearchFaq

This determines which tools the AI agent is allowed to invoke during response generation.

2. AI Agent instructions must lead to tool invocation

The AI agent chooses the appropriate tool based on the current task and the prompt description. If the correct tool is not available, the LLM won't be able to call it, even if it's implemented server-side.

3. Custom tools must be defined in a Skill Group

If you're using a custom tool, it must be defined in the YAML plugin file uploaded in a Skill Group:

tools:
  - name: SendLeadNotification
    description: "Send email to manager after form submission"
    implementation: tools.send_lead_notification
    parameters:
      - name: email
        type: string
        description: "Recipient's email address"

Important: The tool name is arbitrary and should be clear to the LLM agent. This name is used in available_tools and when generating actions. It doesn't need to match the Python object_name or function name.

Additional Tool Configuration Options

• init_skills — triggered on state entry
• finalization_skills — triggered on state exit
• attached_tools — triggered during transitions

Example of attached_tools:

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

attached_tools is a special field inside state_scenarios, used to trigger tools during state transitions, not within the state itself.

System Tools Reference

Core Communication Tools

SendChatMessage

• Purpose: Sends a text message from the AI agent to the user through a connected channel (chat, messenger, etc.)
• Parameters:
  • stylized_message — a string with the message to display to the user
• Note: This is the basic tool for any text communication. Used in almost every state where the AI agent responds with text.

SendChatMessageFormSync

• Purpose: Sends a message and pauses state execution until all required form fields are completed
• Parameters:
  • stylized_message — message prompting the user to provide information (e.g., email, name, budget)
• Note: Used when it's important to wait for full form completion before proceeding. Unlike standard SendChatMessage, this tool waits for all FormInfoField values before returning control to the AI agent.

FinishSession

• Purpose: Ends the current user session. Can be used as a logical conclusion or during escalation to a human agent
• Parameters:
  • last_message — final message shown to the user before ending the session
• Note: Recommended for any scenario involving session closure. Lets the AI agent explicitly notify the user that the session has ended and halts further processing.

Knowledge Base Tools

SingleSearchFAQ

• Purpose: Performs a search in the vector-based Knowledge Base using the user's query. Returns a relevant text fragment that can be included in the response
• Parameters:
  • query — the user's text query
• Note: This is the primary tool for Retrieval-Augmented Generation (RAG). Without this tool, the AI agent cannot access the knowledge base. The SingleSearchFaq tool is used only for searching in the Knowledge Base (vector-based RAG). For using the Fast Access Knowledge Base (FAQ), no tools are required, as the content is embedded directly into the agent's prompt.

Interactive Tools

ProvideOptionButtons

• Purpose: Displays response options as buttons when the AI agent cannot select one automatically
• How it works: Takes an observation — a list of options returned by other tools (e.g., GetAvailableSlots) — and shows them to the user
• Example usage: Instead of having the LLM choose a delivery city from a list, ProvideOptionButtons gives the user the choice

SearchTool

• Purpose: Performs search and automatic selection of the most suitable tool for the user's current request
• How it works: Based on the input query and connected Skill Groups, SearchTool determines the most relevant tool and initiates its call. It can also trigger an associated skill if defined in the plugin
• Why it matters: Enables dynamic AI agent behavior — no need to hardcode specific actions in every state. The platform finds the right tool automatically

Calendar Tools

CreateEvent

• Purpose: Schedules a meeting in an integrated calendar (e.g., Google Calendar, Outlook)
• Parameters:
  • start_time — meeting start time
  • end_time — meeting end time
  • attendees — list of participants

CancelEvent

• Purpose: Cancels a previously scheduled meeting
• Parameters:
  • event_id — meeting identifier

GetAvailableSlots

• Purpose: Returns a list of available appointment slots
• Parameters:
  • date_range — date range to search within

CheckSlotAvailable

• Purpose: Checks if a specific time slot is available
• Parameters:
  • start_time
  • end_time

Summary Table of Built-in Tools

Tool Name	Purpose	Status
SendChatMessage	Sends a text message	Core tool
SendChatMessageFormSync	Sends message + waits for form completion	Form handling
FinishSession	Ends the session	Recommended
SingleSearchFAQ	Knowledge base search (RAG)	Required with KB
ProvideOptionButtons	Response options as buttons	System tool (UI)
SearchTool	Automatic tool selection	System tool (routing)

Best Practices

Writing Tool Descriptions

Do:

• Describe what the tool does, not when to use it
• Be specific about the tool's action
• Use clear, simple language

Don't:

• Include usage instructions in the description
• Make descriptions too long or complex

Good Example:

description: Creates a support ticket in Jira with the provided issue details

Poor Example:

description: Use this when customer has a problem and needs help. This tool will create a ticket but only if the issue is serious enough.

When to Use Tools Instructions

Put instructions about when to use tools in the workflow state description, not in the tool description:

description: |
  ## Tool Usage Guidelines
  - Use CreateTicket only after confirming the issue with the customer
  - Always get customer contact information before creating a ticket

Naming Conventions

• object_name: PascalCase, no spaces (e.g., SendEmailTemplate)
• name: Same as object_name for consistency
• Parameters: lowercase with underscores (e.g., customer_email)

Design Principles

1. Separate logic and actions — use skills for logic, tools for concrete actions
2. Describe only what the tool does — usage conditions go in the workflow
3. Design tools and skills as reusable components
4. Avoid duplicate object_name values — they will cause conflicts

Handling Similar Tools

When you have similar tools (e.g., "Get Active Cards" vs "Get Inactive Cards"):

• Keep descriptions similar in structure
• Clearly highlight the key difference
• Maintain consistent parameter naming

Complete Example: Customer Support Tools

Plugin Configuration (support_plugin.yaml)

kind: Plugin
name: Customer Support Plugin
description: Tools for customer service operations
dependencies:
  - support_impl.py

tools:
  - kind: Tool
    object_name: CreateJiraTicket
    name: CreateJiraTicket
    description: Creates a Jira ticket for customer issues
    parameters:
      - name: issue_topic
        type: string
        description: Brief summary of the issue (max 100 characters)
      - name: issue_description
        type: string
        description: Detailed description provided by the customer
    implementation: support_impl.create_jira_ticket

  - kind: Tool
    object_name: SendFeedbackSurvey
    name: SendFeedbackSurvey
    description: Sends a satisfaction survey to the customer
    parameters: []
    implementation: support_impl.send_survey

  - kind: Tool
    object_name: TransferToOperator
    name: TransferToOperator
    description: Transfers the conversation to a human operator
    parameters:
      - name: reason
        type: string
        description: Reason for transfer
    implementation: support_impl.transfer_chat

Implementation (support_impl.py)

import aiohttp
from loguru import logger

async def create_jira_ticket(issue_topic: str, issue_description: str, 
                           flow_config, **kwargs):
    # Get customer information from session
    env_params = flow_config.environment_parameters
    customer_name = env_params.get("customer_name", "Unknown")
    customer_email = env_params.get("customer_email", "")
    
    # Create ticket (simplified example)
    ticket_data = {
        "summary": issue_topic,
        "description": f"Customer: {customer_name}\n\n{issue_description}",
        "email": customer_email
    }
    
    # In real implementation, call Jira API here
    logger.info(f"Creating ticket: {issue_topic}")
    
    return f"Support ticket created successfully. A team member will contact you within 24 hours."

async def send_survey(**kwargs):
    # Send survey logic here
    return "Satisfaction survey sent to your email. Thank you for your feedback!"

async def transfer_chat(reason: str, stack, **kwargs):
    # Add transfer message to conversation
    transfer_msg = f"Transferring to human operator. Reason: {reason}"
    
    # In real implementation, trigger operator handover
    
    return "Connecting you with a human operator. Please wait..."

Using in Workflow

- process_name: SupportProcess
  name: MainSupport
  kind: StateConfig
  description: |
    ## Your role
    Help customers with their issues and create tickets when needed.
    
    ## When to use tools
    - Use CreateJiraTicket after gathering all issue details
    - Use SendFeedbackSurvey at the end of successful interactions
    - Use TransferToOperator if customer explicitly asks for human help
    
  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage
      - CreateJiraTicket
      - SendFeedbackSurvey
      - TransferToOperator

Deploying Tools

1. Create Plugin YAML with tool configurations
2. Create Python implementation with your tool functions
3. Upload Plugin to FlameTree portal
4. Add tools to workflow in appropriate states
5. Test thoroughly in Playground before production

Common Issues & Solutions

Tool Not Available in Agent

Problem: Agent cannot see or use the tool despite being configured.

Solution:

1. Verify the tool is declared in available_tools for the current state
2. Check that the Skill Group containing the tool is connected to the agent
3. Ensure the tool name matches exactly (case-sensitive)
4. Restart the agent after making changes

Tool Execution Fails

Problem: Tool is called but returns errors or doesn't work.

Solution:

1. Check the Python implementation for syntax errors
2. Verify all required parameters are properly defined
3. Ensure the implementation function is async
4. Check agent logs for specific error messages

Knowledge Base Tools Not Working

Problem: Agent cannot search knowledge base content.

Solution:

1. Add SingleSearchFAQ to available_tools
2. Ensure knowledge base is built (not in "Modified" status)
3. Verify knowledge base is connected to the agent
4. Check that the knowledge base contains indexed content

FAQ

How to connect a tool to an AI agent?

To enable an AI agent to use tools, you must:

1. Connect a Skill Group to the AI agent (in the agent's Skill Groups section)
2. Declare the tool in the workflow's available_tools section for each state where it should be available
3. Ensure naming consistency - the tool name must match the object_name in the Skill Group YAML

What indentation rules apply to tool configurations?

• Only spaces are allowed; tabs are prohibited
• Use 2 spaces per indentation level consistently
• All items on the same level must have the same indentation
• Do not mix different numbers of spaces for indentation

How to connect a knowledge base to use search tools?

1. Create the Knowledge Base and build it
2. Link it to the AI agent in the Database section
3. Add the search tool (SingleSearchFAQ) to the workflow's available_tools

Note: Fast Access KB does not require a tool call, but RAG (vector knowledge base) requires the explicit SingleSearchFAQ tool.

Why does my tool work in one state but not another?

Tools are state-specific in FlameTree workflows. You must declare each tool in the available_tools section of every state where the agent should have access to it.

What should be configured in the AI agent to enable operator handoff?

Example workflow that implements operator handoff:

- process_name: AssistanceProcess
  name: AutonomousAssistance
  init_state: true
  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage
      - FinishSession
  state_scenarios:
    - next_state: CopilotAssistance
      transition_name: transfer_to_partnership_manager

- process_name: AssistanceProcess
  name: CopilotAssistance
  available_tools:
    SingleStatefulOutboundAgent:
      - SendChatMessage

The agent operates through a two-step process:

• AutonomousAssistance: Agent independently handles inquiries and transfers when needed
• CopilotAssistance: Agent works in copilot mode, suggesting drafts to the operator

How to format links so they appear as text, hiding the actual URL?

Use standard Markdown link formatting:

[link-text](https://example.com)

Example:

[Official Meta Business Page](https://business.facebook.com/)

FlameTree agents render responses in Markdown by default, including link formatting.

Related Resources

• Workflow Configuration Guide
• Knowledge Base Setup