.NET: Python: Add AGENTS.md files and update coding standards (#3644)

* Add AGENTS.md files and update coding standards for Python - Add root python/AGENTS.md with project structure and package links - Add AGENTS.md for each package describing purpose and main classes - Update .github/copilot-instructions.md with improved structure - Update python/CODING_STANDARD.md with API review guidance: - Future annotations convention (#3578) - TypeVar naming convention (#3594) - Mapping vs MutableMapping (#3577) - Avoid shadowing built-ins (#3583) - Explicit exports (#3605) - Exception documentation guidelines (#3410) - Simplify python/.github/instructions/python.instructions.md to reference AGENTS.md - Remove AGENTS.md from .gitignore * Fix purview import path in AGENTS.md * Address PR review comments and restructure instructions - Slim down .github/copilot-instructions.md to reference language-specific docs - Add ADR section explaining templates and purpose - Create dotnet/AGENTS.md with .NET-specific build commands, conventions, and sample guidance - Update Python build/test instructions for core vs isolated changes - Fix Microsoft.Extensions.AI package references - Update kwargs guidance per issue #3642 - Fix Python sample helper placement (top, not bottom) - Document new 'typing' poe task in DEV_SETUP.md * Add 'typing' poe task to run both pyright and mypy * Add kwargs guidelines from issue #3642 to CODING_STANDARD.md * Clarify that connector packages pull in core as dependency
2026-06-16 21:04:09 +08:00 · 2026-02-05 11:27:46 +01:00
parent de80543302
commit eaad042241
30 changed files with 1026 additions and 201 deletions
@@ -0,0 +1,23 @@
+# A2A Package (agent-framework-a2a)
+
+Agent-to-Agent (A2A) protocol support for inter-agent communication.
+
+## Main Classes
+
+- **`A2AAgent`** - Agent wrapper that exposes an agent via the A2A protocol
+
+## Usage
+
+```python
+from agent_framework.a2a import A2AAgent
+
+a2a_agent = A2AAgent(agent=my_agent)
+```
+
+## Import Path
+
+```python
+from agent_framework.a2a import A2AAgent
+# or directly:
+from agent_framework_a2a import A2AAgent
+```
@@ -0,0 +1,35 @@
+# AG-UI Package (agent-framework-ag-ui)
+
+AG-UI protocol integration for building agent UIs with the AG-UI standard.
+
+## Main Classes
+
+- **`AgentFrameworkAgent`** - Wraps agents for AG-UI compatibility
+- **`AGUIChatClient`** - Chat client that speaks AG-UI protocol
+- **`AGUIHttpService`** - HTTP service for AG-UI endpoints
+- **`AGUIEventConverter`** - Converts between Agent Framework and AG-UI events
+- **`add_agent_framework_fastapi_endpoint()`** - Add AG-UI endpoint to FastAPI app
+
+## Types
+
+- **`AGUIRequest`** / **`AGUIChatOptions`** - Request types
+- **`AgentState`** / **`RunMetadata`** - State management types
+- **`PredictStateConfig`** - Configuration for state prediction
+
+## Usage
+
+```python
+from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
+from fastapi import FastAPI
+
+app = FastAPI()
+add_agent_framework_fastapi_endpoint(app, agent)
+```
+
+## Import Path
+
+```python
+from agent_framework.ag_ui import AGUIChatClient, add_agent_framework_fastapi_endpoint
+# or directly:
+from agent_framework_ag_ui import AGUIChatClient
+```
@@ -0,0 +1,25 @@
+# Anthropic Package (agent-framework-anthropic)
+
+Integration with Anthropic's Claude API.
+
+## Main Classes
+
+- **`AnthropicClient`** - Chat client for Anthropic Claude models
+- **`AnthropicChatOptions`** - Options TypedDict for Anthropic-specific parameters
+
+## Usage
+
+```python
+from agent_framework.anthropic import AnthropicClient
+
+client = AnthropicClient(model_id="claude-sonnet-4-20250514")
+response = await client.get_response("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework.anthropic import AnthropicClient
+# or directly:
+from agent_framework_anthropic import AnthropicClient
+```
@@ -0,0 +1,28 @@
+# Azure AI Search Package (agent-framework-azure-ai-search)
+
+Integration with Azure AI Search for RAG (Retrieval-Augmented Generation).
+
+## Main Classes
+
+- **`AzureAISearchContextProvider`** - Context provider that retrieves relevant documents from Azure AI Search
+- **`AzureAISearchSettings`** - Pydantic settings for Azure AI Search configuration
+
+## Usage
+
+```python
+from agent_framework.azure import AzureAISearchContextProvider
+
+provider = AzureAISearchContextProvider(
+    endpoint="https://your-search.search.windows.net",
+    index_name="your-index",
+)
+agent = ChatAgent(..., context_provider=provider)
+```
+
+## Import Path
+
+```python
+from agent_framework.azure import AzureAISearchContextProvider
+# or directly:
+from agent_framework_azure_ai_search import AzureAISearchContextProvider
+```
@@ -0,0 +1,32 @@
+# Azure AI Package (agent-framework-azure-ai)
+
+Integration with Azure AI Foundry for persistent agents and project-based agent management.
+
+## Main Classes
+
+- **`AzureAIAgentClient`** - Chat client for Azure AI Agents (persistent agents with threads)
+- **`AzureAIClient`** - Client for Azure AI Foundry project-based agents
+- **`AzureAIAgentsProvider`** - Provider for listing/managing Azure AI agents
+- **`AzureAIProjectAgentProvider`** - Provider for project-scoped agent management
+- **`AzureAISettings`** - Pydantic settings for Azure AI configuration
+- **`AzureAIAgentOptions`** / **`AzureAIProjectAgentOptions`** - Options TypedDicts
+
+## Usage
+
+```python
+from agent_framework.azure import AzureAIAgentClient
+
+client = AzureAIAgentClient(
+    endpoint="https://your-project.services.ai.azure.com",
+    agent_id="your-agent-id",
+)
+response = await client.get_response("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework.azure import AzureAIAgentClient, AzureAIClient
+# or directly:
+from agent_framework_azure_ai import AzureAIAgentClient
+```
@@ -0,0 +1,23 @@
+# Azure Functions Package (agent-framework-azurefunctions)
+
+Hosting agents as Azure Functions.
+
+## Main Classes
+
+- **`AgentFunctionApp`** - Azure Functions app wrapper for agents
+
+## Usage
+
+```python
+from agent_framework.azure import AgentFunctionApp
+
+app = AgentFunctionApp(agent=my_agent)
+```
+
+## Import Path
+
+```python
+from agent_framework.azure import AgentFunctionApp
+# or directly:
+from agent_framework_azurefunctions import AgentFunctionApp
+```
@@ -0,0 +1,25 @@
+# Bedrock Package (agent-framework-bedrock)
+
+Integration with AWS Bedrock for LLM inference.
+
+## Main Classes
+
+- **`BedrockChatClient`** - Chat client for AWS Bedrock models
+- **`BedrockChatOptions`** - Options TypedDict for Bedrock-specific parameters
+- **`BedrockGuardrailConfig`** - Configuration for Bedrock guardrails
+- **`BedrockSettings`** - Pydantic settings for Bedrock configuration
+
+## Usage
+
+```python
+from agent_framework_bedrock import BedrockChatClient
+
+client = BedrockChatClient(model_id="anthropic.claude-3-sonnet-20240229-v1:0")
+response = await client.get_response("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework_bedrock import BedrockChatClient
+```
@@ -0,0 +1,27 @@
+# ChatKit Package (agent-framework-chatkit)
+
+Integration with OpenAI ChatKit (Python) for building chat UIs.
+
+## Main Classes
+
+- **`ThreadItemConverter`** - Converts between Agent Framework and ChatKit types
+- **`stream_agent_response()`** - Stream agent responses to ChatKit
+- **`simple_to_agent_input()`** - Convert simple input to agent input format
+
+## Usage
+
+```python
+from agent_framework.chatkit import stream_agent_response, ThreadItemConverter
+
+async for event in stream_agent_response(agent, messages):
+    # Handle ChatKit events
+    pass
+```
+
+## Import Path
+
+```python
+from agent_framework.chatkit import stream_agent_response
+# or directly:
+from agent_framework_chatkit import stream_agent_response
+```
@@ -0,0 +1,28 @@
+# Claude Package (agent-framework-claude)
+
+Integration with Anthropic Claude as a managed agent (Claude Agent SDK).
+
+## Main Classes
+
+- **`ClaudeAgent`** - Agent using Claude's native agent capabilities
+- **`ClaudeAgentOptions`** - Options for Claude agent configuration
+- **`ClaudeAgentSettings`** - Pydantic settings for configuration
+
+## Usage
+
+```python
+from agent_framework_claude import ClaudeAgent
+
+agent = ClaudeAgent(...)
+response = await agent.run("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework_claude import ClaudeAgent
+```
+
+## Note
+
+This package is for Claude's managed agent functionality. For basic Claude chat, use `agent-framework-anthropic` instead.
@@ -0,0 +1,28 @@
+# Copilot Studio Package (agent-framework-copilotstudio)
+
+Integration with Microsoft Copilot Studio agents.
+
+## Main Classes
+
+- **`CopilotStudioAgent`** - Agent that connects to a Copilot Studio bot
+- **`acquire_token`** - Helper function for authentication
+
+## Usage
+
+```python
+from agent_framework.microsoft import CopilotStudioAgent
+
+agent = CopilotStudioAgent(
+    bot_identifier="your-bot-id",
+    environment_id="your-env-id",
+)
+response = await agent.run("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework.microsoft import CopilotStudioAgent
+# or directly:
+from agent_framework_copilotstudio import CopilotStudioAgent
+```
@@ -0,0 +1,141 @@
+# Core Package (agent-framework-core)
+
+The foundation package containing all core abstractions, types, and built-in OpenAI/Azure OpenAI support.
+
+## Module Structure
+
+```
+agent_framework/
+├── __init__.py          # Public API exports
+├── _agents.py           # Agent implementations
+├── _clients.py          # Chat client base classes and protocols
+├── _types.py            # Core types (ChatMessage, ChatResponse, Content, etc.)
+├── _tools.py            # Tool definitions and function invocation
+├── _middleware.py       # Middleware system for request/response interception
+├── _threads.py          # AgentThread and message store abstractions
+├── _memory.py           # Context providers for memory/RAG
+├── _mcp.py              # Model Context Protocol support
+├── _workflows/          # Workflow orchestration (sequential, concurrent, handoff, etc.)
+├── openai/              # Built-in OpenAI client
+├── azure/               # Lazy-loading entry point for Azure integrations
+└── <provider>/          # Other lazy-loading provider folders
+```
+
+## Core Classes
+
+### Agents (`_agents.py`)
+
+- **`AgentProtocol`** - Protocol defining the agent interface
+- **`BaseAgent`** - Abstract base class for agents
+- **`ChatAgent`** - Main agent class wrapping a chat client with tools, instructions, and middleware
+
+### Chat Clients (`_clients.py`)
+
+- **`ChatClientProtocol`** - Protocol for chat client implementations
+- **`BaseChatClient`** - Abstract base class with middleware support; subclasses implement `_inner_get_response()` and `_inner_get_streaming_response()`
+
+### Types (`_types.py`)
+
+- **`ChatMessage`** - Represents a chat message with role, content, and metadata
+- **`ChatResponse`** - Response from a chat client containing messages and usage
+- **`ChatResponseUpdate`** - Streaming response update
+- **`AgentResponse`** / **`AgentResponseUpdate`** - Agent-level response wrappers
+- **`Content`** - Base class for message content (text, function calls, images, etc.)
+- **`ChatOptions`** - TypedDict for chat request options
+
+### Tools (`_tools.py`)
+
+- **`ToolProtocol`** - Protocol for tool definitions
+- **`FunctionTool`** - Wraps Python functions as tools with JSON schema generation
+- **`@tool`** decorator - Converts functions to tools
+- **`use_function_invocation()`** - Decorator to add automatic function calling to chat clients
+
+### Middleware (`_middleware.py`)
+
+- **`AgentMiddleware`** - Intercepts agent `run()` calls
+- **`ChatMiddleware`** - Intercepts chat client `get_response()` calls
+- **`FunctionMiddleware`** - Intercepts function/tool invocations
+- **`AgentRunContext`** / **`ChatContext`** / **`FunctionInvocationContext`** - Context objects passed through middleware
+
+### Threads (`_threads.py`)
+
+- **`AgentThread`** - Manages conversation history for an agent
+- **`ChatMessageStoreProtocol`** - Protocol for persistent message storage
+- **`ChatMessageStore`** - Default in-memory implementation
+
+### Memory (`_memory.py`)
+
+- **`ContextProvider`** - Protocol for providing additional context to agents (RAG, memory systems)
+- **`Context`** - Container for context data
+
+### Workflows (`_workflows/`)
+
+- **`Workflow`** - Graph-based workflow definition
+- **`WorkflowBuilder`** - Fluent API for building workflows
+- **Orchestrators**: `SequentialOrchestrator`, `ConcurrentOrchestrator`, `GroupChatOrchestrator`, `MagenticOrchestrator`, `HandoffOrchestrator`
+
+## Built-in Providers
+
+### OpenAI (`openai/`)
+
+- **`OpenAIChatClient`** - Chat client for OpenAI API
+- **`OpenAIResponsesClient`** - Client for OpenAI Responses API
+
+### Azure OpenAI (`azure/`)
+
+- **`AzureOpenAIChatClient`** - Chat client for Azure OpenAI
+- **`AzureOpenAIResponsesClient`** - Client for Azure OpenAI Responses API
+
+## Key Patterns
+
+### Creating an Agent
+
+```python
+from agent_framework import ChatAgent
+from agent_framework.openai import OpenAIChatClient
+
+agent = ChatAgent(
+    chat_client=OpenAIChatClient(),
+    instructions="You are helpful.",
+    tools=[my_function],
+)
+response = await agent.run("Hello")
+```
+
+### Using `as_agent()` Shorthand
+
+```python
+agent = OpenAIChatClient().as_agent(
+    name="Assistant",
+    instructions="You are helpful.",
+)
+```
+
+### Middleware Pipeline
+
+```python
+from agent_framework import ChatAgent, AgentMiddleware, AgentRunContext
+
+class LoggingMiddleware(AgentMiddleware):
+    async def invoke(self, context: AgentRunContext, next) -> AgentResponse:
+        print(f"Input: {context.messages}")
+        response = await next(context)
+        print(f"Output: {response}")
+        return response
+
+agent = ChatAgent(..., middleware=[LoggingMiddleware()])
+```
+
+### Custom Chat Client
+
+```python
+from agent_framework import BaseChatClient, ChatResponse, ChatMessage
+
+class MyClient(BaseChatClient):
+    async def _inner_get_response(self, *, messages, options, **kwargs) -> ChatResponse:
+        # Call your LLM here
+        return ChatResponse(messages=[ChatMessage(role="assistant", text="Hi!")])
+
+    async def _inner_get_streaming_response(self, *, messages, options, **kwargs):
+        yield ChatResponseUpdate(...)
+```
@@ -0,0 +1,33 @@
+# Declarative Package (agent-framework-declarative)
+
+YAML/JSON-based declarative agent and workflow definitions.
+
+## Main Classes
+
+- **`AgentFactory`** - Creates agents from declarative definitions
+- **`WorkflowFactory`** - Creates workflows from declarative definitions
+- **`WorkflowState`** - State management for declarative workflows
+- **`ProviderTypeMapping`** - Maps provider types to implementations
+- **`DeclarativeLoaderError`** / **`ProviderLookupError`** - Error types
+
+## External Input Handling
+
+- **`ExternalInputRequest`** / **`ExternalInputResponse`** - Human-in-the-loop support
+- **`AgentExternalInputRequest`** / **`AgentExternalInputResponse`** - Agent-level input requests
+
+## Usage
+
+```python
+from agent_framework.declarative import AgentFactory, WorkflowFactory
+
+agent = AgentFactory.create_from_file("agent.yaml")
+workflow = WorkflowFactory.create_from_file("workflow.yaml")
+```
+
+## Import Path
+
+```python
+from agent_framework.declarative import AgentFactory, WorkflowFactory
+# or directly:
+from agent_framework_declarative import AgentFactory
+```
@@ -0,0 +1,43 @@
+# DevUI Package (agent-framework-devui)
+
+Interactive developer UI for testing and debugging agents and workflows.
+
+## Main Classes
+
+- **`serve()`** - Launch the DevUI server
+- **`DevServer`** - The FastAPI-based development server
+- **`register_cleanup()`** - Register cleanup hooks for entities
+- **`CheckpointConversationManager`** - Manages conversation checkpoints
+
+## Models
+
+- **`AgentFrameworkRequest`** - Request model for agent invocations
+- **`OpenAIResponse`** / **`OpenAIError`** - OpenAI-compatible response models
+- **`DiscoveryResponse`** / **`EntityInfo`** - Entity discovery models
+
+## Usage
+
+```python
+from agent_framework.devui import serve
+
+agent = ChatAgent(...)
+serve(entities=[agent], port=8080, auto_open=True)
+```
+
+## CLI
+
+```bash
+# Run with auto-discovery
+devui ./agents
+
+# Run with specific entities
+devui --entities my_agent.py
+```
+
+## Import Path
+
+```python
+from agent_framework.devui import serve, register_cleanup
+# or directly:
+from agent_framework_devui import serve
+```
@@ -0,0 +1,46 @@
+# Durable Task Package (agent-framework-durabletask)
+
+Durable execution support for long-running agent workflows using Azure Durable Functions.
+
+## Main Classes
+
+### Client Side
+
+- **`DurableAIAgentClient`** - Client for invoking durable agents
+- **`DurableAIAgent`** - Shim for creating durable agents
+
+### Worker Side
+
+- **`DurableAIAgentWorker`** - Worker that executes durable agent tasks
+- **`DurableAgentExecutor`** - Executes agent logic within durable context
+- **`AgentEntity`** - Durable entity for agent state management
+
+### State Management
+
+- **`DurableAgentState`** - State container for durable agents
+- **`DurableAgentThread`** - Thread management for durable agents
+- **`DurableAIAgentOrchestrationContext`** - Orchestration context
+
+### Callbacks
+
+- **`AgentCallbackContext`** - Context for agent callbacks
+- **`AgentResponseCallbackProtocol`** - Protocol for response callbacks
+
+## Usage
+
+```python
+from agent_framework_durabletask import DurableAIAgentClient, DurableAIAgentWorker
+
+# Client side
+client = DurableAIAgentClient(endpoint="https://your-functions.azurewebsites.net")
+response = await client.run("Hello")
+
+# Worker side
+worker = DurableAIAgentWorker(agent=my_agent)
+```
+
+## Import Path
+
+```python
+from agent_framework_durabletask import DurableAIAgentClient, DurableAIAgentWorker
+```
@@ -0,0 +1,24 @@
+# Foundry Local Package (agent-framework-foundry-local)
+
+Integration with Azure AI Foundry Local for local model inference.
+
+## Main Classes
+
+- **`FoundryLocalClient`** - Chat client for Foundry Local models
+- **`FoundryLocalChatOptions`** - Options TypedDict for Foundry Local parameters
+- **`FoundryLocalSettings`** - Pydantic settings for configuration
+
+## Usage
+
+```python
+from agent_framework_foundry_local import FoundryLocalClient
+
+client = FoundryLocalClient(model_id="your-local-model")
+response = await client.get_response("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework_foundry_local import FoundryLocalClient
+```
@@ -0,0 +1,26 @@
+# GitHub Copilot Package (agent-framework-github-copilot)
+
+Integration with GitHub Copilot extensions.
+
+## Main Classes
+
+- **`GitHubCopilotAgent`** - Agent for GitHub Copilot extensions
+- **`GitHubCopilotOptions`** - Options for Copilot agent configuration
+- **`GitHubCopilotSettings`** - Pydantic settings for configuration
+
+## Usage
+
+```python
+from agent_framework.github import GitHubCopilotAgent
+
+agent = GitHubCopilotAgent(...)
+response = await agent.run("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework.github import GitHubCopilotAgent
+# or directly:
+from agent_framework_github_copilot import GitHubCopilotAgent
+```
@@ -0,0 +1,22 @@
+# Lab Package (agent-framework-lab)
+
+Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives.
+
+## Structure
+
+This package contains experimental sub-packages:
+
+- `gaia/` - GAIA benchmark integration
+- `lightning/` - Lightning-based training utilities
+- `tau2/` - Tau-bench evaluation framework
+- `namespace/` - Experimental namespace utilities
+
+## Note
+
+Lab packages are experimental and may change frequently. They are not included in the standard `agent-framework[all]` installation.
+
+## Installation
+
+```bash
+pip install agent-framework-lab
+```
@@ -0,0 +1,28 @@
+# Mem0 Package (agent-framework-mem0)
+
+Integration with Mem0 for agent memory management.
+
+## Main Classes
+
+- **`Mem0Provider`** - Context provider that integrates Mem0 memory into agents
+
+## Usage
+
+```python
+from agent_framework.mem0 import Mem0Provider
+
+provider = Mem0Provider(api_key="your-key")
+agent = ChatAgent(..., context_provider=provider)
+```
+
+## Import Path
+
+```python
+from agent_framework.mem0 import Mem0Provider
+# or directly:
+from agent_framework_mem0 import Mem0Provider
+```
+
+## Notes
+
+Mem0 telemetry is disabled by default. Set `MEM0_TELEMETRY=true` to enable.
@@ -0,0 +1,26 @@
+# Ollama Package (agent-framework-ollama)
+
+Integration with Ollama for local LLM inference.
+
+## Main Classes
+
+- **`OllamaChatClient`** - Chat client for Ollama models
+- **`OllamaChatOptions`** - Options TypedDict for Ollama-specific parameters
+- **`OllamaSettings`** - Pydantic settings for Ollama configuration
+
+## Usage
+
+```python
+from agent_framework.ollama import OllamaChatClient
+
+client = OllamaChatClient(model_id="llama3.2")
+response = await client.get_response("Hello")
+```
+
+## Import Path
+
+```python
+from agent_framework.ollama import OllamaChatClient
+# or directly:
+from agent_framework_ollama import OllamaChatClient
+```
@@ -0,0 +1,44 @@
+# Purview Package (agent-framework-purview)
+
+Integration with Microsoft Purview for data governance and policy enforcement.
+
+## Main Classes
+
+### Middleware
+
+- **`PurviewPolicyMiddleware`** - Agent middleware for Purview policy enforcement
+- **`PurviewChatPolicyMiddleware`** - Chat-level middleware for policy enforcement
+
+### Configuration
+
+- **`PurviewSettings`** - Pydantic settings for Purview configuration
+- **`PurviewAppLocation`** / **`PurviewLocationType`** - Location configuration
+
+### Caching
+
+- **`CacheProvider`** - Cache provider for Purview policy caching
+
+### Exceptions
+
+- **`PurviewAuthenticationError`** - Authentication failures
+- **`PurviewRateLimitError`** - Rate limit exceeded
+- **`PurviewRequestError`** / **`PurviewServiceError`** - Request/service errors
+- **`PurviewPaymentRequiredError`** - Payment required
+
+## Usage
+
+```python
+from agent_framework.microsoft import PurviewPolicyMiddleware, PurviewSettings
+
+settings = PurviewSettings(...)
+middleware = PurviewPolicyMiddleware(settings=settings)
+agent = ChatAgent(..., middleware=[middleware])
+```
+
+## Import Path
+
+```python
+from agent_framework.microsoft import PurviewPolicyMiddleware
+# or directly:
+from agent_framework_purview import PurviewPolicyMiddleware
+```
@@ -0,0 +1,25 @@
+# Redis Package (agent-framework-redis)
+
+Redis-based storage for agent threads and context.
+
+## Main Classes
+
+- **`RedisChatMessageStore`** - Persistent message store using Redis
+- **`RedisProvider`** - Context provider with Redis backing
+
+## Usage
+
+```python
+from agent_framework.redis import RedisChatMessageStore
+
+store = RedisChatMessageStore(redis_url="redis://localhost:6379")
+agent = ChatAgent(..., chat_message_store_factory=lambda: store)
+```
+
+## Import Path
+
+```python
+from agent_framework.redis import RedisChatMessageStore, RedisProvider
+# or directly:
+from agent_framework_redis import RedisChatMessageStore
+```