Agent Framework

https://learn.microsoft.com/en-us/agent-framework/
Admin
Agent Framework is a tool to build robust, future-proof Agentic AI solutions that evolve with...
Tokens:735,987
Snippets:5,650
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start the backend server with example agents

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Run these commands in the examples directory to start the backend server with the example agents. The server will start on http://localhost:8888 by default.

```bash
cd integrations/microsoft-agent-framework/python/examples
uv run dev

```

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

### Start the backend server

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Restores and runs the sample server with the example agents. The server will start on http://localhost:8889.

```bash
dotnet restore AGUIDojoServer/AGUIDojoServer.csproj
dotnet run --project AGUIDojoServer/AGUIDojoServer.csproj --urls "http://localhost:8889"

```

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

### Install dependencies and start the Dojo frontend

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Run these commands in a new terminal window from the root of the AG-UI repository to install dependencies and start the Dojo frontend. The frontend will be available at http://localhost:3000.

```bash
cd apps/dojo
pnpm install
pnpm dev

```

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

### Run the server on localhost:8888

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/getting-started

Starts the server on the URL used by the client example. Use this command after building the server.

```dotnetcli
dotnet run --urls http://localhost:8888

```

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

### Start the Dojo frontend

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Navigates to the Dojo application directory, installs dependencies, sets the AGENT_FRAMEWORK_DOTNET_URL environment variable to point to the .NET server, and starts the development server. The frontend will be available at http://localhost:3000. Set AGENT_FRAMEWORK_DOTNET_URL before running pnpm dev; this variable makes the 'Microsoft Agent Framework (.NET)' entry appear in Dojo.

```bash
cd apps/dojo
pnpm install
export AGENT_FRAMEWORK_DOTNET_URL="http://localhost:8889"
pnpm dev

```

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

### Install agent-framework-ag-ui with uv

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/getting-started

Alternative installation using uv with prerelease allowed. Requires uv installed.

```bash
uv pip install agent-framework-ag-ui --prerelease=allow

```

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

### Set up observability in Agent Framework

Source: https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen/index

Shows zero-code setup via environment variables (OTEL_EXPORTER_OTLP_ENDPOINT) and manual configuration with configure_otel_providers(). Observability is automatically applied to agents and workflows, as shown in the async example.

```python
from agent_framework import Agent
from agent_framework.observability import configure_otel_providers
from agent_framework.openai import OpenAIChatClient

# Zero-code setup via environment variables
# Set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Or manual setup
configure_otel_providers()

# Create client for the example
client = OpenAIChatClient(model="gpt-5")

async def observability_example():
    # Observability is automatically applied to all agents and workflows
    agent = Agent(name="assistant", client=client)
    result = await agent.run("Hello")  # Automatically traced
```

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

### Install agent-framework-ag-ui package

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/getting-started

Install the AG-UI package which includes the AGUIChatClient. The package is already installed with agent-framework-ag-ui.

```bash
pip install agent-framework-ag-ui --pre
```

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

### Main function to run hosted-agent session examples

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/agent-services/foundry

Sets up credentials, reads environment variables, creates the project client, and runs the session examples. This is the entry point for the script.

```python
async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(
```

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

### Middleware sequence and agent-hooks-sdk installation

Source: https://learn.microsoft.com/en-us/agent-framework/support/upgrade/python-2026-significant-changes

Agent constructors now require middleware as a sequence, not a single value. The agent-framework-core[agent-hooks] extra is removed; install agent-hooks-sdk directly. The before example shows the old single-value usage, and the after examples show the new sequence and the required pip install.

```python
agent = Agent(client=client, middleware=hooks)

```

```bash
pip install agent-hooks-sdk

```

```python
agent = Agent(client=client, middleware=[hooks])

```

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

### Install Python dependencies with uv

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Uses uv to install the required Python dependencies for the examples.

```bash
uv sync
```

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

### Initialize .NET quickstart project

Source: https://learn.microsoft.com/en-us/agent-framework/hosting/azure-functions

Initializes a new project from the durable-agents-quickstart-dotnet template using Azure Developer CLI. Prompts for an environment name.

```console
azd init --template durable-agents-quickstart-dotnet

```

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

### Navigate to examples directory

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Changes to the directory containing Microsoft Agent Framework Python examples.

```bash
cd integrations/microsoft-agent-framework/python/examples
```

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

### Decorator-based chat middleware example

Source: https://learn.microsoft.com/en-us/agent-framework/concepts/agents/middleware/chat-middleware

Starts a decorator-based chat middleware example with imports and type hints.

```python
# Copyright (c) Microsoft. All rights reserved.

import asyncio
from collections.abc import Awaitable, Callable
from random import randint
from typing import Annotated
```

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

### Run the PEP 723 sample locally with uv

Source: https://learn.microsoft.com/en-us/agent-framework/get-started/hosting

Runs the get-started sample from the Agent Framework repository root using uv. Requires the PEP 723 sample file and the repository root as the working directory.

```Bash
uv run python/samples/01-get-started/07_hosting.py

```

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

### Create .env file from template

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Copies the provided .env.example template to .env for configuration.

```bash
cp .env.example .env
```

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

### C#: Install required NuGet packages

Source: https://learn.microsoft.com/en-us/agent-framework/agents/tools/local-mcp-tools

Commands to install the required NuGet packages for the C# MCP server example.

```bash
dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Microsoft.Extensions.Hosting
dotnet add package ModelContextProtocol

```

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

### Install Agent Framework Go and Copilot SDK

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/agent-services/github-copilot

Run this command to install the required Go modules for the Agent Framework and GitHub Copilot SDK. Requires Go 1.25 or later.

```bash
go get github.com/microsoft/agent-framework-go github.com/github/copilot-sdk/go

```

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

### Install agent-framework-gemini package

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/model-providers/google-gemini

Install the Python agent-framework-gemini package with the --pre flag to get the latest pre-release version.

```bash
pip install agent-framework-gemini --pre

```

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

### Example .env file

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/devui/directory-discovery

Shows an example `.env` file with environment variables for OpenAI and Azure OpenAI. DevUI automatically loads `.env` files if present, at entity-level or parent-level.

```bash
OPENAI_API_KEY=sk-...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

```

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

### Install agent-framework-claude with pip

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/agent-services/anthropic-claude

Install the agent-framework-claude package using pip with the --pre flag to get the pre-release version.

```bash
pip install agent-framework-claude --pre
```

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

### Install A2A package with pip

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/agent-services/a2a

Install the agent-framework-a2a package using pip with the --pre flag to get the pre-release version.

```bash
pip install agent-framework-a2a --pre

```

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

### Install agent-framework-monty and agent-framework-foundry

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/context-providers/monty

Install the required packages for Monty CodeAct provider. Use the --pre flag to get the pre-release version.

```bash
pip install agent-framework-monty agent-framework-foundry --pre

```

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

### Example interaction with server and client running

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/state-management

Shows a sample conversation and the resulting state output when the server and client are running. The user can use :q to quit and :state to show the current state at any time.

```text
User (:q to quit, :state to show state): I want to make a classic Italian pasta carbonara

[Run Started]
[Calling Tool: update_recipe]
[State Updated]
[State Updated]
[State Updated]
[Tool Result: Recipe updated.]
Here's your recipe!
[Run Finished]

============================================================
CURRENT STATE
============================================================

recipe:
  title: Classic Pasta Carbonara
  skill_level: Intermediate
  special_preferences: ['Authentic Italian']
  cooking_time: 30 min
  ingredients:
    - 🍝 Spaghetti: 400g
    - 🥓 Guanciale or bacon: 200g
    - 🥚 Egg yolks: 4
    - 🧀 Pecorino Romano: 100g grated
    - 🧂 Black pepper: To taste
  instructions:
    1. Bring a large pot of salted water to boil
    2. Cut guanciale into small strips and fry until crispy
    3. Beat egg yolks with grated Pecorino and black pepper
    4. Cook spaghetti until al dente
    5. Reserve 1 cup pasta water, then drain pasta
    6. Remove pan from heat, add hot pasta to guanciale
    7. Quickly stir in egg mixture, adding pasta water to create creamy sauce
    8. Serve immediately with extra Pecorino and black pepper

============================================================

```

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

### Python Middleware Termination Example Imports

Source: https://learn.microsoft.com/en-us/agent-framework/concepts/agents/middleware/termination

Imports and setup for a Python middleware termination example using the agent_framework library, FoundryChatClient, and AzureCliCredential. This is the beginning of a pre-termination middleware example that blocks disallowed content.

```python
# Copyright (c) Microsoft. All rights reserved.

import asyncio
from collections.abc import Awaitable, Callable
from random import randint
from typing import Annotated

from agent_framework import (
    AgentContext,
    AgentMiddleware,
    AgentResponse,
    Message,
    MiddlewareTermination,
    tool,
)
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
```

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

### Install Agent Hooks middleware bundle first in agent middleware list

Source: https://learn.microsoft.com/en-us/agent-framework/agents/agent-hooks

Place the Agent Hooks bundle first in the agent's middleware list to form the outermost enforcement boundary. The example shows creating an Agent with a middleware list that starts with the Agent Hooks middleware wrapping a SecretEgressGuard, followed by application middleware.

```python
agent = Agent(
    client=client,
    middleware=[
        create_agent_hooks_middleware([SecretEgressGuard()]),
        application_middleware,
    ],
)
```

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

### Install agent-framework-mistral package

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/model-providers/mistral

Installs the Mistral integration package for Agent Framework Python. Use the --pre flag to get the latest pre-release version.

```bash
pip install agent-framework-mistral --pre

```

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

### Navigate to the Microsoft Agent Framework examples directory

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/testing-with-dojo

Changes the current directory to the Microsoft Agent Framework .NET examples directory within the cloned repository.

```bash
cd integrations/microsoft-agent-framework/dotnet/examples

```

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

### Initialize Python quickstart project

Source: https://learn.microsoft.com/en-us/agent-framework/hosting/azure-functions

Initializes a new project from the durable-agents-quickstart-python template using Azure Developer CLI. Prompts for an environment name.

```console
azd init --template durable-agents-quickstart-python

```

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

### Install agent-framework-azure-contentunderstanding package

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/context-providers/azure-content-understanding

Install the Azure Content Understanding integration package using pip. Requires the --pre flag to get the pre-release version.

```bash
pip install agent-framework-azure-contentunderstanding --pre

```

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

### Install agent-framework-hosting package with pip

Source: https://learn.microsoft.com/en-us/agent-framework/hosting/self-hosting

Install the prerelease agent-framework-hosting package. Use the --pre flag explicitly to include prerelease packages.

```bash
pip install --pre agent-framework-hosting

```

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

### Install configuration packages for user secrets and environment variables

Source: https://learn.microsoft.com/en-us/agent-framework/workflows/declarative

Install configuration packages to load settings from user secrets and environment variables, as used by the examples in this article.

```bash
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

```

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

### Create timing middleware and configure agent (Go)

Source: https://learn.microsoft.com/en-us/agent-framework/concepts/agents/agent-pipeline

Shows how to create a lightweight middleware using agent.MiddlewareFunc that logs the duration of the agent run, and then configure an agent with that middleware using foundryprovider.NewAgent and agent.Config.

```go
timing := agent.MiddlewareFunc(
    func(next agent.RunFunc, ctx context.Context, messages []*message.Message, options ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error] {
        start := time.Now()
        return func(yield func(*agent.ResponseUpdate, error) bool) {
            defer log.Printf("agent run completed in %s", time.Since(start))
            for update, err := range next(ctx, messages, options...) {
                if !yield(update, err) {
                    return
                }
            }
        }
    },
)

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        Middlewares: []agent.Middleware{timing},
    },
})

```

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

### Install agent-framework-typesafe package

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-provider/type-safe-ai

Installs the alpha TypeSafe AI integration package for Agent Framework Python. Use the --pre flag to get the pre-release version.

```bash
pip install agent-framework-typesafe --pre

```

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

### Install Azure Cosmos DB memory packages

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/context-providers/azure-cosmos

Install the Azure Cosmos DB memory provider and Foundry packages using pip. The --pre flag is required to get the pre-release versions.

```bash
pip install agent-framework-azure-cosmos-memory agent-framework-foundry --pre

```

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

### Create vector store and run agent with file search (Python)

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/context-providers/microsoft-foundry

Python example showing how to create a vector store, use the file search tool, and run an agent with the Foundry chat client. Requires Azure CLI login via 'az login'.

```python
async def create_vector_store(client: FoundryChatClient) -> tuple[str, str]:
    """Create a vector store with sample documents."""
    file = await client.client.files.create(
        file=("todays_weather.txt", b"The weather today is sunny with a high of 75F."), purpose="assistants"
    )
    vector_store = await client.client.vector_stores.create(
        name="knowledge_base",
        expires_after={"anchor": "last_active_at", "days": 1},
    )
    result = await client.client.vector_stores.files.create_and_poll(vector_store_id=vector_store.id, file_id=file.id)
    if result.last_error is not None:
        raise Exception(f"Vector store file processing failed with status: {result.last_error.message}")

    return file.id, vector_store.id


async def delete_vector_store(client: FoundryChatClient, file_id: str, vector_store_id: str) -> None:
    """Delete the vector store after using it."""
    with contextlib.suppress(Exception):
        await client.client.vector_stores.delete(vector_store_id=vector_store_id)
    with contextlib.suppress(Exception):
        await client.client.files.delete(file_id=file_id)


async def main() -> None:
    print("=== Foundry Chat Client with File Search Example ===\n")

    # Initialize the Foundry chat client
    # Make sure you're logged in via 'az login' before running this sample
    client = FoundryChatClient(credential=AzureCliCredential())

    file_id, vector_store_id = await create_vector_store(client)

    # Create file search tool using instance method
    file_search_tool = client.get_file_search_tool(vector_store_ids=[vector_store_id])

    agent = Agent(
        client=client,
        instructions="You are a helpful assistant that can search through files to find information.",
        tools=[file_search_tool],
    )

    query = "What is the weather today? Do a file search to find the answer."
    print(f"User: {query}")
    result = await agent.run(query)
    print(f"Agent: {result}\n")

    await delete_vector_store(client, file_id, vector_store_id)

```

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

### Apply a transform

Source: https://learn.microsoft.com/en-us/agent-framework/agents/agent-hooks

A transform path must start at `$target`. For example, an interceptor can replace final response content.

```APIDOC
## Apply a transform

### Description
A transform path must start at `$target`. For example, an interceptor can replace final response content.

### Python Example
```python
from agent_hooks import ALLOW, AgentContext, Decision, Transform, Verdict


class OutputRedactor:
    def intercept(self, context: AgentContext) -> Verdict:
        if context["interception_point"] != "output":
            return ALLOW

        return Verdict(
            decision=Decision.TRANSFORM,
            reason="redacted_output",
            transform=Transform(
                path="$target.content",
                value="[Response removed by policy]",
            ),
        )
```

### Behavior
- Transforms are applied to Agent Framework `Content` values, preserving supported rich content rather than reducing every value to plain text.
- A malformed path or incompatible replacement fails closed instead of continuing with the original value.
```

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

### Run the AG-UI server with python

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/getting-started

Starts the server by running server.py. The server listens on http://127.0.0.1:8888.

```bash
python server.py

```

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

### Run a workflow agent streaming

Source: https://learn.microsoft.com/en-us/agent-framework/workflows/as-agents

Runs the workflow agent with RunStreamingAsync() to get real-time updates. The example prints text updates as they arrive.

```C#
var messages = new List<ChatMessage>
{
    new(ChatRole.User, "Write an article about renewable energy trends in 2025")
};

await foreach (AgentResponseUpdate update in workflowAgent.RunStreamingAsync(messages, session))
{
    // Process streaming updates from each agent in the workflow
    if (!string.IsNullOrEmpty(update.Text))
    {
        Console.Write(update.Text);
    }
}

```

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

### Create an agent with tools

Source: https://learn.microsoft.com/en-us/agent-framework/tutorials/agents/function-tools

Configures an agent with a slice of tools in `agent.Config` and runs a text query that invokes tool calling.

```go
a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Tools: []tool.Tool{weatherTool},
    },
})

resp, err := a.RunText(ctx, "What is the weather like in Amsterdam?").Collect()

```

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

### Install Valkey and Foundry packages

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/context-providers/valkey

Adds the Microsoft.Agents.AI.Valkey and Microsoft.Agents.AI.Foundry packages with the --prerelease flag.

```bash
dotnet add package Microsoft.Agents.AI.Valkey --prerelease
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

```

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

### Install AG-UI hosting package

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/ui/ag-ui/getting-started

Adds the Microsoft.Agents.AI.Hosting.AGUI.AspNetCore package to the project. Use the --prerelease flag to get the latest prerelease version.

```dotnetcli
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease

```

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

### Agent creation and run: tools and instructions as keyword args, options for run

Source: https://learn.microsoft.com/en-us/agent-framework/support/upgrade/typed-options-guide-python

Shows the before and after for agent creation and run. On creation, `tools` and `instructions` remain keyword arguments, with `model` moved to `default_options`. For `run()`, only `tools` is a keyword argument, and other parameters go into `options`.

```python
# Before
agent = Agent(
    client=client,
    name="assistant",
    tools=[my_function],
    instructions="You are helpful.",
    model="gpt-4",
)

# After - tools and instructions stay as keyword args on creation
agent = Agent(
    client=client,
    name="assistant",
    tools=[my_function],  # Still a keyword argument!
    instructions="You are helpful.",  # Still a keyword argument!
    default_options={"model": "gpt-4"},
)

# For run(), only tools is available as keyword argument
response = await agent.run(
    "Hello!",
    tools=[another_function],  # Can override tools
    options={"max_tokens": 100},
)
```

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

### Stream responses from GitHubCopilotAgent

Source: https://learn.microsoft.com/en-us/agent-framework/integrations/by-component/agent-services/github-copilot

Shows how to get responses as they are generated by passing stream=True to the run method. The example prints each text chunk as it arrives.

```python
async def streaming_example():
    agent = GitHubCopilotAgent(
        instructions="You are a helpful assistant.",
    )

    async with agent:
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run("Tell me a short story.", stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
        print()

```

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

### Orchestration instance response JSON

Source: https://learn.microsoft.com/en-us/agent-framework/hosting/azure-functions

Example response from starting an orchestration, containing URLs for querying status, sending events, terminating, and purging history.

```json
{
  "id": "abc123def456",
  "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456",
  "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/{eventName}",
  "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/terminate",
  "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456"
}

```
Tokens:
Raw