Skip to content

Commit 6a00c9d

Browse files
dmytrostrukdmytrostruk
authored
Python: Documentation updates (microsoft#538)
* Added README for each sample sub-folder * More documentation updates
1 parent ea7cff1 commit 6a00c9d

12 files changed

Lines changed: 265 additions & 35 deletions

File tree

‎python/.env.example‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
FOUNDRY_PROJECT_ENDPOINT=""
2+
FOUNDRY_MODEL_DEPLOYMENT_NAME=""
3+
OPENAI_API_KEY=""
4+
OPENAI_CHAT_MODEL_ID=""
5+
AZURE_OPENAI_ENDPOINT=""
6+
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=""
7+
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=""
8+
OPENAI_RESPONSES_MODEL_ID=""

‎python/samples/getting_started/agents/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Agent Examples
2+
3+
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.
4+
5+
## Examples by Provider
6+
7+
### Azure AI Foundry Examples
8+
9+
| Folder | Description |
10+
|--------|-------------|
11+
| **[`foundry/`](foundry/)** | Create agents using Azure AI Foundry |
12+
13+
### Azure OpenAI Examples
14+
15+
| Folder | Description |
16+
|--------|-------------|
17+
| **[`azure_assistants_client/`](azure_assistants_client/)** | Create agents using Azure OpenAI Assistants API |
18+
| **[`azure_chat_client/`](azure_chat_client/)** | Create agents using Azure OpenAI Chat Completions API |
19+
| **[`azure_responses_client/`](azure_responses_client/)** | Create agents using Azure OpenAI Responses API |
20+
21+
### OpenAI Examples
22+
23+
| Folder | Description |
24+
|--------|-------------|
25+
| **[`openai_assistants_client/`](openai_assistants_client/)** | Create agents using OpenAI Assistants API |
26+
| **[`openai_chat_client/`](openai_chat_client/)** | Create agents using OpenAI Chat Completions API |
27+
| **[`openai_responses_client/`](openai_responses_client/)** | Create agents using OpenAI Responses API |

‎python/samples/getting_started/agents/azure_assistants_client/README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Azure Assistants Agent Examples
2+
3+
This folder contains examples demonstrating different ways to create and use agents with the Azure Assistants client from the `agent_framework.azure` package.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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. |
11+
| [`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). |
12+
| [`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. |
13+
| [`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. |
14+
15+
## Environment Variables
16+
17+
Make sure to set the following environment variables before running the examples:
18+
19+
- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint
20+
- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI deployment
21+
22+
## Authentication
23+
24+
All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method.

‎python/samples/getting_started/agents/azure_chat_client/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Azure Chat Agent Examples
2+
3+
This folder contains examples demonstrating different ways to create and use agents with the Azure Chat client from the `agent_framework.azure` package.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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). |
11+
| [`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. |
12+
13+
## Environment Variables
14+
15+
Make sure to set the following environment variables before running the examples:
16+
17+
- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint
18+
- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI deployment
19+
20+
## Authentication
21+
22+
All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method.

‎python/samples/getting_started/agents/azure_responses_client/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Azure Responses Agent Examples
2+
3+
This folder contains examples demonstrating different ways to create and use agents with the Azure Responses client from the `agent_framework.azure` package.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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). |
11+
| [`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. |
12+
| [`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. |
13+
14+
## Environment Variables
15+
16+
Make sure to set the following environment variables before running the examples:
17+
18+
- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint
19+
- `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME`: The name of your Azure OpenAI deployment
20+
21+
## Authentication
22+
23+
All examples use `AzureCliCredential` for authentication. Run `az login` in your terminal before running the examples, or replace `AzureCliCredential` with your preferred authentication method.

‎python/samples/getting_started/agents/foundry/README.md‎

Lines changed: 10 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,21 @@
1-
# Foundry Chat Client Examples
1+
# Foundry Agent Examples
22

3-
This folder contains examples demonstrating different ways to use the `FoundryChatClient` from the `agent_framework.foundry` package.
3+
This folder contains examples demonstrating different ways to create and use agents with the Foundry chat client from the `agent_framework.foundry` package.
44

55
## Examples
66

7-
### 1. `foundry_basic.py`
8-
The simplest way to use FoundryChatClient. It automatically handles all configuration using environment variables.
9-
10-
### 2. `foundry_with_explicit_settings.py`
11-
Shows how to explicitly configure the FoundryChatClient with custom settings, including project endpoint, model deployment, credentials, and agent name.
12-
13-
### 3. `foundry_with_existing_client.py`
14-
Demonstrates how to use an existing `AIProjectClient` instance with FoundryChatClient, giving you more control over the underlying Azure AI client.
15-
16-
### 4. `foundry_with_existing_agent.py`
17-
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.
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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. |
11+
| [`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. |
12+
| [`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). |
13+
| [`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. |
14+
| [`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. |
1815

1916
## Environment Variables
2017

2118
Make sure to set the following environment variables before running the examples:
2219

2320
- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
2421
- `FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment
25-
26-
## Running the Examples
27-
28-
Each example can be run independently:
29-
30-
```bash
31-
# Run the basic example
32-
python samples/getting_started/agents/foundry/foundry_basic.py
33-
34-
# Run the explicit settings example
35-
python samples/getting_started/agents/foundry/foundry_with_explicit_settings.py
36-
37-
# Run the existing client example
38-
python samples/getting_started/agents/foundry/foundry_with_existing_client.py
39-
40-
# Run the existing agent example
41-
python samples/getting_started/agents/foundry/foundry_with_existing_agent.py
42-
```
43-
44-
All examples use the same weather tool function that returns mock weather data.

‎python/samples/getting_started/agents/openai_assistants_client/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# OpenAI Assistants Agent Examples
2+
3+
This folder contains examples demonstrating different ways to create and use agents with the OpenAI Assistants client from the `agent_framework.openai` package.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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. |
11+
| [`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). |
12+
| [`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. |
13+
| [`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. |
14+
| [`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. |
15+
16+
## Environment Variables
17+
18+
Make sure to set the following environment variables before running the examples:
19+
20+
- `OPENAI_API_KEY`: Your OpenAI API key
21+
- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`)

‎python/samples/getting_started/agents/openai_chat_client/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# OpenAI Chat Agent Examples
2+
3+
This folder contains examples demonstrating different ways to create and use agents with the OpenAI Chat client from the `agent_framework.openai` package.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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). |
11+
| [`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. |
12+
| [`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. |
13+
| [`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. |
14+
15+
## Environment Variables
16+
17+
Make sure to set the following environment variables before running the examples:
18+
19+
- `OPENAI_API_KEY`: Your OpenAI API key
20+
- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`)

‎python/samples/getting_started/agents/openai_responses_client/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# OpenAI Responses Agent Examples
2+
3+
This folder contains examples demonstrating different ways to create and use agents with the OpenAI Responses client from the `agent_framework.openai` package.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`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. |
10+
| [`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. |
11+
| [`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). |
12+
| [`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. |
13+
| [`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. |
14+
| [`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. |
15+
| [`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. |
16+
| [`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. |
17+
18+
## Environment Variables
19+
20+
Make sure to set the following environment variables before running the examples:
21+
22+
- `OPENAI_API_KEY`: Your OpenAI API key
23+
- `OPENAI_RESPONSES_MODEL_ID`: The OpenAI model to use (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`)

‎python/samples/getting_started/chat_client/README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Chat Client Examples
2+
3+
This folder contains simple examples demonstrating direct usage of various chat clients.
4+
5+
## Examples
6+
7+
| File | Description |
8+
|------|-------------|
9+
| [`azure_assistants_client.py`](azure_assistants_client.py) | Direct usage of Azure Assistants Client for basic chat interactions with Azure OpenAI assistants. |
10+
| [`azure_chat_client.py`](azure_chat_client.py) | Direct usage of Azure Chat Client for chat interactions with Azure OpenAI models. |
11+
| [`azure_responses_client.py`](azure_responses_client.py) | Direct usage of Azure Responses Client for structured response generation with Azure OpenAI models. |
12+
| [`chat_response_cancellation.py`](chat_response_cancellation.py) | Demonstrates how to cancel chat responses during streaming, showing proper cancellation handling and cleanup. |
13+
| [`foundry_chat_client.py`](foundry_chat_client.py) | Direct usage of Foundry Chat Client for chat interactions with Azure AI Foundry models. |
14+
| [`openai_assistants_client.py`](openai_assistants_client.py) | Direct usage of OpenAI Assistants Client for basic chat interactions with OpenAI assistants. |
15+
| [`openai_chat_client.py`](openai_chat_client.py) | Direct usage of OpenAI Chat Client for chat interactions with OpenAI models. |
16+
| [`openai_responses_client.py`](openai_responses_client.py) | Direct usage of OpenAI Responses Client for structured response generation with OpenAI models. |
17+
18+
## Environment Variables
19+
20+
Depending on which client you're using, set the appropriate environment variables:
21+
22+
**For Azure clients:**
23+
- `AZURE_OPENAI_ENDPOINT`: Your Azure OpenAI endpoint
24+
- `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`: The name of your Azure OpenAI chat deployment
25+
- `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME`: The name of your Azure OpenAI responses deployment
26+
27+
**For Foundry client:**
28+
- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
29+
- `FOUNDRY_MODEL_DEPLOYMENT_NAME`: The name of your model deployment
30+
31+
**For OpenAI clients:**
32+
- `OPENAI_API_KEY`: Your OpenAI API key
33+
- `OPENAI_CHAT_MODEL_ID`: The OpenAI model to use for chat clients (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`)
34+
- `OPENAI_RESPONSES_MODEL_ID`: The OpenAI model to use for responses clients (e.g., `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`)

0 commit comments

Comments
 (0)