Skip to content

samples

Directory actions

More options

Directory actions

More options

Latest commit

History

History

samples

README.md

Python Samples

This directory contains samples demonstrating the capabilities of Microsoft Agent Framework for Python.

Structure

FolderDescription
01-get-started/Progressive tutorial: hello agent → hosting
02-agents/Deep-dive by concept: tools, middleware, providers, orchestrations
03-workflows/Workflow patterns: sequential, concurrent, state, declarative
04-hosting/Deployment: Azure Functions, Durable Tasks, A2A
05-end-to-end/Full applications, evaluation, demos

Getting Started

Start with 01-get-started/ and work through the numbered files:

  1. 01_hello_agent.py — Create and run your first agent
  2. 02_add_tools.py — Add function tools with @tool
  3. 03_multi_turn.py — Multi-turn conversations with AgentSession
  4. 04_memory.py — Agent memory with ContextProvider
  5. 05_functional_workflow_with_agents.py — Call agents inside a functional workflow
  6. 06_functional_workflow_basics.py — Write a workflow as a plain async function
  7. 07_first_graph_workflow.py — Build a workflow with executors and edges
  8. 08_host_your_agent.py — Host your agent via Azure Functions

Prerequisites

pip install agent-framework

Environment Variables

Samples call load_dotenv() to automatically load environment variables from a .env file in the python/ directory. This is a convenience for local development and testing.

For local development, set up your environment using any of these methods:

Option 1: Using a .env file (recommended for local development):

  1. Copy .env.example to .env in the python/ directory: 
    cp .env.example .env
  2. Edit .env and set your values (API keys, endpoints, etc.)

Option 2: Export environment variables directly:

export FOUNDRY_PROJECT_ENDPOINT="your-foundry-project-endpoint"export FOUNDRY_MODEL="gpt-4o"

Option 3: Using env_file_path parameter (for per-client configuration):

All client classes (e.g., OpenAIChatClient, OpenAIChatCompletionClient) support an env_file_path parameter to load environment variables from a specific file:

fromagent_framework.openaiimportOpenAIChatClient# Load from a custom .env fileclient=OpenAIChatClient(env_file_path="path/to/custom.env")

This allows different clients to use different configuration files if needed.

For the generic OpenAI clients (OpenAIChatClient and OpenAIChatCompletionClient), routing precedence is:

  1. Explicit Azure inputs such as credential, azure_endpoint, or api_version
  2. OPENAI_API_KEY / explicit OpenAI API-key parameters
  3. Azure environment fallback such as AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY

If you keep both OpenAI and Azure variables in your shell, the generic clients stay on OpenAI until you pass an explicit Azure input.

For the getting-started samples, you'll need at minimum:

FOUNDRY_PROJECT_ENDPOINT="your-foundry-project-endpoint"
FOUNDRY_MODEL="gpt-4o"

Consolidated sample env inventory

This is the single source of truth for package-level environment variables read by packages included by agent-framework-core[all]. It intentionally excludes variables that are only read by standalone samples, package sample folders, or tests. When package code adds, removes, or renames an environment variable, update this table in the same change.

Example values below are illustrative. For entries not backed by a single public class, the class column names the closest public surface, helper, or package-level initialization point that reads the variable.

packageclassenv varexample value
agent-framework-anthropicAnthropicClientANTHROPIC_API_KEYsk-ant-api03-...
agent-framework-anthropicAnthropicClientANTHROPIC_CHAT_MODELclaude-sonnet-4-5-20250929
agent-framework-foundryFoundryEmbeddingClientFOUNDRY_MODELS_ENDPOINThttps://my-endpoint.inference.ai.azure.com
agent-framework-foundryFoundryEmbeddingClientFOUNDRY_MODELS_API_KEYenv-key
agent-framework-foundryFoundryEmbeddingClientFOUNDRY_EMBEDDING_MODELtext-embedding-3-small
agent-framework-foundryFoundryEmbeddingClientFOUNDRY_IMAGE_EMBEDDING_MODELCohere-embed-v3-english
agent-framework-azure-ai-searchAzureAISearchContextProviderAZURE_SEARCH_ENDPOINThttps://my-search.search.windows.net
agent-framework-azure-ai-searchAzureAISearchContextProviderAZURE_SEARCH_API_KEYsearch-key
agent-framework-azure-ai-searchAzureAISearchContextProviderAZURE_SEARCH_INDEX_NAMEhotels-index
agent-framework-azure-ai-searchAzureAISearchContextProviderAZURE_SEARCH_KNOWLEDGE_BASE_NAMEhotels-kb
agent-framework-azure-cosmosCosmosHistoryProviderAZURE_COSMOS_ENDPOINThttps://my-cosmos.documents.azure.com:443/
agent-framework-azure-cosmosCosmosHistoryProviderAZURE_COSMOS_DATABASE_NAMEagent-history
agent-framework-azure-cosmosCosmosHistoryProviderAZURE_COSMOS_CONTAINER_NAMEmessages
agent-framework-azure-cosmosCosmosHistoryProviderAZURE_COSMOS_KEYC2F...==
agent-framework-bedrockBedrockChatClientBEDROCK_REGIONus-east-1
agent-framework-bedrockBedrockChatClientBEDROCK_CHAT_MODELanthropic.claude-3-5-sonnet-20241022-v2:0
agent-framework-bedrockBedrockEmbeddingClientBEDROCK_REGIONus-east-1
agent-framework-bedrockBedrockEmbeddingClientBEDROCK_EMBEDDING_MODELamazon.titan-embed-text-v2:0
agent-framework-bedrockBedrockChatClient / BedrockEmbeddingClientAWS_ACCESS_KEY_IDAKIAIOSFODNN7EXAMPLE
agent-framework-bedrockBedrockChatClient / BedrockEmbeddingClientAWS_SECRET_ACCESS_KEYwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
agent-framework-bedrockBedrockChatClient / BedrockEmbeddingClientAWS_SESSION_TOKENIQoJb3JpZ2luX2VjEO7//////////wEaCXVzLXdlc3QtMiJHMEUCIQD...
agent-framework-copilotstudioCopilotStudioAgentCOPILOTSTUDIOAGENT__ENVIRONMENTID00000000-0000-0000-0000-000000000000
agent-framework-copilotstudioCopilotStudioAgentCOPILOTSTUDIOAGENT__SCHEMANAMEcr123_agentname
agent-framework-copilotstudioCopilotStudioAgentCOPILOTSTUDIOAGENT__TENANTID11111111-1111-1111-1111-111111111111
agent-framework-copilotstudioCopilotStudioAgentCOPILOTSTUDIOAGENT__AGENTAPPID22222222-2222-2222-2222-222222222222
agent-framework-coreenable_instrumentation()ENABLE_INSTRUMENTATIONtrue
agent-framework-coreenable_instrumentation()ENABLE_SENSITIVE_DATAfalse
agent-framework-coreenable_instrumentation()ENABLE_CONSOLE_EXPORTERStrue
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_TRACES_ENDPOINThttp://localhost:4318/v1/traces
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_METRICS_ENDPOINThttp://localhost:4318/v1/metrics
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_LOGS_ENDPOINThttp://localhost:4318/v1/logs
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_PROTOCOLgrpc
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_HEADERSapi-key=demo
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_TRACES_HEADERSapi-key=trace-demo
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_METRICS_HEADERSapi-key=metric-demo
agent-framework-coreenable_instrumentation()OTEL_EXPORTER_OTLP_LOGS_HEADERSapi-key=log-demo
agent-framework-coreenable_instrumentation()OTEL_SERVICE_NAMEsample-agent
agent-framework-coreenable_instrumentation()OTEL_SERVICE_VERSION1.0.0
agent-framework-coreenable_instrumentation()OTEL_RESOURCE_ATTRIBUTESdeployment.environment=dev,service.namespace=agent-framework
agent-framework-devuiDevUI serverDEVUI_AUTH_TOKENmy-devui-token
agent-framework-foundryFoundryChatClientFOUNDRY_PROJECT_ENDPOINThttps://my-project.services.ai.azure.com/api/projects/my-project
agent-framework-foundryFoundryChatClientFOUNDRY_MODELgpt-4o
agent-framework-foundryFoundryAgentFOUNDRY_AGENT_NAMEtravel-planner
agent-framework-foundryFoundryAgentFOUNDRY_AGENT_VERSIONv1
agent-framework-github-copilotGitHubCopilotAgentGITHUB_COPILOT_CLI_PATHcopilot
agent-framework-github-copilotGitHubCopilotAgentGITHUB_COPILOT_MODELgpt-5
agent-framework-github-copilotGitHubCopilotAgentGITHUB_COPILOT_TIMEOUT60
agent-framework-github-copilotGitHubCopilotAgentGITHUB_COPILOT_LOG_LEVELinfo
agent-framework-mem0agent_framework_mem0 package importMEM0_TELEMETRYfalse
agent-framework-ollamaOllamaChatClientOLLAMA_HOSThttp://localhost:11434
agent-framework-ollamaOllamaChatClientOLLAMA_MODELllama3.1:8b
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientOPENAI_API_KEYsk-proj-...
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientOPENAI_MODELgpt-4o-mini
agent-framework-openaiOpenAIChatClientOPENAI_CHAT_MODELgpt-4.1-mini
agent-framework-openaiOpenAIChatCompletionClientOPENAI_CHAT_COMPLETION_MODELgpt-4o
agent-framework-openaiOpenAIEmbeddingClientOPENAI_EMBEDDING_MODELtext-embedding-3-small
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientOPENAI_BASE_URLhttps://api.openai.com/v1/
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientOPENAI_ORG_IDorg_123456789
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientAZURE_OPENAI_ENDPOINThttps://my-resource.openai.azure.com/
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientAZURE_OPENAI_API_KEYsk-azure-...
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientAZURE_OPENAI_API_VERSION2024-10-21
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientAZURE_OPENAI_BASE_URLhttps://my-resource.openai.azure.com/openai/v1/
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientAZURE_OPENAI_MODELgpt-4o
agent-framework-openaiOpenAIChatClientAZURE_OPENAI_CHAT_MODELgpt-4.1
agent-framework-openaiOpenAIChatCompletionClientAZURE_OPENAI_CHAT_COMPLETION_MODELgpt-4o-mini
agent-framework-openaiOpenAIEmbeddingClientAZURE_OPENAI_EMBEDDING_MODELtext-embedding-3-large
agent-framework-openaiOpenAIChatClient / OpenAIChatCompletionClient / OpenAIEmbeddingClientAZURE_OPENAI_RESOURCE_URLhttps://cognitiveservices.azure.com/

agent-framework-openai supports the Azure OpenAI client-specific deployment aliases listed above; keep packages/openai/README.md as the authoritative reference for the exact fallback order and package-specific behavior.

Note for production: In production environments, set environment variables through your deployment platform (e.g., Azure App Settings, Kubernetes ConfigMaps/Secrets) rather than using .env files. The load_dotenv() call in samples will have no effect when a .env file is not present, allowing environment variables to be loaded from the system.

For Azure authentication, run az login before running samples.

Note on XML tags

Some sample files include XML-style snippet tags (for example <snippet_name> and </snippet_name>). These are used by our documentation tooling and can be ignored or removed when you use the samples outside this repository.

Additional Resources