Skip to main content

​
Overview

The Agent API provides tools that extend model capabilities beyond their training data. Tools must be explicitly configured in your API request—once enabled, models autonomously decide when to use them based on your instructions.
TypeToolsUse Case
Built-inweb_search, fetch_urlReal-time web information retrieval
CustomYour functionsConnect to databases, APIs, business logic
Enable tools by adding them to the tools array in your request: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.4",
    input="What are the latest AI developments?",
    tools=[
        {"type": "web_search"},
        {"type": "fetch_url"}
    ],
    instructions="Use web_search for current information. Use fetch_url when you need full article content."
)

print(response.output_text)

​
Web Search Tool

The web_search tool allows models to perform web searches with advanced filtering capabilities. Use it when you need current information, news, or data beyond the model’s training cutoff. Pricing: $5.00 per 1,000 search calls ($0.005 per search), plus token costs.

​
Example

from perplexity import Perplexity

client = Perplexity()

# Real-time: breaking news or live events
response = client.responses.create(
    model="openai/gpt-5.4",
    input="What is happening right now in the markets?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_recency_filter": "hour"
            }
        }
    ],
    instructions="Search for live market news."
)

print(response.output_text)

# Recent academic publications
response = client.responses.create(
    model="openai/gpt-5.4",
    input="What are recent academic findings on renewable energy?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": ["nature.com", "science.org", ".edu"],
                "search_recency_filter": "month"
            }
        }
    ],
    instructions="Search for recent English-language academic publications."
)

print(response.output_text)

​
Key Parameters

FilterTypeDescriptionLimit
search_domain_filterArray of stringsFilter by specific domains (allowlist or denylist with - prefix)Max 20 domains
search_recency_filterStringFilter by time period: "hour", "day", "week", "month", "year". Use hour for real-time data such as breaking news or live events.-
search_after_dateStringFilter results published after this date (format: "M/D/YYYY")-
search_before_dateStringFilter results published before this date (format: "M/D/YYYY")-
max_tokens_per_pageIntegerControl the amount of content retrieved per search result-
Use - prefix to exclude domains: "-reddit.com" excludes Reddit from results. Lower max_tokens_per_page to reduce context token costs.

​
Fetch URL Tool

The fetch_url tool fetches and extracts content from specific URLs. Use it when you need the full content of a particular web page, article, or document rather than search results. Pricing: $0.50 per 1,000 requests ($0.0005 per fetch), plus token costs.

​
Example

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.4",
    input="Summarize the content at https://example.com/article",
    tools=[
        {
            "type": "fetch_url"
        }
    ],
    instructions="Use fetch_url to retrieve and summarize the article."
)

print(response.output_text)

​
When to Use

Use fetch_url when…Use web_search when…
You have a specific URLYou need to find relevant pages
You need full page contentYou need snippets from multiple sources
Analyzing a particular documentResearching a broad topic
Verifying specific claimsFinding current news or events
Combine web_search and fetch_url for comprehensive research: search to find relevant pages, then fetch full content from the most relevant results.

​
Function Calling

Function calling allows you to define custom functions that models can invoke during a conversation. Unlike built-in tools, custom functions let you connect the model to your own systems—databases, APIs, business logic, or any external service. Pricing: No additional cost (standard token pricing applies).

​
How It Works

Function calling follows a multi-turn conversation pattern:
  1. Define functions with names, descriptions, and parameter schemas
  2. Send your prompt with function definitions
  3. Model returns a function_call item if it needs to call a function
  4. Execute the function in your code
  5. Return results as a function_call_output item
  6. Model uses the results to generate its final response

​
Example

from perplexity import Perplexity
import json

client = Perplexity()

# Define your function tools
tools = [
    {
        "type": "function",
        "name": "get_horoscope",
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius"
                }
            },
            "required": ["sign"]
        }
    }
]

# Your actual function implementation
def get_horoscope(sign: str) -> str:
    return f"{sign}: Today brings new opportunities for growth."

# Send initial request with tools
response = client.responses.create(
    model="openai/gpt-5.4",
    tools=tools,
    input="What is my horoscope? I am an Aquarius."
)

# Process the response and handle function calls
next_input = [item.model_dump() for item in response.output]

for item in response.output:
    if item.type == "function_call":
        # Execute the function
        args = json.loads(item.arguments)
        result = get_horoscope(args["sign"])

        # Add the function result to the input
        next_input.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"horoscope": result})
        })

# Send the function results back to get the final response
final_response = client.responses.create(
    model="openai/gpt-5.4",
    input=next_input
)

print(final_response.output_text)

​
Key Properties

PropertyTypeRequiredDescription
typestringYesMust be "function"
namestringYesFunction name the model will use to call it
descriptionstringYesClear description of what the function does and when to use it
parametersobjectYesJSON Schema defining the function’s parameters
strictbooleanNoEnable strict schema validation
The arguments field in function calls is a JSON string, not a parsed object. Always use json.loads() (Python) or JSON.parse() (JavaScript) to parse it.
Write clear, specific function descriptions. The model uses these to decide when to call each function. Include details about what the function returns and any constraints.

​
Next Steps

Agent API Quickstart

Get started with the Agent API.

Models

Explore direct model selection and third-party models.

API Reference

View complete endpoint documentation.

Output Control

Configure streaming responses and structured outputs with JSON schema.