AutoGen

https://microsoft.github.io/autogen/stable/
Admin
AutoGen is a framework for building AI agents and applications with support for conversational...
Tokens:774,331
Snippets:5,475
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup Functions and Dependencies

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/local.html

Builds the function file, installs required packages via pip, and validates the setup.

```python
async def _setup_functions(self, cancellation_token: CancellationToken) -> None:
        func_file_content = build_python_functions_file(self._functions)
        func_file = self.work_dir / f"{self._functions_module}.py"
        func_file.write_text(func_file_content)

        # Collect requirements
        lists_of_packages = [x.python_packages for x in self._functions if isinstance(x, FunctionWithRequirements)]
        flattened_packages = [item for sublist in lists_of_packages for item in sublist]
        required_packages = list(set(flattened_packages))
        if len(required_packages) > 0:
            logging.info("Ensuring packages are installed in executor.")

            cmd_args = ["-m", "pip", "install"]
            cmd_args.extend(required_packages)

            if self._virtual_env_context:
                py_executable = self._virtual_env_context.env_exe
            else:
                py_executable = sys.executable

            task = asyncio.create_task(
                asyncio.create_subprocess_exec(
                    py_executable,
                    *cmd_args,
                    cwd=self.work_dir,
                    stdout=asyncio.subprocess.PIPE,
                    stderr=asyncio.subprocess.PIPE,
                )
            )
            cancellation_token.link_future(task)
            try:
                proc = await task
                stdout, stderr = await asyncio.wait_for(proc.communicate(), self._timeout)
            except asyncio.TimeoutError as e:
                raise ValueError("Pip install timed out") from e
            except asyncio.CancelledError as e:
                raise ValueError("Pip install was cancelled") from e

            if proc.returncode is not None and proc.returncode != 0:
                raise ValueError(f"Pip install failed. {stdout.decode()}, {stderr.decode()}")

        # Attempt to load the function file to check for syntax errors, imports etc.
        exec_result = await self._execute_code_dont_check_setup(
            [CodeBlock(code=func_file_content, language="python")], cancellation_token
        )

        if exec_result.exit_code != 0:
            raise ValueError(f"Functions failed to load: {exec_result.output}")

        self._setup_functions_complete = True
```

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

### Local fetch MCP service example

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/tools/mcp/_factory.html

This example shows how to create an agent that utilizes the `fetch` tool from a local MCP server. The `mcp-server-fetch` package must be installed. The agent can then fetch and summarize web content.

```bash
pip install mcp-server-fetch
```

```python
import asyncio

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools


async def main() -> None:
    # Get the fetch tool from mcp-server-fetch.
    fetch_mcp_server = StdioServerParams(command="uvx", args=["mcp-server-fetch"])
    tools = await mcp_server_tools(fetch_mcp_server)

    # Create an agent that can use the fetch tool.
    model_client = OpenAIChatCompletionClient(model="gpt-4o")
    agent = AssistantAgent(name="fetcher", model_client=model_client, tools=tools, reflect_on_tool_use=True)  # type: ignore

    # Let the agent fetch the content of a URL and summarize it.
    result = await agent.run(task="Summarize the content of https://en.wikipedia.org/wiki/Seattle")
    print(result.messages[-1])


asyncio.run(main())
```

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

### Initialize SingleThreadedAgentRuntime

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_core/_single_threaded_agent_runtime.html

Example demonstrating the setup of a runtime and registration of an agent.

```python
import asyncio
from dataclasses import dataclass

from autogen_core import AgentId, MessageContext, RoutedAgent, SingleThreadedAgentRuntime, message_handler


@dataclass
class MyMessage:
    content: str


class MyAgent(RoutedAgent):
    @message_handler
    async def handle_my_message(self, message: MyMessage, ctx: MessageContext) -> None:
        print(f"Received message: {message.content}")


async def main() -> None:
    # Create a runtime and register the agent
```

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

### Local filesystem MCP service example

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/tools/mcp/_factory.html

This example demonstrates setting up an agent to use tools from a local filesystem MCP server. Ensure the `@modelcontextprotocol/server-filesystem` package is installed globally via npm. The agent can then perform filesystem operations.

```bash
npm install -g @modelcontextprotocol/server-filesystem
```

```python
import asyncio
from pathlib import Path
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools
from autogen_agentchat.agents import AssistantAgent
from autogen_core import CancellationToken


async def main() -> None:
    # Setup server params for local filesystem access
    desktop = str(Path.home() / "Desktop")
    server_params = StdioServerParams(
        command="npx.cmd", args=["-y", "@modelcontextprotocol/server-filesystem", desktop]
    )

    # Get all available tools from the server
    tools = await mcp_server_tools(server_params)

    # Create an agent that can use all the tools
    agent = AssistantAgent(
        name="file_manager",
        model_client=OpenAIChatCompletionClient(model="gpt-4"),
        tools=tools,  # type: ignore
    )

    # The agent can now use any of the filesystem tools
    await agent.run(task="Create a file called test.txt with some content", cancellation_token=CancellationToken())


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

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

### Setup Functions and Dependencies

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/docker/_docker_code_executor.html

Configures the execution environment by writing function files and installing required Python packages via pip.

```python
async def _setup_functions(self, cancellation_token: CancellationToken) -> None:
        func_file_content = build_python_functions_file(self._functions)
        func_file = self.work_dir / f"{self._functions_module}.py"
        func_file.write_text(func_file_content)

        # Collect requirements
        lists_of_packages = [x.python_packages for x in self._functions if isinstance(x, FunctionWithRequirements)]
        flattened_packages = [item for sublist in lists_of_packages for item in sublist]
        required_packages = list(set(flattened_packages))
        if len(required_packages) > 0:
            logging.info("Ensuring packages are installed in executor.")

            packages = shlex.join(required_packages)

            result = await self._execute_code_dont_check_setup(
                [CodeBlock(code=f"python -m pip install {packages}", language="sh")], cancellation_token
            )

            if result.exit_code != 0:
                stdout = result.output
                stderr = result.output
                raise ValueError(f"Pip install failed. {stdout}, {stderr}")

        # Attempt to load the function file to check for syntax errors, imports etc.
        exec_result = await self._execute_code_dont_check_setup(
            [CodeBlock(code=func_file_content, language="python")], cancellation_token
        )

        if exec_result.exit_code != 0:
            raise ValueError(f"Functions failed to load: {exec_result.output}")

        self._setup_functions_complete = True
```

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

### Install LiteLLM and Ollama

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/core-user-guide/cookbook/local-llms-ollama-litellm.ipynb.txt

Installs Ollama, pulls a Llama3.2 model, installs LiteLLM with proxy support, and starts the LiteLLM proxy server.

```bash
curl -fsSL https://ollama.com/install.sh | sh

ollama pull llama3.2:1b

pip install 'litellm[proxy]'
litellm --model ollama/llama3.2:1b
```

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

### Register Agents and Run Runtime

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/core-user-guide/framework/message-and-communication.ipynb.txt

This example shows how to register agents with the runtime, add subscriptions, and start the agent runtime to process messages. It demonstrates both decorator-based and manual subscription registration.

```python
from autogen_core import TypeSubscription

runtime = SingleThreadedAgentRuntime()

# Option 1: with type_subscription decorator
# The type_subscription class decorator automatically adds a TypeSubscription to
# the runtime when the agent is registered.
await ReceivingAgent.register(runtime, "receiving_agent", lambda: ReceivingAgent("Receiving Agent"))

# Option 2: with TypeSubscription
await BroadcastingAgent.register(runtime, "broadcasting_agent", lambda: BroadcastingAgent("Broadcasting Agent"))
await runtime.add_subscription(TypeSubscription(topic_type="default", agent_type="broadcasting_agent"))

# Start the runtime and publish a message.
runtime.start()
await runtime.publish_message(
    Message("Hello, World! From the runtime!"), topic_id=TopicId(type="default", source="default")
)
await runtime.stop_when_idle()
```

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

### Build frontend from source manually

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/autogenstudio-user-guide/installation.md.txt

Commands to install dependencies and build the UI when installing from source.

```bash
npm install -g gatsby-cli
npm install --global yarn
cd frontend
yarn install
yarn build
# Windows users may need alternative commands to build the frontend:
gatsby clean && rmdir /s /q ..\autogenstudio\web\ui 2>nul & (set "PREFIX_PATH_VALUE=" || ver>nul) && gatsby build --prefix-paths && xcopy /E /I /Y public ..\autogenstudio\web\ui
```

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

### Install Required Libraries

Source: https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/examples/company-research.html

Install the necessary dependencies for the search and stock analysis tools.

```bash
pip install yfinance matplotlib pytz numpy pandas python-dotenv requests bs4
```

```bash
#!pip install yfinance matplotlib pytz numpy pandas python-dotenv requests bs4
```

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

### Install Rich Library

Source: https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/design-patterns/group-chat.html

Install the rich library to enable formatted message display.

```bash
# ! pip install rich
```

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

### Install OpenAI and Azure extensions

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/core-user-guide/installation.md.txt

Commands to install additional extensions for model client support.

```bash
pip install "autogen-ext[openai]"
```

```bash
pip install "autogen-ext[azure]"
```

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

### Start Runtime

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/runtimes/grpc/_worker_runtime.html

Starts the gRPC runtime connection and begins the background read loop.

```APIDOC
## Method: start

### Description
Starts the runtime in a background task, establishing a connection to the host and initiating the message read loop.

### Response
- **None** (void) - Returns nothing upon successful startup.
```

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

### Start Code Executor

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/azure/_azure_container_code_executor.html

Marks the code executor as started. No specific setup is required for this executor.

```python
self._started = True
```

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

### Instantiate and run the agent with follow-up questions

Source: https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/components/model-context.html

This example demonstrates how to set up the OpenAI chat completion client, register the agent with the runtime, and send sequential messages to observe how the context is maintained. The second question leverages the preserved context from the first.

```python
model_client = OpenAIChatCompletionClient(
    model="gpt-4o-mini",
    # api_key="sk-...", # Optional if you have an OPENAI_API_KEY set in the environment.
)

runtime = SingleThreadedAgentRuntime()
await SimpleAgentWithContext.register(
    runtime,
    "simple_agent_context",
    lambda: SimpleAgentWithContext(model_client=model_client),
)
# Start the runtime processing messages.
runtime.start()
agent_id = AgentId("simple_agent_context", "default")

# First question.
message = Message("Hello, what are some fun things to do in Seattle?")
print(f"Question: {message.content}")
response = await runtime.send_message(message, agent_id)
print(f"Response: {response.content}")
print("-----")

# Second question.
message = Message("What was the first thing you mentioned?")
print(f"Question: {message.content}")
response = await runtime.send_message(message, agent_id)
print(f"Response: {response.content}")
```

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

### Get Start Nodes in Graph

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.html

Returns the nodes that have no incoming edges, serving as entry points. Handles default start node if specified.

```python
def get_start_nodes(self) -> Set[str]:
        """Return the nodes that have no incoming edges (entry points)."""
        if self.default_start_node:
            return {self.default_start_node}

        parents = self.get_parents()
        return set([node_name for node_name, parent_list in parents.items() if not parent_list])
```

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

### Example: Using FunctionTool for Stock Prices

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_core/tools/_function_tool.html

Demonstrates initializing and running a FunctionTool to fetch stock prices. Includes setting up a cancellation token and printing the formatted result.

```python
import random
from autogen_core import CancellationToken
from autogen_core.tools import FunctionTool
from typing_extensions import Annotated
import asyncio


async def get_stock_price(ticker: str, date: Annotated[str, "Date in YYYY/MM/DD"]) -> float:
    # Simulates a stock price retrieval by returning a random float within a specified range.
    return random.uniform(10, 200)


async def example():
    # Initialize a FunctionTool instance for retrieving stock prices.
    stock_price_tool = FunctionTool(get_stock_price, description="Fetch the stock price for a given ticker.")

    # Execute the tool with cancellation support.
    cancellation_token = CancellationToken()
    result = await stock_price_tool.run_json({"ticker": "AAPL", "date": "2021/01/01"}, cancellation_token)

    # Output the result as a formatted string.
    print(stock_price_tool.return_value_as_string(result))


asyncio.run(example())
```

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

### Start Jupyter Kernel Session

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/docker_jupyter/_docker_jupyter.html

Starts a new Jupyter kernel session. It checks for the availability of the specified kernel and raises a ValueError if the kernel is not installed.

```python
async def start(self) -> None:
        """(Experimental) Start a new session."""
        available_kernels = await self._jupyter_client.list_kernel_specs()
        if self._kernel_name not in available_kernels["kernelspecs"]:
            raise ValueError(f"Kernel {self._kernel_name} is not installed.")
        self._kernel_id = await self._jupyter_client.start_kernel(self._kernel_name)
```

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

### Initialize SocietyOfMindAgent with a team

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.agents.html

Example showing the setup of an inner team of agents and the initialization of a SocietyOfMindAgent.

```python
import asyncio
from autogen_agentchat.ui import Console
from autogen_agentchat.agents import AssistantAgent, SocietyOfMindAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4o")

    agent1 = AssistantAgent("assistant1", model_client=model_client, system_message="You are a writer, write well.")
    agent2 = AssistantAgent(
        "assistant2",
        model_client=model_client,
        system_message="You are an editor, provide critical feedback. Respond with 'APPROVE' if the text addresses all feedbacks.",
    )
    inner_termination = TextMentionTermination("APPROVE")
```

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

### Initialize CodeExecutorAgent with Docker

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_agentchat/agents/_code_executor_agent.html

Example of initializing the CodeExecutorAgent with a Docker-based code executor. Ensure Docker is installed and running.

```python
from autogen_agentchat.agents import CodeExecutorAgent
from autogen_ext.code_executors.docker import DockerCommandLineCodeExecutor

# Recommended: Use DockerCommandLineCodeExecutor for isolated code execution.
# Ensure Docker is installed and running.
code_executor = DockerCommandLineCodeExecutor(work_dir="./coding")

# Initialize the agent with the code executor.
code_executor_agent = CodeExecutorAgent(name="CodeExecutorAgent", code_executor=code_executor)
```

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

### Initialize AnthropicBedrockChatCompletionClient

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/models/anthropic/_anthropic_client.html

Example of setting up the Anthropic Bedrock client.

```python
import asyncio
from autogen_ext.models.anthropic import AnthropicBedrockChatCompletionClient, BedrockInfo
from autogen_core.models import UserMessage, ModelInfo


async def main():
```

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

### Internal Function Setup

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/local.html

Internal method to set up Python functions, including installing required packages and verifying syntax.

```APIDOC
## Internal Method: _setup_functions

### Description
This internal method sets up the Python functions for execution. It writes the function code to a file, installs any required Python packages using pip, and then attempts to load the function file to check for syntax errors.

### Method
Internal (async)

### Endpoint
N/A (Internal method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
N/A (Internal method)

### Response
#### Success Response (None)
This method does not return a value upon success; it performs setup actions.

#### Response Example
N/A (Internal method)
```

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

### Initialize Agents with Tools

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/agentchat-user-guide/tutorial/termination.ipynb.txt

Setup of primary and critic agents, where the critic agent is equipped with the approval tool.

```python
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(
    model="gpt-4o",
    temperature=1,
    # api_key="sk-...", # Optional if you have an OPENAI_API_KEY env variable set.
)

# Create the primary agent.
primary_agent = AssistantAgent(
    "primary",
    model_client=model_client,
    system_message="You are a helpful AI assistant.",
)

# Create the critic agent with the approve function as a tool.
critic_agent = AssistantAgent(
    "critic",
    model_client=model_client,
    tools=[approve],  # Register the approve function as a tool.
    system_message="Provide constructive feedback. Use the approve tool to approve when all feedbacks are addressed.",
)
```

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

### Create and Run a Web Surfing Agent

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/agents/web_surfer/_multimodal_web_surfer.html

Demonstrates initializing a MultimodalWebSurfer agent with an OpenAI model client and executing a task within a team.

```python
import asyncio
from autogen_agentchat.ui import Console
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.agents.web_surfer import MultimodalWebSurfer


async def main() -> None:
    # Define an agent
    web_surfer_agent = MultimodalWebSurfer(
        name="MultimodalWebSurfer",
        model_client=OpenAIChatCompletionClient(model="gpt-4o-2024-08-06"),
    )

    # Define a team
    agent_team = RoundRobinGroupChat([web_surfer_agent], max_turns=3)

    # Run the team and stream messages to the console
    stream = agent_team.run_stream(task="Navigate to the AutoGen readme on GitHub.")
    await Console(stream)
    # Close the browser controlled by the agent
    await web_surfer_agent.close()


asyncio.run(main())
```

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

### Register Agents and Start Runtime with Default Topic

Source: https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/framework/message-and-communication.html

This snippet demonstrates how to register agents and start the agent runtime using DefaultTopicId for publishing messages. It shows the typical setup for a broadcasting scenario where agents communicate using the default topic.

```python
runtime = SingleThreadedAgentRuntime()
await BroadcastingAgentDefaultTopic.register(
    runtime, "broadcasting_agent", lambda: BroadcastingAgentDefaultTopic("Broadcasting Agent")
)
await ReceivingAgent.register(runtime, "receiving_agent", lambda: ReceivingAgent("Receiving Agent"))
runtime.start()
await runtime.publish_message(Message("Hello, World! From the runtime!"), topic_id=DefaultTopicId())
await runtime.stop_when_idle()

```

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

### Load OpenAI Client from Configuration

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/models/openai/_openai_client.html

Shows how to instantiate a ChatCompletionClient using a dictionary-based configuration.

```python
from autogen_core.models import ChatCompletionClient

config = {
    "provider": "OpenAIChatCompletionClient",
    "config": {"model": "gpt-4o", "api_key": "REPLACE_WITH_YOUR_API_KEY"},
}

client = ChatCompletionClient.load_component(config)
```

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

### Output of Concurrent Task Processing

Source: https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/design-patterns/concurrent-agents.html

Example output showing that both 'Agent 1' and 'Agent 2' start and finish processing 'task-1' concurrently.

```text
Agent 1 starting task task-1
Agent 2 starting task task-1
Agent 1 finished task task-1
Agent 2 finished task task-1
```

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

### Initialize and Run CodeExecutorAgent

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_agentchat/agents/_code_executor_agent.html

Demonstrates starting the executor, configuring the agent, and running a task.

```python
# start the execution container
await code_executor.start()

code_executor_agent = CodeExecutorAgent(
    "code_executor_agent",
    code_executor=code_executor,
    model_client=model_client,
    approval_func=model_client_approval_func,
)

task = "Write python code to print Hello World!"
await Console(code_executor_agent.run_stream(task=task))

# stop the execution container
await code_executor.stop()
```

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

### Configure Agents with Reasoning Model

Source: https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/selector-group-chat.html

Sets up agents using a reasoning model client ('o3-mini'). System messages are kept concise as reasoning models infer instructions from context. This configuration is suitable for tasks where agents can self-direct.

```python
model_client = OpenAIChatCompletionClient(model="o3-mini")

web_search_agent = AssistantAgent(
    "WebSearchAgent",
    description="An agent for searching information on the web.",
    tools=[search_web_tool],
    model_client=model_client,
    system_message="""Use web search tool to find information.""",
)

data_analyst_agent = AssistantAgent(
    "DataAnalystAgent",
    description="An agent for performing calculations.",
    model_client=model_client,
    tools=[percentage_change_tool],
    system_message="""Use tool to perform calculation. If you have not seen the data, ask for it.""",
)

user_proxy_agent = UserProxyAgent(
    "UserProxyAgent",
    description="A user to approve or disapprove tasks.",
)

selector_prompt = """Select an agent to perform task.

{roles}

Current conversation context:
{history}

Read the above conversation, then select an agent from {participants} to perform the next task.
When the task is complete, let the user approve or disapprove the task.
"""

team = SelectorGroupChat(
    [web_search_agent, data_analyst_agent, user_proxy_agent],
    model_client=model_client,
    termination_condition=termination,  # Use the same termination condition as before.
    selector_prompt=selector_prompt,
    allow_repeated_speaker=True,
)

```

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

### Configure AgentChat Team with Tracing

Source: https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tracing.html

A complete example demonstrating the setup of a multi-agent team using AssistantAgent, tools, and a runtime configured with a NoOpTracerProvider to disable telemetry.

```python
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination
from autogen_agentchat.teams import SelectorGroupChat
from autogen_agentchat.ui import Console
from autogen_core import SingleThreadedAgentRuntime
from autogen_ext.models.openai import OpenAIChatCompletionClient


def search_web_tool(query: str) -> str:
    if "2006-2007" in query:
        return """Here are the total points scored by Miami Heat players in the 2006-2007 season:
        Udonis Haslem: 844 points
        Dwayne Wade: 1397 points
        James Posey: 550 points
        ...
        """
    elif "2007-2008" in query:
        return "The number of total rebounds for Dwayne Wade in the Miami Heat season 2007-2008 is 214."
    elif "2008-2009" in query:
        return "The number of total rebounds for Dwayne Wade in the Miami Heat season 2008-2009 is 398."
    return "No data found."


def percentage_change_tool(start: float, end: float) -> float:
    return ((end - start) / start) * 100


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4o")

    # Get a tracer with the default tracer provider.
    tracer = trace.get_tracer("tracing-autogen-agentchat")

    # Use the tracer to create a span for the main function.
    with tracer.start_as_current_span("run_team"):
        planning_agent = AssistantAgent(
            "PlanningAgent",
            description="An agent for planning tasks, this agent should be the first to engage when given a new task.",
            model_client=model_client,
            system_message="""
            You are a planning agent.
            Your job is to break down complex tasks into smaller, manageable subtasks.
            Your team members are:
                WebSearchAgent: Searches for information
                DataAnalystAgent: Performs calculations

            You only plan and delegate tasks - you do not execute them yourself.

            When assigning tasks, use this format:
            1. <agent> : <task>

            After all tasks are complete, summarize the findings and end with "TERMINATE".
            """,
        )

        web_search_agent = AssistantAgent(
            "WebSearchAgent",
            description="An agent for searching information on the web.",
            tools=[search_web_tool],
            model_client=model_client,
            system_message="""
            You are a web search agent.
            Your only tool is search_tool - use it to find information.
            You make only one search call at a time.
            Once you have the results, you never do calculations based on them.
            """,
        )

        data_analyst_agent = AssistantAgent(
            "DataAnalystAgent",
            description="An agent for performing calculations.",
            model_client=model_client,
            tools=[percentage_change_tool],
            system_message="""
            You are a data analyst.
            Given the tasks you have been assigned, you should analyze the data and provide results using the tools provided.
            If you have not seen the data, ask for it.
            """,
        )

        text_mention_termination = TextMentionTermination("TERMINATE")
        max_messages_termination = MaxMessageTermination(max_messages=25)
        termination = text_mention_termination | max_messages_termination

        selector_prompt = """Select an agent to perform task.

        {roles}

        Current conversation context:
        {history}

        Read the above conversation, then select an agent from {participants} to perform the next task.
        Make sure the planner agent has assigned tasks before other agents start working.
        Only select one agent.
        """

        task = "Who was the Miami Heat player with the highest points in the 2006-2007 season, and what was the percentage change in his total rebounds between the 2007-2008 and 2008-2009 seasons?"

        runtime = SingleThreadedAgentRuntime(
            tracer_provider=trace.NoOpTracerProvider(),  # Disable telemetry for runtime.
        )
        runtime.start()

        team = SelectorGroupChat(
```

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

### Simple UserProxyAgent Usage

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.agents.html

Demonstrates basic interaction with UserProxyAgent. Ensure necessary imports are present. This example shows a straightforward way to get a response from the agent.

```python
import asyncio
from autogen_core import CancellationToken
from autogen_agentchat.agents import UserProxyAgent
from autogen_agentchat.messages import TextMessage


async def simple_user_agent():
    agent = UserProxyAgent("user_proxy")
    response = await asyncio.create_task(
        agent.on_messages(
            [TextMessage(content="What is your name? ", source="user")],
            cancellation_token=CancellationToken(),
        )
    )
    assert isinstance(response.chat_message, TextMessage)
    print(f"Your name is {response.chat_message.content}")

```

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

### Initialize and Run MultimodalWebSurfer

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_ext.agents.web_surfer.html

Demonstrates how to instantiate the MultimodalWebSurfer agent, add it to a group chat, and execute a web-based task.

```python
from autogen_ext.agents.web_surfer import MultimodalWebSurfer


async def main() -> None:
    # Define an agent
    web_surfer_agent = MultimodalWebSurfer(
        name="MultimodalWebSurfer",
        model_client=OpenAIChatCompletionClient(model="gpt-4o-2024-08-06"),
    )

    # Define a team
    agent_team = RoundRobinGroupChat([web_surfer_agent], max_turns=3)

    # Run the team and stream messages to the console
    stream = agent_team.run_stream(task="Navigate to the AutoGen readme on GitHub.")
    await Console(stream)
    # Close the browser controlled by the agent
    await web_surfer_agent.close()


asyncio.run(main())
```

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

### Swarm with Human-in-the-Loop Handoff

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.teams.html

This example shows how to use HandoffTermination for human-in-the-loop interactions within a Swarm. It includes starting a conversation and resuming with user feedback using Console.

```python
import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import Swarm
from autogen_agentchat.conditions import HandoffTermination, MaxMessageTermination
from autogen_agentchat.ui import Console
from autogen_agentchat.messages import HandoffMessage


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4o")

    agent = AssistantAgent(
        "Alice",
        model_client=model_client,
        handoffs=["user"],
        system_message="You are Alice and you only answer questions about yourself, ask the user for help if needed.",
    )
    termination = HandoffTermination(target="user") | MaxMessageTermination(3)
    team = Swarm([agent], termination_condition=termination)

    # Start the conversation.
    await Console(team.run_stream(task="What is bob's birthday?"))

    # Resume with user feedback.
    await Console(
        team.run_stream(
            task=HandoffMessage(source="user", target="Alice", content="Bob's birthday is on 1st January.")
        )
    )


asyncio.run(main())
```

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

### Initialize OpenAIAgent with basic tools

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/agents/openai/_openai_agent.html

Demonstrates basic agent initialization using a tool that does not require additional parameters.

```python
import asyncio

from autogen_agentchat.ui import Console
from autogen_ext.agents.openai import OpenAIAgent
from openai import AsyncOpenAI


async def example():
    client = AsyncOpenAI()
    agent = OpenAIAgent(
        name="SimpleAgent",
        description="A simple OpenAI agent using the Responses API",
        client=client,
        model="gpt-4.1",
        instructions="You are a helpful assistant.",
        tools=["web_search_preview"],  # Only tools without required params
    )
    await Console(agent.run_stream(task="Search for recent AI developments"))


asyncio.run(example())
```

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

### Integrate remote MCP tool with AutoGen

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/tools/mcp/_streamable_http.html

Example showing how to configure server parameters, initialize the adapter, and assign it to an AssistantAgent.

```python
import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import StreamableHttpMcpToolAdapter, StreamableHttpServerParams
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_core import CancellationToken


async def main() -> None:
    # Create server params for the remote MCP service
    server_params = StreamableHttpServerParams(
        url="https://api.example.com/mcp",
        headers={"Authorization": "Bearer your-api-key", "Content-Type": "application/json"},
        timeout=30.0,  # HTTP timeout in seconds
        sse_read_timeout=300.0,  # SSE read timeout in seconds (5 minutes)
        terminate_on_close=True,
    )

    # Get the translation tool from the server
    adapter = await StreamableHttpMcpToolAdapter.from_server_params(server_params, "translate")

    # Create an agent that can use the translation tool
    model_client = OpenAIChatCompletionClient(model="gpt-4")
    agent = AssistantAgent(
        name="translator",
        model_client=model_client,
        tools=[adapter],
        system_message="You are a helpful translation assistant.",
    )

    # Let the agent translate some text
    await Console(
        agent.run_stream(task="Translate 'Hello, how are you?' to Spanish", cancellation_token=CancellationToken())
    )


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

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

### Run Coding Task with Design Pattern

Source: https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/design-patterns/reflection.html

Initiate a coding task by publishing a message to the default topic. Agents decorated with `default_subscription()` automatically subscribe. This example starts a code writing task.

```python
from autogen_core import DefaultTopicId, SingleThreadedAgentRuntime
from autogen_ext.models.openai import OpenAIChatCompletionClient

runtime = SingleThreadedAgentRuntime()
model_client = OpenAIChatCompletionClient(model="gpt-4o-mini")
await ReviewerAgent.register(runtime, "ReviewerAgent", lambda: ReviewerAgent(model_client=model_client))
await CoderAgent.register(runtime, "CoderAgent", lambda: CoderAgent(model_client=model_client))
runtime.start()
await runtime.publish_message(
    message=CodeWritingTask(task="Write a function to find the sum of all even numbers in a list."),
    topic_id=DefaultTopicId(),
)

# Keep processing messages until idle.
await runtime.stop_when_idle()
```

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

### Run AutoGen Studio with an Azure SQL database

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/autogenstudio-user-guide/faq.md.txt

Example command to connect AutoGen Studio to an Azure SQL database using its specific connection string format. Requires `pyodbc` to be installed.

```bash
autogenstudio ui --database-uri mssql+pyodbc:///?odbc_connect=DRIVER%3D%7BODBC+Driver+17+for+SQL+Server%7D%3BSERVER%3Dtcp%3Aservername.database.windows.net%2C1433%3BDATABASE%3Ddatabasename%3BUID%3Dusername%3BPWD%3Dpassword123%3BEncrypt%3Dyes%3BTrustServerCertificate%3Dno%3BConnection+Timeout%3D30%3B
```

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

### Configure OpenAIAgent with Tools

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/agents/openai/_openai_agent.html

Instantiate an OpenAIAgent with a list of tools, including configurations for search context size. This example demonstrates how to set up an agent with specific tools for a task.

```python
tools = [
                    {
                        "type": "web_search_preview",
                        "description": "Search the web for information",
                        "search_args": {
                            "city": "San Francisco",  # optional
                        },
                        "search_context_size": "low",  # optional
                    },
                    # "image_generation",  # Simple tools can still use string format
                ]

                agent = OpenAIAgent(
                    name="ConfiguredAgent",
                    description="An agent with configured tools",
                    client=client,
                    model="gpt-4.1",
                    instructions="You are a helpful assistant with specialized tools.",
                    tools=tools,  # type: ignore
                )
                await Console(agent.run_stream(task="Search for recent AI developments"))
```

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

### Get Required Parameters Help for Tool

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/agents/openai/_openai_agent.html

Retrieves help text for the required parameters of a specific tool. This is used internally to guide users on how to correctly configure tools that need specific arguments.

```python
def _get_required_params_help(self, tool_name: str) -> str:
        """Get help text for required parameters of a tool."""
        help_text = {
            "file_search": "vector_store_ids (List[str])",

```

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

### Install and Run AutoGen Studio

Source: https://microsoft.github.io/autogen/stable/index.html

Install AutoGen Studio using pip and run the UI on a specified port and application directory.

```bash
pip install -U autogenstudio
autogenstudio ui --port 8080 --appdir ./myapp
```

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

### Poetry Generation with Max Turns (1 Turn)

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/agentchat-user-guide/tutorial/human-in-the-loop.ipynb.txt

This example demonstrates using `max_turns=1` in a `RoundRobinGroupChat` for a poetry generation task. It shows how the team stops after one turn and how user feedback can guide subsequent turns. The output includes conversation summaries and token usage.

```python
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient

# Create the agents.
model_client = OpenAIChatCompletionClient(model="gpt-4o-mini")
assistant = AssistantAgent("assistant", model_client=model_client)

# Create the team setting a maximum number of turns to 1.
team = RoundRobinGroupChat([assistant], max_turns=1)

task = "Write a 4-line poem about the ocean."
while True:
    # Run the conversation and stream to the console.
    stream = team.run_stream(task=task)
    # Use asyncio.run(...) when running in a script.
    await Console(stream)
    # Get the user response.
    task = input("Enter your feedback (type 'exit' to leave): ")
    if task.lower().strip() == "exit":
        break
await model_client.close()
```

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

### Use OpenAI o1-mini with AssistantAgent

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.agents.html

This example shows how to initialize an AssistantAgent with OpenAI's o1-mini model. Note that o1 series models do not support system messages.

```python
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent


async def main() -> None:
    model_client = OpenAIChatCompletionClient(
        model="o1-mini",
        # api_key = "your_openai_api_key"
    )
    # The system message is not supported by the o1 series model.
    agent = AssistantAgent(name="assistant", model_client=model_client, system_message=None)

    result = await agent.run(task="What is the capital of France?")
    print(result.messages[-1].content)  # type: ignore


asyncio.run(main())
```

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

### Install AutoGen Extensions

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/extensions-user-guide/installation.md.txt

Install the main AutoGen Extensions package using pip. This command installs the core functionalities.

```sh
pip install "autogen-ext"
```

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

### Create and Run a Basic Assistant Agent

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_agentchat/agents/_assistant_agent.html

Demonstrates creating an AssistantAgent with a model client and running a simple task. Ensure the model client is properly configured with a model name and optionally an API key.

```python
import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent


async def main() -> None:
    model_client = OpenAIChatCompletionClient(
        model="gpt-4o",
        # api_key = "your_openai_api_key"
    )
    agent = AssistantAgent(name="assistant", model_client=model_client)

    result = await agent.run(task="Name two cities in North America.")
    print(result)


asyncio.run(main())
```

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

### McpWorkbench - Configuration and Instantiation

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_ext.tools.mcp.html

Information on how to configure and create instances of the McpWorkbench.

```APIDOC
## McpWorkbench Configuration and Instantiation

### Get Configuration

Returns the configuration required to create a new instance of the component.

- **Method**: `to_config()`
- **Endpoint**: `to_config()`
- **Description**: Dumps the configuration of the current instance.
- **Returns**:
  - **McpWorkbenchConfig** - The configuration object.

### Create From Configuration

Creates a new instance of the component from a configuration object.

- **Method**: `classmethod __from_config(config: McpWorkbenchConfig)`
- **Endpoint**: `__from_config(config)`
- **Description**: Instantiates the workbench using a provided configuration.
- **Parameters**:
  - **config** (McpWorkbenchConfig) - Required - The configuration object.
- **Returns**:
  - **Self** - A new instance of McpWorkbench.
```

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

### Install Local Filesystem MCP Server

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_ext.tools.mcp.html

Install the filesystem server package globally using npm. Ensure Node.js 16+ is installed.

```bash
npm install -g @modelcontextprotocol/server-filesystem
```

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

### Install Open Telemetry SDK

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/core-user-guide/framework/telemetry.md.txt

Install the Open Telemetry SDK for Python. This is a prerequisite for instrumenting your application.

```bash
pip install opentelemetry-sdk
```

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

### Start Agent Runtime

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_core/_single_threaded_agent_runtime.html

Starts the runtime message processing loop in a background task. Ensure the runtime is not already started to avoid errors.

```python
import asyncio
from autogen_core import SingleThreadedAgentRuntime


async def main() -> None:
    runtime = SingleThreadedAgentRuntime()
    runtime.start()

    # ... do other things ...

    await runtime.stop()


asyncio.run(main())
```

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

### Load AzureOpenAIChatCompletionClient from Configuration

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/models/openai/_openai_client.html

Shows how to instantiate the client using a dictionary configuration and the load_component method.

```python
from autogen_core.models import ChatCompletionClient

config = {
    "provider": "AzureOpenAIChatCompletionClient",
    "config": {
        "model": "gpt-4o-2024-05-13",
        "azure_endpoint": "https://{your-custom-endpoint}.openai.azure.com/",
        "azure_deployment": "{your-azure-deployment}",
        "api_version": "2024-06-01",
        "azure_ad_token_provider": {
            "provider": "autogen_ext.auth.azure.AzureTokenProvider",
            "config": {
                "provider_kind": "DefaultAzureCredential",
                "scopes": ["https://cognitiveservices.azure.com/.default"],
            },
        },
    },
}

client = ChatCompletionClient.load_component(config)
```

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

### Install Ollama Extension for AutoGen

Source: https://microsoft.github.io/autogen/stable/_sources/user-guide/agentchat-user-guide/tutorial/models.ipynb.txt

Install the Ollama extension for AutoGen using pip. This command ensures that the necessary packages for Ollama integration are installed.

```shell
pip install -U "autogen-ext[ollama]"
```

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

### Initialize Azure AI Search Tools

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/tools/azure/_ai_search.html

Examples for creating full-text and semantic search tools, including integration with agents.

```python
full_text_tool = AzureAISearchTool.create_full_text_search(
    name="doc-search",
    endpoint="https://your-search.search.windows.net",  # Your Azure AI Search endpoint
    index_name="<your-index>",  # Name of your search index
    credential=AzureKeyCredential("<your-key>"),  # Your Azure AI Search admin key
    query_type="full",  # Enable Lucene query syntax
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)
```

```python
semantic_tool = AzureAISearchTool.create_full_text_search(
    name="semantic-search",
    endpoint="https://your-search.search.windows.net",
    index_name="<your-index>",
    credential=AzureKeyCredential("<your-key>"),
    query_type="semantic",  # Enable semantic ranking
    semantic_config_name="<your-semantic-config>",  # Required for semantic search
    search_fields=["content", "title"],  # Required: fields to search within
    select_fields=["content", "title", "url"],  # Optional: fields to return
    top=5,
)
```

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

### Internal Code Execution (No Setup Check)

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/local.html

Internal method to execute code blocks without re-checking the setup. Used after initial setup is confirmed.

```APIDOC
## Internal Method: _execute_code_dont_check_setup

### Description
Executes the provided code blocks in the local command line without re-checking the setup. This method is used internally after the initial setup of functions is complete.

### Method
Internal (async)

### Endpoint
N/A (Internal method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **code_blocks** (List[CodeBlock]) - Required - The code blocks to execute.
- **cancellation_token** (CancellationToken) - Required - A token to cancel the operation.

### Request Example
```json
{
  "code_blocks": [
    {
      "language": "python",
      "code": "import sys\nprint(sys.version)"
    }
  ],
  "cancellation_token": null
}
```

### Response
#### Success Response (None)
Returns a `CommandLineCodeResult` object.
  - **exit_code** (int) - The exit code of the executed command.
  - **output** (str) - The standard output of the executed command.
  - **code_file** (str) - The path to the generated code file, if applicable.

#### Response Example
```json
{
  "exit_code": 0,
  "output": "3.9.12 (main, Jun  1 2022, 06:34:44)\n[GCC 11.2.0]\n",
  "code_file": null
}
```
```

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

### Install autogen-ext with mcp extra

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/tools/mcp/_sse.html

To use the SseMcpToolAdapter, ensure you have installed the 'autogen-ext' package with the 'mcp' extra. This command installs the necessary dependencies for MCP integration.

```bash
pip install -U "autogen-ext[mcp]"
```

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

### Initialize Agent with o1-mini

Source: https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.agents.html

Basic setup for using the o1-mini model with an assistant agent.

```python
import asyncio
```

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

### Install Autogen Extension for OpenAI Assistant

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/agents/openai/_openai_assistant_agent.html

Provides installation instructions for the autogen-ext package with OpenAI Assistant support. Use the 'azure' extra for Azure OpenAI Assistant.

```bash
pip install "autogen-ext[openai]"  # For OpenAI Assistant
# pip install "autogen-ext[openai,azure]"  # For Azure OpenAI Assistant
```

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

### Start Kernel

Source: https://microsoft.github.io/autogen/stable/_modules/autogen_ext/code_executors/docker_jupyter/_jupyter_server.html

Starts a new kernel on the Jupyter server.

```APIDOC
## POST /api/kernels

### Description
Starts a new kernel on the Jupyter server.

### Method
POST

### Endpoint
/api/kernels

### Parameters
#### Request Body
- **kernel_spec_name** (str) - Required - The name of the kernel specification to start.

### Request Example
```json
{
  "name": "python3"
}
```

### Response
#### Success Response (200)
- **str** - The ID of the newly started kernel.
```

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

### Register and Run the Agent

Source: https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/components/model-clients.html

Setup code to register the agent with a runtime and send a message.

```python
# Create the runtime and register the agent.
from autogen_core import AgentId

model_client = OpenAIChatCompletionClient(
    model="gpt-4o-mini",
    # api_key="sk-...", # Optional if you have an OPENAI_API_KEY set in the environment.
)

runtime = SingleThreadedAgentRuntime()
await SimpleAgent.register(
    runtime,
    "simple_agent",
    lambda: SimpleAgent(model_client=model_client),
)
# Start the runtime processing messages.
runtime.start()
# Send a message to the agent and get the response.
message = Message("Hello, what are some fun things to do in Seattle?")
response = await runtime.send_message(message, AgentId("simple_agent", "default"))
print(response.content)
```

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

### Install Semantic Kernel Provider Extras

Source: https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/models.html

Install the necessary extras for the Semantic Kernel adapter based on the provider you intend to use. For Anthropic models, install `semantic-kernel-anthropic`.

```bash
# pip install "autogen-ext[semantic-kernel-anthropic]"

```
Tokens:
Raw