Skip to main content

Documentation Index

Fetch the complete documentation index at: https://polos.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

A research agent that searches the web using the Tavily API and asks users follow-up questions to refine its research. Combines createWebSearchTool with createAskUserTool for interactive, source-cited research.

​
Create the tools

from polos import (
    Agent, max_steps, MaxStepsConfig,
    create_web_search_tool, WebSearchToolConfig,
    create_ask_user_tool,
)

# Web search tool -- uses Tavily API via TAVILY_API_KEY env var.
# The API key is resolved lazily at call time, not at import time.
web_search = create_web_search_tool(
    WebSearchToolConfig(
        max_results=5,
        search_depth="basic",
        include_answer=True,
        approval="always",
    )
)

# Ask-user tool -- lets the agent ask the user for clarification
ask_user = create_ask_user_tool()

​
Define the agent

research_agent = Agent(
    id="research_agent",
    provider="anthropic",
    model="claude-sonnet-4-5",
    system_prompt=(
        "You are a research assistant with access to web search. "
        "When the user asks a question, search the web for current information and "
        "synthesize a well-sourced answer. Include URLs from your search results as references. "
        "If the user's question is ambiguous, use the ask_user tool to clarify before searching. "
        "You may perform multiple searches to gather comprehensive information. "
        "Always cite your sources with URLs in the final answer."
    ),
    tools=[web_search, ask_user],
    stop_conditions=[max_steps(MaxStepsConfig(count=30))],
)

​
How it works

  1. The agent receives a research question
  2. If the question is ambiguous, it uses ask_user to clarify — the workflow suspends until the user responds
  3. The agent searches the web with web_search (each search suspends for approval when approval: "always" is set)
  4. It may perform multiple searches to gather comprehensive information
  5. The final answer includes source URLs from the search results

​
Run it

git clone https://github.com/polos-dev/polos.git
cd polos/python-examples/20-web-search-agent
cp .env.example .env  # Add your POLOS_PROJECT_ID and API key
uv sync
python main.py
Requires a Tavily API key set as TAVILY_API_KEY in your .env file.
Open http://localhost:5173 to view your agents and workflows, run them from the UI, and see execution traces. Python example on GitHub | TypeScript example on GitHub