diff --git a/python/.env.example b/python/.env.example new file mode 100644 index 0000000000..e8de35394a --- /dev/null +++ b/python/.env.example @@ -0,0 +1,8 @@ +FOUNDRY_PROJECT_ENDPOINT="" +FOUNDRY_MODEL_DEPLOYMENT_NAME="" +OPENAI_API_KEY="" +OPENAI_CHAT_MODEL_ID="" +AZURE_OPENAI_ENDPOINT="" +AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="" +AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="" +OPENAI_RESPONSES_MODEL_ID="" diff --git a/python/samples/getting_started/agents/README.md b/python/samples/getting_started/agents/README.md new file mode 100644 index 0000000000..14233b7812 --- /dev/null +++ b/python/samples/getting_started/agents/README.md @@ -0,0 +1,27 @@ +# Agent Examples + +This folder contains examples demonstrating how to create and use agents with different chat clients from the Agent Framework. Each sub-folder focuses on a specific provider and client type, showing various capabilities like function tools, code interpreter, thread management, and more. + +## Examples by Provider + +### Azure AI Foundry Examples + +| Folder | Description | +|--------|-------------| +| **[`foundry/`](foundry/)** | Create agents using Azure AI Foundry | + +### Azure OpenAI Examples + +| Folder | Description | +|--------|-------------| +| **[`azure_assistants_client/`](azure_assistants_client/)** | Create agents using Azure OpenAI Assistants API | +| **[`azure_chat_client/`](azure_chat_client/)** | Create agents using Azure OpenAI Chat Completions API | +| **[`azure_responses_client/`](azure_responses_client/)** | Create agents using Azure OpenAI Responses API | + +### OpenAI Examples + +| Folder | Description | +|--------|-------------| +| **[`openai_assistants_client/`](openai_assistants_client/)** | Create agents using OpenAI Assistants API | +| **[`openai_chat_client/`](openai_chat_client/)** | Create agents using OpenAI Chat Completions API | +| **[`openai_responses_client/`](openai_responses_client/)** | Create agents using OpenAI Responses API | diff --git a/python/samples/getting_started/agents/azure_assistants_client/README.md b/python/samples/getting_started/agents/azure_assistants_client/README.md new file mode 100644 index 0000000000..baf825b5ba --- /dev/null +++ b/python/samples/getting_started/agents/azure_assistants_client/README.md @@ -0,0 +1,24 @@ +# Azure Assistants Agent Examples + +This folder contains examples demonstrating different ways to create and use agents with the Azure Assistants client from the `agent_framework.azure` package. + +## Examples + +| File | Description | +|------|-------------| +| [`azure_assistants_basic.py`](azure_assistants_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `AzureAssistantsClient`. Shows both streaming and non-streaming responses with automatic assistant creation and cleanup. | +| [`azure_assistants_with_existing_assistant.py`](azure_assistants_with_existing_assistant.py) | Shows how to work with a pre-existing assistant by providing the assistant ID to the Azure Assistants client. Demonstrates proper cleanup of manually created assistants. | +| [`azure_assistants_with_function_tools.py`](azure_assistants_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`azure_assistants_with_code_interpreter.py`](azure_assistants_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. | +| [`azure_assistants_with_thread.py`](azure_assistants_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | + +## Environment Variables + +Make sure to set the following environment variables before running the examples: + +- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint +- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI deployment + +## Authentication + +All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method. diff --git a/python/samples/getting_started/agents/azure_chat_client/README.md b/python/samples/getting_started/agents/azure_chat_client/README.md new file mode 100644 index 0000000000..da9b6e06dc --- /dev/null +++ b/python/samples/getting_started/agents/azure_chat_client/README.md @@ -0,0 +1,22 @@ +# Azure Chat Agent Examples + +This folder contains examples demonstrating different ways to create and use agents with the Azure Chat client from the `agent_framework.azure` package. + +## Examples + +| File | Description | +|------|-------------| +| [`azure_chat_client_basic.py`](azure_chat_client_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `AzureChatClient`. Shows both streaming and non-streaming responses for chat-based interactions with Azure OpenAI models. | +| [`azure_chat_client_with_function_tools.py`](azure_chat_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`azure_chat_client_with_thread.py`](azure_chat_client_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | + +## Environment Variables + +Make sure to set the following environment variables before running the examples: + +- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint +- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI deployment + +## Authentication + +All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method. diff --git a/python/samples/getting_started/agents/azure_responses_client/README.md b/python/samples/getting_started/agents/azure_responses_client/README.md new file mode 100644 index 0000000000..aed0b5573b --- /dev/null +++ b/python/samples/getting_started/agents/azure_responses_client/README.md @@ -0,0 +1,23 @@ +# Azure Responses Agent Examples + +This folder contains examples demonstrating different ways to create and use agents with the Azure Responses client from the `agent_framework.azure` package. + +## Examples + +| File | Description | +|------|-------------| +| [`azure_responses_client_basic.py`](azure_responses_client_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `AzureResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with Azure OpenAI models. | +| [`azure_responses_client_with_function_tools.py`](azure_responses_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`azure_responses_client_with_code_interpreter.py`](azure_responses_client_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. | +| [`azure_responses_client_with_thread.py`](azure_responses_client_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | + +## Environment Variables + +Make sure to set the following environment variables before running the examples: + +- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint +- `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME`: The name of your Azure OpenAI deployment + +## Authentication + +All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method. diff --git a/python/samples/getting_started/agents/foundry/README.md b/python/samples/getting_started/agents/foundry/README.md index d594db3266..0ad4575ef2 100644 --- a/python/samples/getting_started/agents/foundry/README.md +++ b/python/samples/getting_started/agents/foundry/README.md @@ -1,20 +1,17 @@ -# Foundry Chat Client Examples +# Foundry Agent Examples -This folder contains examples demonstrating different ways to use the `FoundryChatClient` from the `agent_framework.foundry` package. +This folder contains examples demonstrating different ways to create and use agents with the Foundry chat client from the `agent_framework.foundry` package. ## Examples -### 1. `foundry_basic.py` -The simplest way to use FoundryChatClient. It automatically handles all configuration using environment variables. - -### 2. `foundry_with_explicit_settings.py` -Shows how to explicitly configure the FoundryChatClient with custom settings, including project endpoint, model deployment, credentials, and agent name. - -### 3. `foundry_with_existing_client.py` -Demonstrates how to use an existing `AIProjectClient` instance with FoundryChatClient, giving you more control over the underlying Azure AI client. - -### 4. `foundry_with_existing_agent.py` -Shows how to work with a pre-existing agent by providing the agent ID to FoundryChatClient. This example also demonstrates proper cleanup of manually created agents. +| File | Description | +|------|-------------| +| [`foundry_basic.py`](foundry_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `FoundryChatClient`. It automatically handles all configuration using environment variables. | +| [`foundry_with_explicit_settings.py`](foundry_with_explicit_settings.py) | Shows how to create an agent with explicitly configured `FoundryChatClient` settings, including project endpoint, model deployment, credentials, and agent name. | +| [`foundry_with_existing_agent.py`](foundry_with_existing_agent.py) | Shows how to work with a pre-existing agent by providing the agent ID to the Foundry chat client. This example also demonstrates proper cleanup of manually created agents. | +| [`foundry_with_function_tools.py`](foundry_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`foundry_with_code_interpreter.py`](foundry_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Foundry agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. | +| [`foundry_with_thread.py`](foundry_with_thread.py) | Demonstrates thread management with Foundry agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | ## Environment Variables @@ -22,23 +19,3 @@ Make sure to set the following environment variables before running the examples - `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint - `FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment - -## Running the Examples - -Each example can be run independently: - -```bash -# Run the basic example -python samples/getting_started/agents/foundry/foundry_basic.py - -# Run the explicit settings example -python samples/getting_started/agents/foundry/foundry_with_explicit_settings.py - -# Run the existing client example -python samples/getting_started/agents/foundry/foundry_with_existing_client.py - -# Run the existing agent example -python samples/getting_started/agents/foundry/foundry_with_existing_agent.py -``` - -All examples use the same weather tool function that returns mock weather data. diff --git a/python/samples/getting_started/agents/openai_assistants_client/README.md b/python/samples/getting_started/agents/openai_assistants_client/README.md new file mode 100644 index 0000000000..e318fb15eb --- /dev/null +++ b/python/samples/getting_started/agents/openai_assistants_client/README.md @@ -0,0 +1,21 @@ +# OpenAI Assistants Agent Examples + +This folder contains examples demonstrating different ways to create and use agents with the OpenAI Assistants client from the `agent_framework.openai` package. + +## Examples + +| File | Description | +|------|-------------| +| [`openai_assistants_basic.py`](openai_assistants_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `OpenAIAssistantsClient`. Shows both streaming and non-streaming responses with automatic assistant creation and cleanup. | +| [`openai_assistants_with_existing_assistant.py`](openai_assistants_with_existing_assistant.py) | Shows how to work with a pre-existing assistant by providing the assistant ID to the OpenAI Assistants client. Demonstrates proper cleanup of manually created assistants. | +| [`openai_assistants_with_function_tools.py`](openai_assistants_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`openai_assistants_with_code_interpreter.py`](openai_assistants_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with OpenAI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. | +| [`openai_assistants_with_file_search.py`](openai_assistants_with_file_search.py) | Demonstrates how to use file search capabilities with OpenAI agents, allowing the agent to search through uploaded files to answer questions. | +| [`openai_assistants_with_thread.py`](openai_assistants_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | + +## Environment Variables + +Make sure to set the following environment variables before running the examples: + +- `OPENAI_API_KEY`: Your OpenAI API key +- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`) diff --git a/python/samples/getting_started/agents/openai_chat_client/README.md b/python/samples/getting_started/agents/openai_chat_client/README.md new file mode 100644 index 0000000000..37ae8c8660 --- /dev/null +++ b/python/samples/getting_started/agents/openai_chat_client/README.md @@ -0,0 +1,20 @@ +# OpenAI Chat Agent Examples + +This folder contains examples demonstrating different ways to create and use agents with the OpenAI Chat client from the `agent_framework.openai` package. + +## Examples + +| File | Description | +|------|-------------| +| [`openai_chat_client_basic.py`](openai_chat_client_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `OpenAIChatClient`. Shows both streaming and non-streaming responses for chat-based interactions with OpenAI models. | +| [`openai_chat_client_with_function_tools.py`](openai_chat_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`openai_chat_client_with_local_mcp.py`](openai_chat_client_with_local_mcp.py) | Shows how to integrate OpenAI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. | +| [`openai_chat_client_with_thread.py`](openai_chat_client_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | +| [`openai_chat_client_with_web_search.py`](openai_chat_client_with_web_search.py) | Shows how to use web search capabilities with OpenAI agents to retrieve and use information from the internet in responses. | + +## Environment Variables + +Make sure to set the following environment variables before running the examples: + +- `OPENAI_API_KEY`: Your OpenAI API key +- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`) diff --git a/python/samples/getting_started/agents/openai_responses_client/README.md b/python/samples/getting_started/agents/openai_responses_client/README.md new file mode 100644 index 0000000000..40dd994370 --- /dev/null +++ b/python/samples/getting_started/agents/openai_responses_client/README.md @@ -0,0 +1,23 @@ +# OpenAI Responses Agent Examples + +This folder contains examples demonstrating different ways to create and use agents with the OpenAI Responses client from the `agent_framework.openai` package. + +## Examples + +| File | Description | +|------|-------------| +| [`openai_responses_client_basic.py`](openai_responses_client_basic.py) | The simplest way to create an agent using `ChatClientAgent` with `OpenAIResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with OpenAI models. | +| [`openai_responses_client_reasoning.py`](openai_responses_client_reasoning.py) | Demonstrates how to use reasoning capabilities with OpenAI agents, showing how the agent can provide detailed reasoning for its responses. | +| [`openai_responses_client_with_function_tools.py`](openai_responses_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). | +| [`openai_responses_client_with_code_interpreter.py`](openai_responses_client_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with OpenAI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. | +| [`openai_responses_client_with_file_search.py`](openai_responses_client_with_file_search.py) | Demonstrates how to use file search capabilities with OpenAI agents, allowing the agent to search through uploaded files to answer questions. | +| [`openai_responses_client_with_local_mcp.py`](openai_responses_client_with_local_mcp.py) | Shows how to integrate OpenAI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. | +| [`openai_responses_client_with_thread.py`](openai_responses_client_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. | +| [`openai_responses_client_with_web_search.py`](openai_responses_client_with_web_search.py) | Shows how to use web search capabilities with OpenAI agents to retrieve and use information from the internet in responses. | + +## Environment Variables + +Make sure to set the following environment variables before running the examples: + +- `OPENAI_API_KEY`: Your OpenAI API key +- `OPENAI_RESPONSES_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`) diff --git a/python/samples/getting_started/chat_client/README.md b/python/samples/getting_started/chat_client/README.md new file mode 100644 index 0000000000..48d96fa0de --- /dev/null +++ b/python/samples/getting_started/chat_client/README.md @@ -0,0 +1,34 @@ +# Chat Client Examples + +This folder contains simple examples demonstrating direct usage of various chat clients. + +## Examples + +| File | Description | +|------|-------------| +| [`azure_assistants_client.py`](azure_assistants_client.py) | Direct usage of Azure Assistants Client for basic chat interactions with Azure OpenAI assistants. | +| [`azure_chat_client.py`](azure_chat_client.py) | Direct usage of Azure Chat Client for chat interactions with Azure OpenAI models. | +| [`azure_responses_client.py`](azure_responses_client.py) | Direct usage of Azure Responses Client for structured response generation with Azure OpenAI models. | +| [`chat_response_cancellation.py`](chat_response_cancellation.py) | Demonstrates how to cancel chat responses during streaming, showing proper cancellation handling and cleanup. | +| [`foundry_chat_client.py`](foundry_chat_client.py) | Direct usage of Foundry Chat Client for chat interactions with Azure AI Foundry models. | +| [`openai_assistants_client.py`](openai_assistants_client.py) | Direct usage of OpenAI Assistants Client for basic chat interactions with OpenAI assistants. | +| [`openai_chat_client.py`](openai_chat_client.py) | Direct usage of OpenAI Chat Client for chat interactions with OpenAI models. | +| [`openai_responses_client.py`](openai_responses_client.py) | Direct usage of OpenAI Responses Client for structured response generation with OpenAI models. | + +## Environment Variables + +Depending on which client you're using, set the appropriate environment variables: + +**For Azure clients:** +- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint +- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI chat deployment +- `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME`: The name of your Azure OpenAI responses deployment + +**For Foundry client:** +- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint +- `FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment + +**For OpenAI clients:** +- `OPENAI_API_KEY`: Your OpenAI API key +- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use for chat clients (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`) +- `OPENAI_RESPONSES_MODEL_ID`: The OpenAI model to use for responses clients (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`) diff --git a/python/samples/getting_started/threads/README.md b/python/samples/getting_started/threads/README.md new file mode 100644 index 0000000000..04d8afc8b3 --- /dev/null +++ b/python/samples/getting_started/threads/README.md @@ -0,0 +1,10 @@ +# Thread Management Examples + +This folder contains examples demonstrating different ways to manage conversation threads and chat message stores with the Agent Framework. + +## Examples + +| File | Description | +|------|-------------| +| [`custom_chat_message_store_thread.py`](custom_chat_message_store_thread.py) | Demonstrates how to implement a custom `ChatMessageStore` for persisting conversation history. Shows how to create a custom store with serialization/deserialization capabilities and integrate it with agents for thread management across multiple sessions. | +| [`suspend_resume_thread.py`](suspend_resume_thread.py) | Shows how to suspend and resume conversation threads, allowing you to save the state of a conversation and continue it later. This is useful for long-running conversations or when you need to persist conversation state across application restarts. | diff --git a/user-documentation-python/getting-started/README.md b/user-documentation-python/getting-started/README.md index 0fbc789918..69442d9370 100644 --- a/user-documentation-python/getting-started/README.md +++ b/user-documentation-python/getting-started/README.md @@ -1,7 +1,48 @@ # Microsoft Agent Framework Getting Started -This guide will help you get up and running quickly with a basic agent using the Agent Framework and Azure OpenAI. +This guide will help you get up and running quickly with a basic agent using the Agent Framework and Azure AI Foundry. -## Coming Soon +## Prerequisites +Before you begin, ensure you have the following: +- [Python 3.9 or later](https://www.python.org/downloads/) +- An [Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/) project with a deployed model (e.g., `gpt-4o-mini`) +- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed and authenticated (`az login`) + +**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure AI Foundry project. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively). + +## Running a Basic Agent Sample + +This sample demonstrates how to create and use a simple AI agent with Azure AI Foundry as the backend. It will create a basic agent using `ChatClientAgent` with `FoundryChatClient` and custom instructions. + +Make sure to set the following environment variables: +- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint +- `FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment + +### Sample Code + +```python +import asyncio +from agent_framework import ChatClientAgent +from agent_framework.foundry import FoundryChatClient +from azure.identity.aio import AzureCliCredential + +async def main(): + async with ( + AzureCliCredential() as credential, + ChatClientAgent( + chat_client=FoundryChatClient(async_credential=credential), + instructions="You are good at telling jokes." + ) as agent, + ): + result = await agent.run("Tell me a joke about a pirate.") + print(result.text) + +if __name__ == "__main__": + asyncio.run(main()) +``` + +## More Examples + +For more detailed examples and advanced scenarios, see the [Foundry Agent Examples](../../python/samples/getting_started/agents/foundry/README.md).