> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Function Tools

> Make server-side API calls during conversations to extend your agent with external data and actions

Function tools allow your agent to make HTTP requests to external APIs during a conversation. Use them to look up data, perform actions, or integrate with your backend systems.

## How They Work

```
User speaks → Agent decides to call a tool → Server makes API request →
Response returned → Agent uses the data in its reply
```

Function tools run server-side, so they work on both phone and web deployments.

## Creating a Function Tool

1. Navigate to the **Tools** section in your dashboard
2. Click **Create Tool**
3. Select **API Request** as the tool type
4. Configure the tool:

### Basic Configuration

* **Name**: A clear name the LLM uses to understand when to call the tool (e.g., `check_order_status`)
* **Description**: Explain what the tool does — the LLM uses this to decide when to invoke it
* **URL**: The API endpoint to call
* **Method**: GET, POST, PUT, PATCH, or DELETE

### Parameters

Define the parameters the agent should extract from the conversation and pass to the API:

```json theme={null}
{
  "order_id": {
    "type": "string",
    "description": "The customer's order ID"
  },
  "include_tracking": {
    "type": "boolean",
    "description": "Whether to include tracking information"
  }
}
```

The agent will extract these values from the conversation context before making the call.

### Authentication

* **None**: No authentication headers.
* **Bearer Token**: Prepends `Bearer ` to the provided string and sends it in the `Authorization` header.
* **Token**: Prepends `Token ` to the provided string.
* **Basic Auth**: Enter a Username and Password; the system automatically Base64-encodes them into a single string (`user:pass`) and sends it as a `Basic` auth header.
* **Custom Headers**: Manually define any other header name and value pair.

### Asynchronous Execution (Async)

Toggle the **Async** setting to control how the agent waits for a response:

* **Async OFF (Synchronous)**: The agent waits for the API response before proceeding. Use this when the agent needs the response data to decide what to say next or how to route the flow.
* **Async ON (Asynchronous)**: The agent sends the request and immediately continues the conversation or moves to the next node without waiting. Use this for "fire-and-forget" actions like sending an SMS, starting a background export, or other slow background processes.

### Timeout

Set a maximum wait time for the API response (in milliseconds). If the API doesn't respond in time, the tool call fails gracefully.

## Using Function Tools

### In Single Prompt Agents

The agent decides when to call the tool based on the conversation and the tool's description. The API response (string or JSON) is sent back to the LLM, which uses it naturally in its next reply.

**Example**: A customer asks "Where's my order?" → Agent calls `check_order_status` with the order ID → API returns tracking info → Agent relays the information conversationally.

### In Flow Agents

Function tools are used via [Tool Nodes](/agents/flow-agent/nodes/tool-node). You can:

* Extract specific values from the response using output mapping
* Route the conversation based on extracted values using transitions
* Use extracted data in subsequent nodes via variables

## Examples

### Order Status Lookup

```
Name: check_order_status
Description: Check the current status and tracking information for a customer order
Method: GET
URL: https://api.yourstore.com/orders/{order_id}
Parameters:
  - order_id (string, required): The order ID to look up
```

### Appointment Booking

```
Name: book_appointment
Description: Book an appointment for the customer at the requested date and time
Method: POST
URL: https://api.yourservice.com/appointments
Parameters:
  - date (string, required): Appointment date in YYYY-MM-DD format
  - time (string, required): Appointment time in HH:MM format
  - service_type (string, required): Type of service requested
```

### Customer Lookup

```
Name: find_customer
Description: Look up a customer by their phone number or email address
Method: GET
URL: https://api.yourcrm.com/customers/search
Parameters:
  - phone (string): Customer's phone number
  - email (string): Customer's email address
```

## Related

<CardGroup cols={2}>
  <Card title="Tools Overview" href="/agents/tools/introduction">
    Overview of all tool types
  </Card>

  <Card title="Tool Node (Flow Agent)" href="/agents/flow-agent/nodes/tool-node">
    Using function tools in flow agents
  </Card>
</CardGroup>