### Create Environment and Install Dev Dependencies

Source: https://github.com/mozilla-ai/any-agent/blob/main/AGENTS.md

Sets up a virtual environment and installs development dependencies using uv. Ensure Python 3.11+ is installed.

```bash
uv venv && source .venv/bin/activate && uv sync --dev --extra all
```

--------------------------------

### Install Any-Agent (Bare Bones)

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/index.md

Installs the core Any-Agent library, enabling support for TinyAgent.

```bash
pip install any-agent
```

--------------------------------

### Install Any-Agent

Source: https://github.com/mozilla-ai/any-agent/blob/main/README.md

Install the Any-Agent library using pip. Include specific frameworks as needed for your project.

```bash
pip install 'any-agent'
```

--------------------------------

### Install Any-Agent with Framework Dependencies

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/index.md

Installs Any-Agent along with specific framework dependencies, such as Agno and OpenAI.

```bash
pip install any-agent[agno,openai]
```

--------------------------------

### Clone and Set Up Development Environment

Source: https://github.com/mozilla-ai/any-agent/blob/main/CONTRIBUTING.md

Follow these steps to clone the repository, set up a virtual environment, install dependencies, and configure pre-commit hooks.

```bash
git clone https://github.com/YOUR_USERNAME/any-agent.git
cd any-agent
git remote add upstream https://github.com/mozilla-ai/any-agent.git
uv venv
source .venv/bin/activate
uv sync --dev --extra all
uv run pre-commit install
uv run pre-commit run --all-files
pytest -v tests
```

--------------------------------

### Configure and Serve an Agent with Time Tool

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/serve-a2a.md

Initializes an Any-Agent with a time-fetching tool served via an MCP server. It then starts the agent asynchronously and polls until the server is ready.

```python
import asyncio
import sys

import httpx

from any_agent import AgentConfig, AnyAgent
from any_agent.config import MCPStdio
from any_agent.serving import A2AServingConfig

time_tool = MCPStdio(
    command=sys.executable,
    args=["-u", "-m", "mcp_server_time", "--local-timezone", "America/New_York"],
    tools=[
        "get_current_time",
    ],
    client_session_timeout_seconds=30,
)

time = await AnyAgent.create_async(
    "tinyagent",  # See all options in https://docs.mozilla.ai/any-agent/
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        description="I'm an agent to help with getting the time",
        tools=[time_tool],
    ),
)

time_handle = await time.serve_async(A2AServingConfig(port=0))

server_port = time_handle.port

max_attempts = 20
poll_interval = 0.5
attempts = 0
server_url = f"http://localhost:{server_port}"
async with httpx.AsyncClient() as client:
    while True:
        try:
            # Try to make a basic GET request to check if server is responding
            await client.get(server_url, timeout=1.0)
            print(f"Server is ready at {server_url}")
            break
        except (httpx.RequestError, httpx.TimeoutException):
            # Server not ready yet, continue polling
            pass

        await asyncio.sleep(poll_interval)
        attempts += 1
        if attempts >= max_attempts:
            msg = f"Could not connect to {server_url}. Tried {max_attempts} times with {poll_interval} second interval."
            raise ConnectionError(msg)
```

--------------------------------

### LLM API Response with Steps

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/traces/LLAMA_INDEX_trace.html

Example LLM response detailing a sequence of steps. This format is used to guide agent actions.

```json
{
  "steps": [
    {
      "number": 1,
      "description": "Get current time in the America/New_York timezone. "
    },
    {
      "number": 2,
      "description": "Write the year to a file."
    }
  ]
}
```

--------------------------------

### Install Dependencies and Apply Nesting

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/mcp_agent.ipynb

Installs the necessary libraries and enables nested event loops for asyncio in Jupyter environments.

```python
%pip install 'any-agent' 'mcp-server-time' --quiet

import nest_asyncio

nest_asyncio.apply()
```

--------------------------------

### Install Dependencies and Apply Nest Asyncio

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/serve-a2a.md

Installs the necessary any-agent and mcp-server-time packages and applies the nest_asyncio patch for running asyncio in Jupyter notebooks.

```python
%pip install 'any-agent[a2a]' 'mcp-server-time' --quiet

import nest_asyncio

nest_asyncio.apply()
```

--------------------------------

### Install Any-Agent and Dependencies

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/your-first-agent-evaluation.md

Installs the any-agent library and the ddgs package. It also configures the asyncio event loop for use in Jupyter notebooks and suppresses common technical warnings.

```python
%pip install 'any-agent' --quiet
%pip install ddgs --quiet

import warnings

import nest_asyncio

# Suppress technical warnings to reduce noise for the user
warnings.simplefilter("ignore", category=DeprecationWarning)
warnings.simplefilter("ignore", category=RuntimeWarning)
warnings.simplefilter("ignore", category=UserWarning)

nest_asyncio.apply()
```

--------------------------------

### Install any-agent with A2A and Apply Nest Asyncio

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/a2a_as_tool.ipynb

Installs the any-agent library with A2A support and applies the nest_asyncio patch for compatibility with Jupyter notebooks.

```python
%pip install 'any-agent[a2a]'

import nest_asyncio

nest_asyncio.apply()
```

--------------------------------

### Install Any-Agent and Dependencies

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/callbacks.ipynb

Installs the necessary 'any-agent' and 'ddgs' libraries. It also suppresses common deprecation and runtime warnings to keep the output clean. Nest_asyncio is applied to ensure compatibility with asynchronous operations.

```python
%pip install 'any-agent' --quiet
%pip install ddgs --quiet

import warnings

import nest_asyncio

# Suppress technical warnings to reduce noise for the user
warnings.filterwarnings("ignore", category=DeprecationWarning)
warnings.filterwarnings("ignore", category=RuntimeWarning)

nest_asyncio.apply()
```

--------------------------------

### Download Ollama Model

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/agent_with_local_llm.ipynb

Pulls the 'qwen2.5:14b' model from Ollama. Ensure Ollama CLI is installed and the model is compatible with your system's hardware.

```bash
ollama pull qwen2.5:14b
```

--------------------------------

### Install Dependencies and Apply Nesting

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/agent_with_local_llm.ipynb

Installs the 'any-agent' and 'ipywidgets' libraries and applies the 'nest_asyncio' patch to enable nested event loops, which is necessary for running asyncio in Jupyter notebooks.

```python
%pip install 'any-agent' --quiet
%pip install ipywidgets --quiet

from pathlib import Path

import nest_asyncio

nest_asyncio.apply()
```

--------------------------------

### Create an Agent to be Used as a Tool

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/tools.md

Define an agent that will serve as a tool for another agent. This example sets up a 'google_expert' agent with web search capabilities.

```python
from any_agent import AgentConfig, AnyAgent
from any_agent.tools import search_web

google_agent = await AnyAgent.create_async(
    "google",
    AgentConfig(
        name="google_expert",
        model_id="mistral:mistral-small-latest",
        instructions="Use the available tools to answer questions about the Google ADK",
        description="An agent that can answer questions about the Google Agents Development Kit (ADK).",
        tools=[search_web]
    )
)
```

--------------------------------

### Callback Order Warning Example

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/callbacks.md

Demonstrates an incorrect callback order that would lead to failure due to missing shared context.

```python
    callbacks=[
        LimitSearchWeb(max_calls=3) # This will fail!
        CountSearchWeb()    # Counter must come first
    ]
```

--------------------------------

### LLM API Call Usage Example

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/traces/LLAMA_INDEX_trace.html

Example of token and cost usage for an LLM API call. Useful for understanding resource consumption.

```json
{
  "input_tokens": 403,
  "output_tokens": 32,
  "input_cost": 4.03e-05,
  "output_cost": 9.6e-06
}
```

--------------------------------

### Add Custom OpenTelemetry Exporter

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/tracing.md

Shows how to configure the OpenTelemetry SDK to send agent traces to an OTLP endpoint via HTTP. Requires installing the `opentelemetry-exporter-otlp` package.

```python
from opentelemetry.trace import get_tracer_provider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

tp = get_tracer_provider()
http_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
tp.add_span_processor(SimpleSpanProcessor(http_exporter))
```

--------------------------------

### LLM API Call Usage for Steps

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/traces/LLAMA_INDEX_trace.html

Example token and cost usage for an LLM API call that returns a list of steps. Helps in estimating costs for task planning.

```json
{
  "input_tokens": 161,
  "output_tokens": 60,
  "input_cost": 1.61e-05,
  "output_cost": 1.8e-05
}
```

--------------------------------

### Minimum Callback Implementation

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/callbacks.md

A minimal valid implementation of a callback requires inheriting from the base Callback class and returning the context object. This example shows the essential structure for the `before_llm_call` method.

```python
# Minimum valid implementation
def before_llm_call(self, context: Context, *args, **kwargs) -> Context:
    return context  # <--- Essential!
```

--------------------------------

### Run Agent with Prompt

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/mcp_agent.ipynb

Use this snippet to run the agent with a specific prompt. The prompt guides the agent's behavior and task execution. Ensure the prompt clearly outlines the steps and constraints for the agent.

```python
prompt = """
I am planning a trip to New York, NY for next weekend. Please act as my travel planner.

Follow these steps in strict order:
1. **Time Check:** Use the time tool to identify the specific dates for "next weekend."
2. **Information Gathering:** Ask me about my budget and number of guests. Do NOT search yet.
3. **Wait:** Wait for my response.
4. **Search:** ONLY after I reply, search for listings.
   **CRITICAL:** You MUST set the `location` parameter explicitly to "New York, NY" in the tool call.
"""

agent_trace = await agent.run_async(prompt)
```

--------------------------------

### Counting Tool Executions with Callbacks

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/callbacks.md

This example demonstrates how to initialize a counter in one callback (`after_tool_execution`) and use it to track specific tool calls. It utilizes `Context.shared` for state persistence and checks `context.current_span.attributes` to identify the tool.

```python
from any_agent.callbacks import Callback, Context
from any_agent.tracing.attributes import GenAI

class CountSearchWeb(Callback):
    def after_tool_execution(self, context: Context, *args, **kwargs) -> Context:
        if "search_web_count" not in context.shared:
            context.shared["search_web_count"] = 0
        if context.current_span.attributes[GenAI.TOOL_NAME] == "search_web":
            context.shared["search_web_count"] += 1
        return context
```

--------------------------------

### Configure Agent with Custom Callbacks

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/callbacks.ipynb

Register custom callbacks, including the `ToolUsageCounter` and `BudgetLimit`, along with default callbacks, in the `AgentConfig`. This setup is used to test the rate-limiting functionality by intentionally triggering the limit.

```python
from any_agent.callbacks import get_default_callbacks

# 1. Configure Agent with our custom stack
config = AgentConfig(
    model_id="mistral:mistral-small-latest",
    tools=[search_web],
    callbacks=[
        ToolUsageCounter(),  # Runs first: Counts the step
        BudgetLimit(
            max_tools=2
        ),  # Runs second: Checks the limit (set low to force a crash)
        *get_default_callbacks(),  # Runs last: Logs to console
    ],
)

agent = AnyAgent.create("tinyagent", config)

# 2. Run with a complex prompt
print("--- Starting Stress Test ---")
try:
    agent.run("Find the current weather in Tokyo, New York, and London.")
except RuntimeError as e:
    print(f"\n✅ Success! The agent was stopped: {e}")
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/mozilla-ai/any-agent/blob/main/AGENTS.md

Builds and serves the documentation locally for preview. Requires navigating to the docs directory and using npm.

```bash
cd docs && npm run dev
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/mozilla-ai/any-agent/blob/main/CONTRIBUTING.md

Serve the documentation locally to preview changes before pushing. Note that GitBook-specific syntax will appear as raw text.

```bash
uv run mkdocs serve
```

--------------------------------

### Configure API Keys

Source: https://github.com/mozilla-ai/any-agent/blob/main/CONTRIBUTING.md

Set up your API keys by creating a `.env` file in the project root or by exporting them as environment variables. Never commit API keys.

```bash
# Add keys for providers you want to test
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
MISTRAL_API_KEY=your_key_here
# Add others as needed
```

```bash
export OPENAI_API_KEY="your_key_here"
```

--------------------------------

### Create and Run an Agent

Source: https://github.com/mozilla-ai/any-agent/blob/main/README.md

Define an agent with a specific name, configuration including model, instructions, and tools. Then, run the agent with a query and print the trace.

```python
from any_agent.tools import search_web, visit_webpage

agent = AnyAgent.create(
    "tinyagent",  # See all options in https://docs.mozilla.ai/any-agent/
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        instructions="Use the tools to find an answer",
        tools=[search_web, visit_webpage]
    )
)

agent_trace = agent.run("Which Agent Framework is the best??")
print(agent_trace)
```

--------------------------------

### Running Agent for File Reading and Summarization

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/agent-with-local-llm.md

This snippet demonstrates a two-step process: first, reading a file using an agent, and second, summarizing its content and writing it to another file. Ensure the 'agent' object is initialized and necessary paths are resolved.

```python
abs_path = Path("../../demo/app.py").resolve()
output_dir = Path("agent_outputs")
output_dir.mkdir(exist_ok=True)
output_file = output_dir / "code_summary.txt"

# --- STEP 1: FORCE READ ---
print("🤖 Step 1: Reading file...")
read_agent = agent.run(f"Output the JSON to read the file at: '{abs_path}'")
# The framework executes the tool and returns the trace
# We assume the last message contains the file content (or we grab it manually)
# Note: In a real app, you'd extract the tool output programmatically.
# For this cookbook, we can just feed the file content explicitly if the agent fails,
# but usually, the agent trace contains the history.

# --- STEP 2: FORCE WRITE ---
# We feed the Previous History + New Instruction
print("🤖 Step 2: Summarizing and Writing...")
write_agent = agent.run(
    f"""
    I have read the file.
    Here is the content: {read_file(str(abs_path))}
    Task: Write a summary of this content to: '{output_file}'
    """
)
```

--------------------------------

### Initialize and Run Agent with Default Callbacks

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/callbacks.ipynb

Creates an AnyAgent instance configured with a specific model and the 'search_web' tool. It then executes a web search query using the agent's default callbacks.

```python
agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(model_id="mistral:mistral-small-latest", tools=[search_web]),
)

## Let's run a simple web search
agent_trace = agent.run("What are 5 LLM agent frameworks that are trending in 2025?")
```

--------------------------------

### Using TinyAgent with MCP Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/frameworks/tinyagent.md

Demonstrates how to initialize and run TinyAgent with MCP tools for interacting with external commands. Use this when you need to integrate TinyAgent with command-line tools via the MCP protocol.

```python
from any_agent import AnyAgent, AgentConfig
from any_agent.config import MCPStdio

agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        instructions="You must use the available tools to find an answer",
        tools=[
            MCPStdio(
                command="uvx",
                args=["duckduckgo-mcp-server"]
            )
        ]
    )
)

result = agent.run(
    "Which Agent Framework is the best??"
)
print(result.final_output)
```

--------------------------------

### Run a Main Agent Using Served Agents as Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/serving.md

This script demonstrates how to instantiate and run a main agent that utilizes other served agents as tools. It configures two tools, one using MCP/SSE and another using A2A, and then creates a main agent that can call these tools to answer prompts.

```python
import asyncio

from any_agent import AgentConfig, AnyAgent
from any_agent.config import MCPSse
from any_agent.tools import a2a_tool_async

async def main():
    prompt = "What do you know about the Google ADK?"

    google_expert = MCPSse(
        url="http://localhost:5001/google/sse", client_session_timeout_seconds=300)
    openai_expert = await a2a_tool_async(
        url="http://localhost:5002/openai")

    main_agent = await AnyAgent.create_async(
        "tinyagent",
        AgentConfig(
            model_id="gemini/gemini-2.5-pro",
            instructions="You must use the available tools to answer.",
            tools=[google_expert, openai_expert],
        )
    )

    await main_agent.run_async(prompt)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize MCP Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/mcp_agent.ipynb

Initializes two MCP tools: a time tool using MCPStdio with a local timezone and an Airbnb tool that uses 'npx' to run the Airbnb MCP server. Both tools have a client session timeout of 30 seconds.

```python
import sys

from any_agent import AgentConfig, AnyAgent
from any_agent.config import MCPStdio

time_tool = MCPStdio(
    command=sys.executable,
    args=["-u", "-m", "mcp_server_time", "--local-timezone", "America/New_York"],
    tools=[
        "get_current_time",
    ],
    client_session_timeout_seconds=30,
)

print("Done init time_tool")
# This MCP tool relies upon npx https://docs.npmjs.com/cli/v8/commands/npx which comes standard with npm
airbnb_tool = MCPStdio(
    command="npx",
    args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
    client_session_timeout_seconds=30,
)
print("Done init airbnb_tool")
```

--------------------------------

### Configure and Serve Helper Agents via A2A

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/a2a-as-tool.md

Sets up two 'helper' agents, one for time and one for weather recommendations, and serves them asynchronously over A2A. It includes a loop to poll for server readiness before proceeding.

```python
import asyncio

import httpx

from any_agent import AgentConfig, AnyAgent
from any_agent.config import MCPStdio
from any_agent.serving import A2AServingConfig

# This MCP Tool relies upon uvx https://docs.astral.sh/uv/getting-started/installation/
time_tool = MCPStdio(
    command="uvx",
    args=["--local-timezone=America/New_York"],
    tools=[
        "get_current_time",
    ],
)

time = await AnyAgent.create_async(
    "tinyagent",  # See all options in https://docs.mozilla.ai/any-agent/
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        name="time_agent",
        description="I'm an agent to help with getting the time",
        tools=[time_tool],
    ),
)
time_handle = await time.serve_async(A2AServingConfig(port=0, endpoint="/time"))

weather_expert = await AnyAgent.create_async(
    "tinyagent",
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        name="weather_expert",
        instructions="You're an expert that is an avid skier, recommend a great location to ski given a time of the year",
        description="I'm an agent that is an expert in recommending my favorite location given a time of the year",
    ),
)
weather_handle = await weather_expert.serve_async(
    A2AServingConfig(port=0, endpoint="/location_recommender")
)

weather_port = weather_handle.port
time_port = time_handle.port

max_attempts = 20
poll_interval = 0.5
attempts = 0
time_url = f"http://localhost:{time_port}"
weather_url = f"http://localhost:{weather_port}"
async with httpx.AsyncClient() as client:
    while True:
        try:
            # Try to make a basic GET request to check if server is responding
            await client.get(time_url, timeout=1.0)
            print(f"Server is ready at {weather_url}")
            break
        except (httpx.RequestError, httpx.TimeoutException):
            # Server not ready yet, continue polling
            pass

        await asyncio.sleep(poll_interval)
        attempts += 1
        if attempts >= max_attempts:
            msg = f"Could not connect to the servers. Tried {max_attempts} times with {poll_interval} second interval."
            raise ConnectionError(msg)
```

--------------------------------

### Tool Execution: Get Current Time

Source: https://github.com/mozilla-ai/any-agent/blob/main/tests/assets/LLAMA_INDEX_trace.html

Demonstrates the input provided to the 'get_current_time' tool and its resulting output, including timezone, datetime, and DST information.

```json
{
  "timezone": "America/New_York"
}
{
  "timezone": "America/New_York",
  "datetime": "2025-09-16T09:14:59-04:00",
  "is_dst": true
}
```

--------------------------------

### Create Agent with Local LLM and Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/agent-with-local-llm.md

This Python code initializes an agent using the any-agent library with a local LLM (ollama/qwen2.5:14b) and custom tools. It configures model arguments, including a 'WAIT' stop token to ensure proper tool execution flow.

```python
from any_agent import AgentConfig, AnyAgent

model_id = "ollama/qwen2.5:14b"

model_args = {
    "num_ctx": 32000,
    "temperature": 0.0,
    # Note: We use a strict 'WAIT' stop token to force the local model to pause and let the Python kernel execute the tool.
    # Without this, local models often hallucinate the tool output.
    "stop": ["WAIT"],
}

agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(
        model_id=model_id,
        instructions='''You are a precise tool-calling agent.

        PROTOCOL:
        1. Output valid JSON for the tool you want to use.
        2. AFTER the JSON, write the word "WAIT".
        3. The system will then pause and run the tool for you.
        FORMAT:
        {
            "name": "tool_name",
            "arguments": {
                "arg_name": "value"
            }
        }
        WAIT
        ''',
        tools=[read_file, write_file],
        model_args=model_args,
    ),
)
```

--------------------------------

### Configure and Serve Helper Agents

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/a2a_as_tool.ipynb

Sets up two helper agents, 'time_agent' and 'weather_expert', serving them asynchronously over A2A. Includes a mechanism to poll and confirm server readiness before proceeding.

```python
import asyncio

import httpx

from any_agent import AgentConfig, AnyAgent
from any_agent.config import MCPStdio
from any_agent.serving import A2AServingConfig

# This MCP Tool relies upon uvx https://docs.astral.sh/uv/getting-started/installation/
time_tool = MCPStdio(
    command="uvx",
    args=["mcp-server-time", "--local-timezone=America/New_York"],
    tools=[
        "get_current_time",
    ],
)

time = await AnyAgent.create_async(
    "tinyagent",  # See all options in https://docs.mozilla.ai/any-agent/
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        name="time_agent",
        description="I'm an agent to help with getting the time",
        tools=[time_tool],
    ),
)
time_handle = await time.serve_async(A2AServingConfig(port=0, endpoint="/time"))

weather_expert = await AnyAgent.create_async(
    "tinyagent",
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        name="weather_expert",
        instructions="You're an expert that is an avid skier, recommend a great location to ski given a time of the year",
        description="I'm an agent that is an expert in recommending my favorite location given a time of the year",
    ),
)
weather_handle = await weather_expert.serve_async(
    A2AServingConfig(port=0, endpoint="/location_recommender")
)

weather_port = weather_handle.port
time_port = time_handle.port

max_attempts = 20
poll_interval = 0.5
attempts = 0
time_url = f"http://localhost:{time_port}"
weather_url = f"http://localhost:{weather_port}"
async with httpx.AsyncClient() as client:
    while True:
        try:
            # Try to make a basic GET request to check if server is responding
            await client.get(time_url, timeout=1.0)
            print(f"Server is ready at {weather_url}")
            break
        except (httpx.RequestError, httpx.TimeoutException):
            # Server not ready yet, continue polling
            pass

        await asyncio.sleep(poll_interval)
        attempts += 1
        if attempts >= max_attempts:
            msg = f"Could not connect to the servers. Tried {max_attempts} times with {poll_interval} second interval."
            raise ConnectionError(msg)
```

--------------------------------

### Set API Key

Source: https://github.com/mozilla-ai/any-agent/blob/main/README.md

Set the API key for the model provider you are using. This example shows setting the Mistral API key, but other providers like OpenAI are also supported.

```bash
export MISTRAL_API_KEY="YOUR_KEY_HERE"  # or OPENAI_API_KEY, etc
```

--------------------------------

### Configure Main Agent with Tool Agent

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/tools.md

Set up a main agent that utilizes another agent (e.g., 'google_agent_as_tool') as one of its tools. This allows for hierarchical agent interactions.

```python
main_agent = await AnyAgent.create_async(
    "tinyagent",
    AgentConfig(
        name="main_agent",
        model_id="mistral-small-latest",
        instructions="Use the available tools to obtain additional information to answer the query.",
        tools=[google_agent_as_tool],
    )
)
```

--------------------------------

### Execute Tool: write_file

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/traces/AGNO_trace.html

This snippet shows the input and output for the 'write_file' tool execution. It includes the text to be written and the resulting empty output.

```json
{
  "text": "2025"
}
```

```json
{}
```

--------------------------------

### LLM Call: Initial Prompt and Tool Selection

Source: https://github.com/mozilla-ai/any-agent/blob/main/tests/assets/LLAMA_INDEX_trace.html

Shows the initial system and user prompts sent to the LLM, and the LLM's decision to call the 'get_current_time' tool. Includes token and cost usage.

```json
{
  "role": "system",
  "content": "Use the available tools to answer.You must call the fina"
}
{
  "role": "user",
  "content": "Find what year it is in the America/New_York timezone an"
}
{
  "tool.name": "get_current_time",
  "tool.args": "{}"
}
{
  "input_tokens": 197,
  "output_tokens": 36,
  "input_cost": 1.9699999999999998e-05,
  "output_cost": 1.08e-05
}
```

--------------------------------

### Create AnyAgent with Local LLM and Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/agent_with_local_llm.ipynb

Initializes an AnyAgent instance using the 'tinyagent' framework, specifying a local model ID, custom instructions, and the defined tools. The 'stop' token 'WAIT' is crucial for synchronizing tool execution with the local model.

```python
from any_agent import AgentConfig, AnyAgent

model_id = "ollama/qwen2.5:14b"

model_args = {
    "num_ctx": 32000,
    "temperature": 0.0,
    # Note: We use a strict 'WAIT' stop token to force the local model to pause and let the Python kernel execute the tool.
    # Without this, local models often hallucinate the tool output.
    "stop": ["WAIT"],
}

agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(
        model_id=model_id,
        instructions="""You are a precise tool-calling agent.

        PROTOCOL:
        1. Output valid JSON for the tool you want to use.
        2. AFTER the JSON, write the word "WAIT".
        3. The system will then pause and run the tool for you.
        FORMAT:
        {
            "name": "tool_name",
            "arguments": {
                "arg_name": "value"
            }
        }
        WAIT
        """,
        tools=[read_file, write_file],
        model_args=model_args,
    ),
)
```

--------------------------------

### Initialize Any-Agent with Model and Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/your-first-agent.md

Creates an instance of AnyAgent named 'tinyagent'. It's configured to use the 'mistral-small-latest' model and includes the 'search_web' tool for DuckDuckGo searches.

```python
from any_agent import AgentConfig, AnyAgent
from any_agent.tools import search_web

# We use the 'mistral-small-latest' model we promised in the text
agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(model_id="mistral:mistral-small-latest", tools=[search_web]),
)
```

--------------------------------

### Run Agent for File Reading and Writing

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/agent_with_local_llm.ipynb

Executes the agent to first read a file and then summarize its content and write it to another file. This demonstrates a multi-step agent process involving tool use.

```python
from pathlib import Path

abs_path = Path("../../demo/app.py").resolve()
output_dir = Path("agent_outputs")
output_dir.mkdir(exist_ok=True)
output_file = output_dir / "code_summary.txt"

# --- STEP 1: FORCE READ ---
print("🤖 Step 1: Reading file...")
read_agent = agent.run(f"Output the JSON to read the file at: '{abs_path}'")
# The framework executes the tool and returns the trace
# We assume the last message contains the file content (or we grab it manually)
# Note: In a real app, you'd extract the tool output programmatically.
# For this cookbook, we can just feed the file content explicitly if the agent fails,
# but usually, the agent trace contains the history.

# --- STEP 2: FORCE WRITE ---
# We feed the Previous History + New Instruction
print("🤖 Step 2: Summarizing and Writing...")
write_agent = agent.run(
    f"""
    I have read the file.
    Here is the content: {read_file(str(abs_path))}
    Task: Write a summary of this content to: '{output_file}'
    """
)
```

--------------------------------

### Pseudocode for Agent Run with Callbacks

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/callbacks.md

Illustrates the sequence of callback events during an agent's run, including pre/post LLM calls and tool executions. Callbacks receive and return a Context object.

```python
# pseudocode of an Agent run

history = [system_prompt, user_prompt]
context = Context()

for callback in agent.config.callbacks:
    # 1. Agent Start
    context = callback.before_agent_invocation(context)

while True:

    for callback in agent.config.callbacks:
        # 2. Pre-LLM
        context = callback.before_llm_call(context)

    response = CALL_LLM(history)

    for callback in agent.config.callbacks:
        # 3. Post-LLM
        context = callback.after_llm_call(context)

    history.append(response)

    if response.tool_executions:
        for tool_execution in tool_executions:
            # 4. Pre-Tool
            for callback in agent.config.callbacks:
                context = callback.before_tool_execution(context)

            tool_response = EXECUTE_TOOL(tool_execution)

            for callback in agent.config.callbacks:
                # 5. Post-Tool
                context = callback.after_tool_execution(context)

            history.append(tool_response)

    else:
        for callback in agent.config.callbacks:
            # 6. Agent DONE
            context = callback.after_agent_invocation(context)
        return response

```

--------------------------------

### Agent with User Interaction Tool for Natural Conversations

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/index.md

Shows how to create an agent equipped with the `send_console_message` tool, enabling it to naturally ask follow-up questions during execution. This is ideal for scenarios requiring back-and-forth user interaction to complete a task.

```python
from any_agent import AgentConfig, AnyAgent
from any_agent.tools.user_interaction import send_console_message

# Create agent with user interaction capabilities
agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        instructions="You are a helpful travel assistant. Send console messages to ask more questions. Do not stop until you've answered the question.",
        tools=[send_console_message]
    )
)

# The agent can now naturally ask questions during its execution
prompt = """
I'm planning a trip and need help finding accommodations.
Please ask me some questions to understand my preferences, then provide recommendations.
"""

agent_trace = agent.run(prompt)
print(f"Final recommendations: {agent_trace.final_output}")
```

--------------------------------

### Serve Agent as MCP Tool

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/tools.md

Make an agent available as a Model Context Protocol (MCP) service. This allows other agents to interact with it over HTTP.

```python
from any_agent.config import MCPSse
from any_agent.serving import MCPServingConfig

mcp_handle = await google_agent.serve_async(
    MCPServingConfig(port=5001, endpoint="/google-agent"))

google_agent_as_tool = MCPSse(
    url="http://localhost:5001/google-agent/sse")
```

--------------------------------

### Create a Web Search Agent

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/your-first-agent-evaluation.md

Initializes an AnyAgent instance named 'tinyagent' configured to use the 'mistral:mistral-small-latest' model and includes 'search_web' and 'visit_webpage' tools.

```python
from any_agent import AgentConfig, AnyAgent
from any_agent.tools import search_web, visit_webpage

agent = AnyAgent.create(
    "tinyagent",  # See all options in https://docs.mozilla.ai/any-agent/
    AgentConfig(
        model_id="mistral:mistral-small-latest", tools=[search_web, visit_webpage]
    ),
)
```

--------------------------------

### Serve Google Expert Agent (Python)

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/serving.md

Configures and serves a Google expert agent. Specify 'a2a' or 'mcp' as the protocol argument. Requires 'a2a' extra if using A2A protocol.

```python
# google_expert.py
import argparse
import asyncio

from any_agent import AgentConfig, AnyAgent
from any_agent.tools import search_web

async def serve_agent(protocol):
    agent = await AnyAgent.create_async(
        "google",
        AgentConfig(
            name="google_expert",
            model_id="mistral:mistral-small-latest",
            instructions="You can answer questions about the Google Agents Development Kit (ADK) but nothing else",
            description="An agent that can answer questions specifically and only about the Google Agents Development Kit (ADK).",
            tools=[search_web]
        )
    )

    if protocol == "a2a":
        from any_agent.serving import A2AServingConfig
        serving_config = A2AServingConfig(port=5001, endpoint="/google")
    elif protocol == "mcp":
        from any_agent.serving import MCPServingConfig
        serving_config = MCPServingConfig(port=5001, endpoint="/google")

    server_handle = await agent.serve_async(serving_config)
    await server_handle.task

if __name__ == "__main__":
    parser=argparse.ArgumentParser()
    parser.add_argument("protocol", choices=["a2a", "mcp"])
    args = parser.parse_args()
    asyncio.run(serve_agent(args.protocol))
```

--------------------------------

### Import Necessary Libraries

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/callbacks.ipynb

Imports the core AnyAgent class and configuration settings, along with the 'search_web' tool for agent functionality.

```python
from any_agent import AgentConfig, AnyAgent
from any_agent.tools import search_web
```

--------------------------------

### Create and run an agent asynchronously

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/index.md

For asynchronous contexts, use `create_async` and `run_async` methods. This is useful for non-blocking operations.

```python
import asyncio

async def main():
    agent = await AnyAgent.create_async(
        "openai",
        AgentConfig(
            model_id="mistral:mistral-small-latest",
            instructions="Use the tools to find an answer",
            tools=[search_web, visit_webpage]
        )
    )

    agent_trace = await agent.run_async("Which Agent Framework is the best??")
    print(agent_trace.final_output)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Serve OpenAI Expert Agent (Python)

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/serving.md

Configures and serves an OpenAI expert agent. Specify 'a2a' or 'mcp' as the protocol argument. Requires 'a2a' extra if using A2A protocol.

```python
# openai_expert.py
import argparse
import asyncio

from any_agent import AgentConfig, AnyAgent
from any_agent.tools import search_web

async def serve_agent(protocol):
    agent = await AnyAgent.create_async(
        "openai",
        AgentConfig(
            name="openai_expert",
            model_id="mistral:mistral-small-latest",
            instructions="You can answer questions about the OpenAI Agents SDK but nothing else.",
            description="An agent that can answer questions specifically and only about the OpenAI Agents SDK.",
            tools=[search_web]
        )
    )

    if protocol == "a2a":
        from any_agent.serving import A2AServingConfig
        serving_config = A2AServingConfig(port=5002, endpoint="/openai")
    elif protocol == "mcp":
        from any_agent.serving import MCPServingConfig
        serving_config = MCPServingConfig(port=5002, endpoint="/openai")

    server_handle = await agent.serve_async(serving_config)
    await server_handle.task

if __name__ == "__main__":
    parser=argparse.ArgumentParser()
    parser.add_argument("protocol", choices=["a2a", "mcp"])
    args = parser.parse_args()
    asyncio.run(serve_agent(args.protocol))
```

--------------------------------

### Define Agent with Web Search Tool

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/tools.md

Configure an agent with a built-in web search tool. Ensure the `search_web` tool is imported.

```python
from any_agent import AgentConfig
from any_agent.tools import search_web

main_agent = AgentConfig(
    model_id="mistral:mistral-small-latest",
    tools=[search_web]
)
```

--------------------------------

### Evaluate Agent Response Quality with LlmJudge

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/evaluation.md

This snippet demonstrates how to use LlmJudge to evaluate an agent's response to a customer support query. It sets up an agent, runs it, defines evaluation questions, and then uses LlmJudge to assess the response against these questions multiple times for consistency. For asynchronous applications, use `judge.run_async()`.

```python
from any_agent import AnyAgent, AgentConfig
from any_agent.tools import search_web
from any_agent.evaluation import LlmJudge
# Run an agent on a customer support task
agent = AnyAgent.create(
    "tinyagent",
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        tools=[search_web]
    ),
)

trace = agent.run(
    "A customer is asking about setting up a new email account on the latest version of iOS. "
    "They mention they're not very tech-savvy and seem frustrated. "
    "Help them with clear, step-by-step instructions."
)

# Evaluate the quality of the agent's response multiple times
judge = LlmJudge(model_id="mistral:mistral-small-latest")
evaluation_questions = [
    "Did it provide clear, step-by-step instructions?",
    "Was the tone empathetic and appropriate for a frustrated, non-technical customer?",
    "Did it avoid using technical jargon without explanation?",
    "Was the response complete and actionable?",
    "Does the description specify which version of iOS this works with?"
]

# Run evaluation 4 times to check consistency
results = []
for evaluation_question in evaluation_questions:
    question = f"Evaluate whether the agent's response demonstrates good customer service by considering: {evaluation_question}.".
    result = judge.run(context=str(trace.spans_to_messages()), question=evaluation_question)
    results.append(result)

# Print all results
for i, result in enumerate(results, 1):
    print(f"Run {i} - Passed: {result.passed}")
    print(f"Run {i} - Reasoning: {result.reasoning}")
    print("-" * 50)
```

--------------------------------

### Create AnyAgent Instance

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/mcp_agent.ipynb

Creates an asynchronous instance of AnyAgent using the 'tinyagent' framework and a specified model ('mistral:mistral-large-latest'). It configures the agent with the previously initialized time and Airbnb MCP tools, along with the custom send_message tool. Includes error handling for agent creation.

```python
print("Start creating agent")
try:
    agent = await AnyAgent.create_async(
        "tinyagent",  # See all options in https://docs.mozilla.ai/any-agent/
        AgentConfig(
            model_id="mistral:mistral-large-latest",
            tools=[time_tool, airbnb_tool, send_message],
        ),
    )
except Exception as e:
    print(f"❌ Failed to create agent: {e}")
print("Done creating agent")
```

--------------------------------

### Define Agent with Composio Tools

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/tools.md

Integrate Composio tools into an agent. Requires initializing `Composio` with a `CallableProvider` and fetching specific toolkits.

```python
from any_agent import AgentConfig
from any_agent.tools.composio import CallableProvider
from composio import Composio

cpo = Composio(CallableProvider())

main_agent = AgentConfig(
    model_id="mistral:mistral-small-latest",
    tools=cpo.tools.get(
        user_id="daavoo",
        toolkits=["GITHUB", "HACKERNEWS"],
    )
)
```

--------------------------------

### Run Expert Agent Scripts (Bash)

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/serving.md

Execute the Python scripts to serve agents. Choose either 'mcp' or 'a2a' as the protocol argument for each script.

```bash
python google_expert.py mcp  ## or a2a
```

```bash
python openai_expert.py a2a  ## or mcp
```

--------------------------------

### Run Agent with a Prompt

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/your-first-agent-evaluation.md

Execute the agent with a specific prompt to generate a trace. This trace captures the agent's execution path and final output.

```python
prompt = """What film won a Goya Award for best film in 2024?
Please provide the name of the film, the genre, a very brief
description of the film - and rotten tomatoes popcornmeter
score."""

agent_trace = agent.run(prompt)
```

--------------------------------

### Create a single agent instance

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/index.md

Instantiate a single agent using the `AnyAgent.create` method, specifying the framework, model, instructions, and available tools.

```python
agent = AnyAgent.create(
    "openai",  # See other options under `Frameworks`
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        instructions="Use the tools to find an answer",
        tools=[search_web, visit_webpage]
    ),
)
```

--------------------------------

### View Agent Results and Trace

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/your-first-agent-evaluation.md

Print the duration, cost, final output, and tool execution path from the generated agent trace. This helps in understanding the agent's behavior and verifying its steps.

```python
print(f"⏱️ Duration: {agent_trace.duration.total_seconds():.2f}s")
print(f"💰 Cost: ${agent_trace.cost.total_cost:.6f}")

print("\n--- Final Answer ---")
print(agent_trace.final_output)

print("\n--- Tool Execution Path ---")
# Show the exact steps the agent took so we can verify if it "Cheated" or not
for span in agent_trace.spans:
    if span.is_tool_execution():
        print(f"🛠️ Tool Used: {span.attributes.get('gen_ai.tool.name')}")
```

--------------------------------

### Run Agent with a Task

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/your-first-agent.md

Executes the configured agent to find 5 trending TV shows released recently, requesting specific details like name, release date, genre, and description.

```python
agent_trace = agent.run(
    "What are 5 tv shows that are trending in 2025? Check a few sites, and provide the name of the show, the exact release date, the genre, and a brief description of the show."
)
```

--------------------------------

### Set Mistral API Key

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/cookbook/mcp_agent.ipynb

Checks for the MISTRAL_API_KEY environment variable and prompts the user to enter it if not found. Also warns if 'npx' is not in the system's PATH, as it's required for the Airbnb tool.

```python
import os
import shutil
from getpass import getpass

if "MISTRAL_API_KEY" not in os.environ:
    print("MISTRAL_API_KEY not found in environment!")
    api_key = getpass("Please enter your MISTRAL_API_KEY: ")
    os.environ["MISTRAL_API_KEY"] = api_key
    print("MISTRAL_API_KEY set for this session!")
else:
    print("MISTRAL_API_KEY found in environment.")

# Quick Environment Check (Airbnb tool requires npx/Node.js)
if not shutil.which("npx"):
    print(
        "⚠️ Warning: 'npx' was not found in your path. The Airbnb tool requires Node.js/npm to run."
    )
```

--------------------------------

### Async Context Manager for Tool Cleanup

Source: https://github.com/mozilla-ai/any-agent/blob/main/docs/agents/tools.md

Use the async context manager pattern for automatic cleanup of tool resources. This is the recommended approach to avoid runtime errors related to resource management.

```python
import asyncio
from any_agent import AgentConfig, AnyAgent
from any_agent.config import MCPStdio

async def main():
    time_tool = MCPStdio(
        command="uvx",
        args=["mcp-server-time"],
    )

    async with await AnyAgent.create_async(
        "tinyagent",
        AgentConfig(
            model_id="mistral:mistral-small-latest",
            tools=[time_tool],
        ),
    ) as agent:
        result = await agent.run_async("What time is it?")
        print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Commit and Push Changes

Source: https://github.com/mozilla-ai/any-agent/blob/main/CONTRIBUTING.md

Stage, commit, and push your local changes to your fork on GitHub. Use descriptive commit messages.

```bash
git add .
git commit -m "feat: add support for new framework"
git push origin feature/your-feature-name
```