Tools

any_agent.tools

a2a_tool(url, toolname=None, http_kwargs=None)

Perform a query using A2A to another agent (synchronous version).

Parameters:

Name	Type	Description	Default
url	str	The url in which the A2A agent is located.	required
toolname	str	The name for the created tool. Defaults to call_{agent name in card}. Leading and trailing whitespace are removed. Whitespace in the middle is replaced by _.	None
http_kwargs	dict	Additional kwargs to pass to the httpx client.	None

Returns:

Type	Description
Callable[[str, Optional[str], Optional[str]], str]	A sync Callable that takes a query and returns the agent response.

Source code in src/any_agent/tools/a2a.py

def a2a_tool(
    url: str, toolname: Optional[str] = None, http_kwargs: dict[str, Any] | None = None
) -> Callable[[str, Optional[str], Optional[str]], str]:
    """Perform a query using A2A to another agent (synchronous version).

    Args:
        url (str): The url in which the A2A agent is located.
        toolname (str): The name for the created tool. Defaults to `call_{agent name in card}`.
            Leading and trailing whitespace are removed. Whitespace in the middle is replaced by `_`.
        http_kwargs (dict): Additional kwargs to pass to the httpx client.

    Returns:
        A sync `Callable` that takes a query and returns the agent response.

    """
    if not a2a_tool_available:
        msg = "You need to `pip install 'any-agent[a2a]'` to use this tool"
        raise ImportError(msg)

    # Fetch the async tool upfront to get proper name and documentation (otherwise the tool doesn't have the right name and documentation)
    async_tool = run_async_in_sync(a2a_tool_async(url, toolname, http_kwargs))

    def sync_wrapper(
        query: str, task_id: Optional[str] = None, context_id: Optional[str] = None
    ) -> Any:
        """Execute the A2A tool query synchronously."""
        return run_async_in_sync(async_tool(query, task_id, context_id))

    # Copy essential metadata from the async tool
    sync_wrapper.__name__ = async_tool.__name__
    sync_wrapper.__doc__ = async_tool.__doc__

    return sync_wrapper

a2a_tool_async(url, toolname=None, http_kwargs=None) async

Perform a query using A2A to another agent.

Parameters:

Name	Type	Description	Default
url	str	The url in which the A2A agent is located.	required
toolname	str	The name for the created tool. Defaults to call_{agent name in card}. Leading and trailing whitespace are removed. Whitespace in the middle is replaced by _.	None
http_kwargs	dict	Additional kwargs to pass to the httpx client.	None

Returns:

Type	Description
Callable[[str, Optional[str], Optional[str]], Coroutine[Any, Any, dict[str, Any]]]	An async Callable that takes a query and returns the agent response.

Source code in src/any_agent/tools/a2a.py

async def a2a_tool_async(
    url: str, toolname: Optional[str] = None, http_kwargs: dict[str, Any] | None = None
) -> Callable[[str, Optional[str], Optional[str]], Coroutine[Any, Any, dict[str, Any]]]:
    """Perform a query using A2A to another agent.

    Args:
        url (str): The url in which the A2A agent is located.
        toolname (str): The name for the created tool. Defaults to `call_{agent name in card}`.
            Leading and trailing whitespace are removed. Whitespace in the middle is replaced by `_`.
        http_kwargs (dict): Additional kwargs to pass to the httpx client.

    Returns:
        An async `Callable` that takes a query and returns the agent response.

    """
    if not a2a_tool_available:
        msg = "You need to `pip install 'any-agent[a2a]'` to use this tool"
        raise ImportError(msg)

    if http_kwargs is None:
        http_kwargs = {}

    # Default timeout in httpx is 5 seconds. For an agent response, the default should be more lenient.
    if "timeout" not in http_kwargs:
        http_kwargs["timeout"] = 30.0

    async with httpx.AsyncClient(
        follow_redirects=True, **http_kwargs
    ) as resolver_client:
        a2a_agent_card: AgentCard = await (
            A2ACardResolver(httpx_client=resolver_client, base_url=url)
        ).get_agent_card()

    # NOTE: Use Optional[T] instead of T | None syntax throughout this module.
    # Google ADK's _parse_schema_from_parameter function has compatibility
    # with the traditional Optional[T] syntax for automatic function calling.
    # Using T | None syntax causes"Failed to parse the parameter ... for automatic function calling"
    async def _send_query(
        query: str, task_id: Optional[str] = None, context_id: Optional[str] = None
    ) -> dict[str, Any]:
        async with httpx.AsyncClient(follow_redirects=True) as query_client:
            client = A2AClient(httpx_client=query_client, agent_card=a2a_agent_card)
            send_message_payload = SendMessageRequest(
                id=str(uuid4()),
                params=MessageSendParams(
                    message=Message(
                        role=Role.user,
                        parts=[Part(root=TextPart(text=query))],
                        # the id is not currently tracked
                        message_id=str(uuid4().hex),
                        task_id=task_id,
                        context_id=context_id,
                    )
                ),
            )
            # TODO check how to capture exceptions and pass them on to the enclosing framework
            response = await client.send_message(
                send_message_payload, http_kwargs=http_kwargs
            )

            if not response.root:
                msg = (
                    "The A2A agent did not return a root. Are you using an A2A agent not managed by any-agent? "
                    "Please file an issue at https://github.com/mozilla-ai/any-agent/issues so we can help."
                )
                raise ValueError(msg)

            if isinstance(response.root, JSONRPCErrorResponse):
                response_dict = {
                    "error": response.root.error.message,
                    "code": response.root.error.code,
                    "data": response.root.error.data,
                }
            elif isinstance(response.root, SendMessageSuccessResponse):
                # Task
                if isinstance(response.root.result, Task):
                    task = response.root.result
                    response_dict = {
                        "timestamp": task.status.timestamp,
                        "status": task.status.state,
                    }
                    if task.status.message:
                        response_dict["task_id"] = task.status.message.task_id
                        response_dict["context_id"] = task.status.message.context_id
                        response_dict["message"] = {
                            " ".join(
                                [
                                    part.root.text
                                    for part in task.status.message.parts
                                    if isinstance(part.root, TextPart)
                                ]
                            )
                        }
                # Message
                else:
                    response_dict = {
                        "message": {
                            " ".join(
                                [
                                    part.root.text
                                    for part in response.root.result.parts
                                    if isinstance(part.root, TextPart)
                                ]
                            )
                        },
                        "task_id": response.root.result.task_id,
                    }
            else:
                msg = (
                    "The A2A agent did not return a error or a result. Are you using an A2A agent not managed by any-agent? "
                    "Please file an issue at https://github.com/mozilla-ai/any-agent/issues so we can help."
                )
                raise ValueError(msg)

            return response_dict

    new_name = toolname or a2a_agent_card.name
    new_name = re.sub(r"\s+", "_", new_name.strip())
    _send_query.__name__ = f"call_{new_name}"
    _send_query.__doc__ = f"""{a2a_agent_card.description}
        Send a query to the A2A hosted agent named {a2a_agent_card.name}.

        Agent description: {a2a_agent_card.description}

        Args:
            query (str): The query to send to the agent.
            task_id (str, optional): Task ID for continuing an incomplete task. Use the same
                task_id from a previous response with TaskState.input_required to resume the task. If you want to start a new task, you should not provide a task id.
            context_id (str, optional): Context ID for conversation continuity. Provides the
                agent with conversation history. Omit to start a fresh conversation. If you want to start a new conversation, you should not provide a context id.

        Returns:
            dict: Response from the A2A agent containing:
                - For successful responses: task_id, context_id, timestamp, status, and message
                - For errors: error message, code, and data

        Note:
            If TaskState is terminal (completed/failed), do not reuse the same task_id.
    """
    return _send_query

ask_user_verification(query)

Asks user to verify the given query.

Parameters:

Name	Type	Description	Default
query	str	The question that requires verification.	required

Source code in src/any_agent/tools/user_interaction.py

def ask_user_verification(query: str) -> str:
    """Asks user to verify the given `query`.

    Args:
        query: The question that requires verification.

    """
    return input(f"{query} => Type your answer here:")

prepare_final_output(output_type, instructions=None)

Prepare instructions and tools for structured output, returning the function directly.

Parameters:

Name	Type	Description	Default
output_type	type[BaseModel]	The Pydantic model type for structured output	required
instructions	str | None	Original instructions to modify	None

Returns:

Type	Description
tuple[str, Callable[[str], dict[str, str | bool | dict[str, Any] | list[Any]]]]	Tuple of (modified_instructions, final_output_function)

Source code in src/any_agent/tools/final_output.py

def prepare_final_output(
    output_type: type[BaseModel], instructions: str | None = None
) -> tuple[str, Callable[[str], dict[str, str | bool | dict[str, Any] | list[Any]]]]:
    """Prepare instructions and tools for structured output, returning the function directly.

    Args:
        output_type: The Pydantic model type for structured output
        instructions: Original instructions to modify

    Returns:
        Tuple of (modified_instructions, final_output_function)

    """
    tool_name = "final_output"
    modified_instructions = instructions or ""
    modified_instructions += (
        f"You must call the {tool_name} tool when finished."
        f"The 'answer' argument passed to the {tool_name} tool must be a JSON string that matches the following schema:\n"
        f"{output_type.model_json_schema()}"
    )

    def final_output_tool(
        answer: str,
    ) -> dict[str, str | bool | dict[str, Any] | list[Any]]:
        # First check if it's valid JSON
        try:
            parsed_answer = json.loads(answer)
        except json.JSONDecodeError as json_err:
            return {
                "success": False,
                "result": f"Invalid JSON format: {json_err}. Please fix the 'answer' parameter so that it is a valid JSON string and call this tool again.",
            }
        # Then validate against the Pydantic model
        try:
            output_type.model_validate_json(answer)
        except ValidationError as e:
            return {
                "success": False,
                "result": f"Please fix this validation error: {e}. The format must conform to {output_type.model_json_schema()}",
            }
        else:
            return {"success": True, "result": parsed_answer}

    # Set the function name and docstring
    final_output_tool.__name__ = tool_name
    final_output_tool.__doc__ = f"""This tool is used to validate the final output. It must be called when the final answer is ready in order to ensure that the output is valid.

    Args:
        answer: The final output that can be loaded as a Pydantic model. This must be a JSON compatible string that matches the following schema:
            {output_type.model_json_schema()}

    Returns:
        A dictionary with the following keys:
            - success: True if the output is valid, False otherwise.
            - result: The final output if success is True, otherwise an error message.

    """

    return modified_instructions, final_output_tool

search_tavily(query, include_images=False)

Perform a Tavily web search based on your query and return the top search results.

See https://blog.tavily.com/getting-started-with-the-tavily-search-api for more information.

Parameters:

Name	Type	Description	Default
query	str	The search query to perform.	required
include_images	bool	Whether to include images in the results.	False

Returns:

Type	Description
str	The top search results as a formatted string.

Source code in src/any_agent/tools/web_browsing.py

def search_tavily(query: str, include_images: bool = False) -> str:
    """Perform a Tavily web search based on your query and return the top search results.

    See https://blog.tavily.com/getting-started-with-the-tavily-search-api for more information.

    Args:
        query (str): The search query to perform.
        include_images (bool): Whether to include images in the results.

    Returns:
        The top search results as a formatted string.

    """
    if not tavily_available:
        msg = "You need to `pip install 'tavily-python'` to use this tool"
        raise ImportError(msg)
    api_key = os.getenv("TAVILY_API_KEY")
    if not api_key:
        return "TAVILY_API_KEY environment variable not set."
    try:
        client = TavilyClient(api_key)
        response = client.search(query, include_images=include_images)
        results = response.get("results", [])
        output = []
        for result in results:
            output.append(
                f"[{result.get('title', 'No Title')}]({result.get('url', '#')})\n{result.get('content', '')}"
            )
        if include_images and "images" in response:
            output.append("\nImages:")
            for image in response["images"]:
                output.append(image)
        return "\n\n".join(output) if output else "No results found."
    except Exception as e:
        return f"Error performing Tavily search: {e!s}"

search_web(query)

Perform a duckduckgo web search based on your query (think a Google search) then returns the top search results.

Parameters:

Name	Type	Description	Default
query	str	The search query to perform.	required

Returns:

Type	Description
str	The top search results.

Source code in src/any_agent/tools/web_browsing.py

def search_web(query: str) -> str:
    """Perform a duckduckgo web search based on your query (think a Google search) then returns the top search results.

    Args:
        query (str): The search query to perform.

    Returns:
        The top search results.

    """
    ddgs = DDGS()
    results = ddgs.text(query, max_results=10)
    return "\n".join(
        f"[{result['title']}]({result['href']})\n{result['body']}" for result in results
    )

send_console_message(user, query)

Send the specified user a message via console and returns their response.

Parameters:

Name	Type	Description	Default
query	str	The question to ask the user.	required
user	str	The user to ask the question to.	required

Returns:

Name	Type	Description
str	str	The user's response.

Source code in src/any_agent/tools/user_interaction.py

def send_console_message(user: str, query: str) -> str:
    """Send the specified user a message via console and returns their response.

    Args:
        query: The question to ask the user.
        user: The user to ask the question to.

    Returns:
        str: The user's response.

    """
    return Prompt.ask(f"{query}\n{user}")

show_final_output(answer)

Show the final answer to the user.

Parameters:

Name	Type	Description	Default
answer	str	The final answer.	required

Source code in src/any_agent/tools/user_interaction.py

def show_final_output(answer: str) -> str:
    """Show the final answer to the user.

    Args:
        answer: The final answer.

    """
    logger.info(f"Final output: {answer}")
    return answer

show_plan(plan)

Show the current plan to the user.

Parameters:

Name	Type	Description	Default
plan	str	The current plan.	required

Source code in src/any_agent/tools/user_interaction.py

def show_plan(plan: str) -> str:
    """Show the current plan to the user.

    Args:
        plan: The current plan.

    """
    logger.info(f"Current plan: {plan}")
    return plan

visit_webpage(url, timeout=30, max_length=10000)

Visits a webpage at the given url and reads its content as a markdown string. Use this to browse webpages.

Parameters:

Name	Type	Description	Default
url	str	The url of the webpage to visit.	required
timeout	int	The timeout in seconds for the request.	30
max_length	int	The maximum number of characters of text that can be returned (default=10000). If max_length==-1, text is not truncated and the full webpage is returned.	10000

Source code in src/any_agent/tools/web_browsing.py

def visit_webpage(url: str, timeout: int = 30, max_length: int = 10000) -> str:
    """Visits a webpage at the given url and reads its content as a markdown string. Use this to browse webpages.

    Args:
        url: The url of the webpage to visit.
        timeout: The timeout in seconds for the request.
        max_length: The maximum number of characters of text that can be returned (default=10000).
                    If max_length==-1, text is not truncated and the full webpage is returned.

    """
    try:
        response = requests.get(url, timeout=timeout)
        response.raise_for_status()

        markdown_content = markdownify(response.text).strip()  # type: ignore[no-untyped-call]

        markdown_content = re.sub(r"\n{2,}", "\n", markdown_content)

        if max_length == -1:
            return str(markdown_content)
        return _truncate_content(markdown_content, max_length)
    except RequestException as e:
        return f"Error fetching the webpage: {e!s}"
    except Exception as e:
        return f"An unexpected error occurred: {e!s}"