diff --git a/README.md b/README.md index dc47b41f..500dff2d 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,143 @@ -# Microsoft Agent 365 Python SDK +# Microsoft Agent 365 SDK - Python -The Microsoft Agent365 SDK provides comprehensive observability, tooling, and runtime capabilities for AI agents and tools built with Python. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-core?label=PyPI&logo=pypi)](https://pypi.org/search/?q=microsoft-agents-a365) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-core?label=Downloads&logo=pypi)](https://pypi.org/search/?q=microsoft-agents-a365) +[![Build Status](https://img.shields.io/github/actions/workflow/status/microsoft/Agent365-python/build.yml?branch=main&label=Build&logo=github)](https://github.com/microsoft/Agent365-python/actions) +[![License](https://img.shields.io/github/license/microsoft/Agent365-python?label=License)](LICENSE.md) +[![Python Version](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python)](https://www.python.org/) +[![Contributors](https://img.shields.io/github/contributors/microsoft/Agent365-python?label=Contributors&logo=github)](https://github.com/microsoft/Agent365-python/graphs/contributors) -## πŸ“š Library Documentation +> #### Note: +> Use the information in this README to contribute to this open-source project. To learn about using this SDK in your projects, refer to the [Microsoft Agent 365 Developer documentation](https://learn.microsoft.com/microsoft-agent-365/developer/). -Each library includes comprehensive documentation: +The Microsoft Agent 365 SDK extends the Microsoft 365 Agents SDK with enterprise-grade capabilities for building sophisticated agents. This SDK provides comprehensive tooling for observability, notifications, runtime utilities, and development tools that help developers create production-ready agents for platforms including M365, Teams, Copilot Studio, and Webchat. -| Library | Purpose | Documentation | -|---------|---------|---------------| -| **Observability Core** | Core telemetry and tracing | [`/libraries/microsoft-agents-a365-observability-core/README.md`](./libraries/microsoft-agents-a365-observability-core/README.md) | -| **Runtime** | Environment management and utilities | [`/libraries/microsoft-agents-a365-runtime/README.md`](./libraries/microsoft-agents-a365-runtime/README.md) | -| **Tooling** | MCP server configuration and utilities | [`/libraries/microsoft-agents-a365-tooling/README.md`](./libraries/microsoft-agents-a365-tooling/README.md) | -| **OpenAI Extensions** | OpenAI integration and observability | [`/libraries/microsoft-agents-a365-observability-extensions-openai/README.md`](./libraries/microsoft-agents-a365-observability-extensions-openai/README.md) | -| **LangChain Extensions** | LangChain integration and observability | [`/libraries/microsoft-agents-a365-observability-extensions-langchain/README.md`](./libraries/microsoft-agents-a365-observability-extensions-langchain/README.md) | -| **Semantic Kernel Extensions** | Semantic Kernel integration | [`/libraries/microsoft-agents-a365-observability-extensions-semantickernel/README.md`](./libraries/microsoft-agents-a365-observability-extensions-semantickernel/README.md) | +The Microsoft Agent 365 SDK focuses on four core areas: + +- **Observability**: Comprehensive tracing, caching, and monitoring capabilities for agent applications +- **Notifications**: Agent notification services and models for handling user notifications +- **Runtime**: Core utilities and extensions for agent runtime operations +- **Tooling**: Developer tools and utilities for building sophisticated agent applications + +## Current Project State + +This project is currently in active development. Packages are published to PyPI as they become available. + +### Public PyPI feed + +The best way to consume this SDK is via our PyPI packages found here: [pypi.org](https://pypi.org/search/?q=microsoft-agents-a365). All packages begin with **microsoft-agents-a365**. + +## Working with this codebase + +### Prerequisites + +- Python 3.10 or later +- pip or uv package manager +- Git + +### Building the project + +1. Clone the repository: + + ```bash + git clone https://github.com/microsoft/Agent365-python.git + cd Agent365-python + ``` + +2. Create a virtual environment: + + ```bash + python -m venv .venv + source .venv/bin/activate # On Windows: .venv\Scripts\activate + ``` + +3. Build the packages: + + ```bash + # Set the version + export AGENT365_PYTHON_SDK_PACKAGE_VERSION="0.1.0" # On Windows: $env:AGENT365_PYTHON_SDK_PACKAGE_VERSION = "0.1.0" + + # Build all packages + uv build --all-packages --wheel + ``` + +4. Run tests: + + ```bash + pytest tests/ + ``` + +For more detailed build instructions, see the [BUILD.md](BUILD.md). + +## Project Structure + +- **libraries/microsoft-agents-a365-notifications**: Microsoft Agent 365 Notifications SDK - Agent notification services and models +- **libraries/microsoft-agents-a365-observability-core**: Microsoft Agent 365 Observability Core - Core observability functionality +- **libraries/microsoft-agents-a365-observability-extensions-agentframework**: Agent Framework observability extensions +- **libraries/microsoft-agents-a365-observability-extensions-langchain**: LangChain observability extensions +- **libraries/microsoft-agents-a365-observability-extensions-openai**: OpenAI observability extensions +- **libraries/microsoft-agents-a365-observability-extensions-semantickernel**: Semantic Kernel observability extensions +- **libraries/microsoft-agents-a365-runtime**: Microsoft Agent 365 Runtime - Core runtime utilities and extensions +- **libraries/microsoft-agents-a365-tooling**: Microsoft Agent 365 Tooling SDK - Agent tooling and MCP integration +- **libraries/microsoft-agents-a365-tooling-extensions-agentframework**: Agent Framework tooling extensions +- **libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry**: Azure AI Foundry tooling extensions +- **libraries/microsoft-agents-a365-tooling-extensions-openai**: OpenAI tooling extensions +- **libraries/microsoft-agents-a365-tooling-extensions-semantickernel**: Semantic Kernel tooling extensions +- **samples/**: For sample applications, see the [Agent365-Samples Repository](https://github.com/microsoft/Agent365-Samples/tree/main/python) +- **tests/**: Unit and integration tests + +## Support + +For issues, questions, or feedback: + +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- **Documentation**: See the [Microsoft Agents 365 developer documentation](https://learn.microsoft.com/microsoft-agent-365/developer/) +- **Security**: For security issues, please see [SECURITY.md](SECURITY.md) + +## Contributing + +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit . + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## Useful Links + +### Microsoft 365 Agent SDK + +The core SDK for building conversational AI agents for Microsoft 365 platforms. + +- [Microsoft 365 Agents SDK](https://aka.ms/agents) +- [Agents-for-net repository](https://github.com/Microsoft/Agents-for-net) +- [Agents-for-js repository](https://github.com/Microsoft/Agents-for-js) +- [Agents-for-python repository](https://github.com/Microsoft/Agents-for-python) +- [Microsoft 365 Agents documentation](https://learn.microsoft.com/microsoft-365/agents-sdk/) + +### Microsoft Agents 365 SDK + +Enterprise-grade extensions for observability, notifications, runtime utilities, and developer tools. + +- [Agent365-dotnet repository](https://github.com/microsoft/Agent365-dotnet) +- [Agent365-python repository](https://github.com/microsoft/Agent365-python) - You are here +- [Agent365-nodejs repository](https://github.com/microsoft/Agent365-nodejs) +- [Agent365-Samples repository](https://github.com/microsoft/Agent365-Samples) +- [Microsoft Agent 365 developer documentation](https://learn.microsoft.com/microsoft-agent-365/developer/) + +### Additional Resources + +- [Python Documentation](https://learn.microsoft.com/python/api/?view=m365-agents-sdk&preserve-view=true) ## πŸ“‹ **Telemetry** -Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. \ No newline at end of file +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* + +## License + +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-notifications/README.md b/libraries/microsoft-agents-a365-notifications/README.md index 9d59a03b..c404d7f1 100644 --- a/libraries/microsoft-agents-a365-notifications/README.md +++ b/libraries/microsoft-agents-a365-notifications/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Notifications -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-notifications.svg)](https://badge.fury.io/py/microsoft-agents-a365-notifications) +# microsoft-agents-a365-notifications -Notification and messaging extensions for AI agent applications built with the Microsoft Agent 365 SDK. Enable your agents to handle rich notifications from Microsoft 365 applications like Word, Excel, PowerPoint, and Email. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-notifications?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-notifications) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-notifications?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-notifications) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The notifications package specifically handles incoming notifications from Microsoft 365 applications, allowing your agents to respond to events like document updates, email mentions, and collaborative activities. - -## Key Features - -βœ… **Microsoft 365 Integration** - Handle notifications from Word, Excel, PowerPoint, and Outlook -βœ… **Channel Routing** - Intelligent routing based on source application and context -βœ… **Type Safety** - Built with Pydantic for automatic validation and type checking -βœ… **Flexible Handlers** - Support for wildcard and specific channel notification handlers -βœ… **Enterprise Ready** - Built for production Microsoft 365 environments -βœ… **Async Support** - Full async/await support for high-performance applications +Notification and messaging extensions for AI agent applications. This package provides utilities for handling agent notifications, lifecycle events, and routing across different channels and subchannels in Microsoft 365 applications. ## Installation @@ -22,119 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-notifications ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Notifications package enables your agents to receive and respond to notifications from Microsoft 365 applications. Key concepts include: - -- **Notification Handlers**: Functions that process incoming notifications -- **Channel Routing**: Route notifications based on the source application -- **Sub-Channel Filtering**: Handle specific types of notifications (email, documents, etc.) -- **Context Integration**: Access rich context about the notification source - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-notifications` -2. Configure your agent application with notification support -3. Register handlers for specific Microsoft 365 applications -4. Process incoming notifications with full context - -## Supported Microsoft 365 Applications - -| Application | Sub-Channel ID | Description | -|-------------|----------------|-------------| -| **Email** | `email` | Handle mentions and email-based interactions | -| **Word** | `word` | Respond to document collaboration events | -| **Excel** | `excel` | Process spreadsheet updates and analysis requests | -| **PowerPoint** | `powerpoint` | Handle presentation collaboration notifications | -| **Federated Knowledge** | `federatedknowledgeservice` | Enterprise knowledge base interactions | - -## Advanced Usage - -### Notification Processing Features - -- **Custom Route Priorities**: Configure handler execution order for different notification types -- **Authentication Integration**: Seamless integration with Microsoft 365 authentication flows -- **Rich Context Access**: Access detailed metadata about notification sources and content -- **Flexible Filtering**: Support for wildcard matching and specific application targeting +## Usage -### Notification Types +For usage examples and detailed documentation, see the [Notification documentation](https://learn.microsoft.com/microsoft-agent-365/developer/notification?tabs=python) on Microsoft Learn. -The package supports various notification scenarios: -- Document collaboration events (Word, Excel, PowerPoint) -- Email mentions and interactions -- Enterprise knowledge base updates -- Custom application notifications +## Support -## Architecture +For issues, questions, or feedback: -The notifications package follows a clean architecture pattern: +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -- **Route Selectors**: Determine which notifications match specific handlers -- **Activity Wrappers**: Strongly-typed wrappers around raw notification data -- **Handler Registry**: Manages registration and execution of notification handlers -- **Channel Filtering**: Intelligent filtering based on Microsoft 365 application context +## πŸ“‹ **Telemetry** -## Integration with Microsoft Agent 365 SDK +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. -This package works seamlessly with other Microsoft Agent 365 SDK components: +## Trademarks -| Package | Integration | -|---------|-------------| -| `microsoft-agents-activity` | Core activity types and protocols | -| `microsoft-agents-hosting-core` | Agent lifecycle and middleware | -| `microsoft-agents-authentication-msal` | Microsoft 365 authentication | -| `microsoft-agents-hosting-teams` | Teams-specific hosting | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Word Assistant** | Agent that helps with document writing | `samples/word-assistant/` | -| **Excel Analyzer** | Data analysis agent for spreadsheets | `samples/excel-analyzer/` | -| **Email Summarizer** | Automatic email summary agent | `samples/email-summarizer/` | -| **Multi-App Agent** | Handles notifications from all M365 apps | `samples/multi-app-agent/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `typing-extensions >= 4.0.0` - - `microsoft-agents-activity >= 0.4.0` - - `microsoft-agents-hosting-core >= 0.4.0` - - `pydantic >= 2.0.0` - -## Common Use Cases - -### Document Collaboration -- Respond to document updates and changes -- Provide writing assistance and suggestions -- Generate document summaries and reviews -- Handle collaborative editing scenarios - -### Data Analysis Assistant -- Process spreadsheet updates and changes -- Generate insights from data modifications -- Create visualizations and reports -- Assist with data analysis workflows - -### Email Productivity -- Handle email mentions and notifications -- Draft responses and follow-ups -- Extract action items from conversations -- Manage email-based workflows - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -πŸ”§ [Microsoft 365 Developer Center](https://developer.microsoft.com/microsoft-365/) +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-observability-core/README.md b/libraries/microsoft-agents-a365-observability-core/README.md index dd3b3868..4c29e5ca 100644 --- a/libraries/microsoft-agents-a365-observability-core/README.md +++ b/libraries/microsoft-agents-a365-observability-core/README.md @@ -1,15 +1,9 @@ -# Microsoft Agent 365 Observability +# microsoft-agents-a365-observability-core -This package provides telemetry, tracing, and monitoring components for AI agents built on OpenTelemetry. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-core?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-core) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-core?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-core) -This package adds structured spans for agent invocation, tool execution, and LLM inference, and can export them via a custom Agent365 exporter or fall back to console output for development. - -## Features - -* Automatic propagation of context (baggage) values onto span attributes -* Fine‑grained scopes for agent invocation, tool execution, and inference calls -* Pluggable exporter -* Safe, no‑op mode when observability is disabled +Telemetry, tracing, and monitoring components for AI agents built on OpenTelemetry. This package provides structured spans for agent invocation, tool execution, and LLM inference with context propagation and pluggable exporters. ## Installation @@ -17,171 +11,28 @@ This package adds structured spans for agent invocation, tool execution, and LLM pip install microsoft-agents-a365-observability-core ``` -## Core Environment Variables - -Set these (e.g. in a `.env` file or your hosting environment) before configuring: - -```properties -ENABLE_OBSERVABILITY=true # Turns on tracing & span creation -ENABLE_A365_OBSERVABILITY_EXPORTER=true # Use Agent365 exporter (otherwise falls back to ConsoleSpanExporter) -PYTHON_ENVIRONMENT=production # Or development; influences target cluster/category resolution -``` - -Prefer the canonical `ENABLE_A365_OBSERVABILITY_EXPORTER`. If you omit `ENABLE_OBSERVABILITY` or set it to false, scopes become no‑ops and no spans are recorded. - -## Configuration - -Use `configure` to set up the tracer provider and span processors. You must provide a `service_name` and `service_namespace`. - -### Minimal configuration (no custom exporter) - -```python -from microsoft_agents_a365.observability.core import config - -config.configure( - service_name="my-agent-service", - service_namespace="my.namespace" -) - -tracer = config.get_tracer() -``` - -When neither `ENABLE_A365_OBSERVABILITY_EXPORTER` nor any legacy alias is truthy, or a required token resolver is missing, the SDK falls back to `ConsoleSpanExporter` and logs warnings. Legacy usage triggers a deprecation warning. - -### Configuration with Agent365 exporter - -The Agent365 exporter requires a `token_resolver` callback that can return an auth token given `(agent_id, tenant_id)` plus the cluster category (defaults to `preprod`). - -```python -from microsoft_agents_a365.observability.core import config - -def token_resolver(agent_id: str, tenant_id: str) -> str | None: - # Implement secure token retrieval here - return "Bearer " - -config.configure( - service_name="my-agent-service", - service_namespace="my.namespace", - token_resolver=token_resolver, # enables exporter if ENABLE_A365_OBSERVABILITY_EXPORTER or legacy alias is true - cluster_category="preprod" # or "prod" -) -``` - -### Exporter Setup Essentials - -Agent365 exporter activation logic: - -1. `ENABLE_A365_OBSERVABILITY_EXPORTER` (canonical) or any legacy alias is truthy (`true`, `1`, `yes`, `on`). -2. A non-None `token_resolver` is passed to `configure`. -3. Environment determines cluster category (overridden by explicit `cluster_category`). - -If any prerequisite fails, console export is used. No code changes required. - -## Baggage to Span Attributes - -The custom `SpanProcessor` copies all non-empty baggage entries to newly started spans without overwriting existing attributes. - -Helper builder: - -```python -from microsoft_agents_a365.observability.core.middleware.baggage_builder import BaggageBuilder - -with ( - BaggageBuilder() - .tenant_id("tenant-123") - .agent_id("agent-456") - .correlation_id("corr-789") - .build() -): - # Any spans started in this context will receive these as attributes - pass -``` - -## Scopes Overview - -The SDK provides three high-level scope types (context managers) that start and end spans automatically: +## Usage -| Scope | Purpose | Typical Use | -|-------|---------|-------------| -| `InvokeAgentScope` | Agent invocation lifecycle | Wrap an agent invocation at the start of workflow | -| `ExecuteToolScope` | Tool / function execution | Wrap execution of a tool inside an agent workflow | -| `InferenceScope` | LLM inference / completion | Wrap a model inference request | +For usage examples and detailed documentation, see the [Observability documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=python) on Microsoft Learn. -Each exposes a static `start(...)` returning a context manager. +## Support -### InvokeAgentScope Usage +For issues, questions, or feedback: -```python -from microsoft_agents_a365.observability.core.invoke_agent_scope import InvokeAgentScope -from microsoft_agents_a365.observability.core.invoke_agent_details import InvokeAgentDetails -from microsoft_agents_a365.observability.core.tenant_details import TenantDetails -from microsoft_agents_a365.observability.core.request import Request - -invoke_details = InvokeAgentDetails( - details=agent_details, # AgentDetails instance - endpoint=my_endpoint, # Optional endpoint (with hostname/port) - session_id="session-42" -) -tenant_details = TenantDetails(tenant_id="tenant-123") -req = Request(content="User asks a question") - -with InvokeAgentScope.start(invoke_details, tenant_details, req): - # Perform agent invocation logic - response = call_agent(...) -``` +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -Tags automatically set (when values present): agent id/name/description, session id, request content, server address/port. - -### ExecuteToolScope Usage - -```python -from microsoft_agents_a365.observability.core.execute_tool_scope import ExecuteToolScope -from microsoft_agents_a365.observability.core.tool_call_details import ToolCallDetails - -tool_details = ToolCallDetails( - tool_name="summarize", - tool_type="function", - tool_call_id="tc-001", - arguments="{'text': '...'}", - description="Summarize provided text", - endpoint=None # or endpoint object with hostname/port -) - -with ExecuteToolScope.start(tool_details, agent_details, tenant_details): - result = run_tool(tool_details) -``` - -Tags: tool name, arguments, type, call id, description, server address/port. - -### InferenceScope Usage - -```python -from microsoft_agents_a365.observability.core.inference_scope import InferenceScope -from microsoft_agents_a365.observability.core.inference_call_details import InferenceCallDetails -from microsoft_agents_a365.observability.core.request import Request - -inference_details = InferenceCallDetails( - operationName=SomeEnumOrValue("chat"), - model="gpt-4o-mini", - providerName="azure-openai", - inputTokens=123, - outputTokens=456, - finishReasons=["stop"], - responseId="resp-987" -) -req = Request(content="Explain quantum computing simply.") - -with InferenceScope.start(inference_details, agent_details, tenant_details, req): - completion = call_llm(...) -``` +## πŸ“‹ **Telemetry** -Tags: model, provider name, request content, input/output tokens, finish reasons, response id. +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* -## Disabling Observability +## License -Set `ENABLE_OBSERVABILITY=false` (or remove it). Scopes still usable but no spans or exports occur. +Copyright (c) Microsoft Corporation. All rights reserved. -## Best Practices +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. -* Create scopes as narrow as possible (only the work you want timed). -* Use baggage for cross-cutting identifiers (tenant, correlation id) rather than manually setting on every scope. diff --git a/libraries/microsoft-agents-a365-observability-extensions-agentframework/README.md b/libraries/microsoft-agents-a365-observability-extensions-agentframework/README.md index 8cf5f263..e1e7ed13 100644 --- a/libraries/microsoft-agents-a365-observability-extensions-agentframework/README.md +++ b/libraries/microsoft-agents-a365-observability-extensions-agentframework/README.md @@ -1,16 +1,37 @@ # microsoft-agents-a365-observability-extensions-agentframework -## Overview +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-extensions-agentframework?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-agentframework) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-extensions-agentframework?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-agentframework) -This package provides Agent365 SDK observability extensions for the agent framework. +Observability extensions for Microsoft Agent Framework. This package provides OpenTelemetry tracing integration specifically for Agent Framework-based applications. -## Features +## Installation -- Seamless integration with the Agent Framework -- Supports OpenTelemetry (OTEL) for distributed tracing -- Optional capture of sensitive data for deeper diagnostics -- Easy configuration via environment variables +```bash +pip install microsoft-agents-a365-observability-extensions-agentframework +``` -To allow the A365 observability SDK to capture input and output messages, please enable the flags in environment: -ENABLE_OTEL=true -ENABLE_SENSITIVE_DATA=true \ No newline at end of file +## Usage + +For usage examples and detailed documentation, see the [Observability documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=python) on Microsoft Learn. + +## Support + +For issues, questions, or feedback: + +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information + +## πŸ“‹ **Telemetry** + +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* + +## License + +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-observability-extensions-langchain/README.md b/libraries/microsoft-agents-a365-observability-extensions-langchain/README.md index fd693ad3..abb77a98 100644 --- a/libraries/microsoft-agents-a365-observability-extensions-langchain/README.md +++ b/libraries/microsoft-agents-a365-observability-extensions-langchain/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Observability Extensions - LangChain -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-observability-extensions-langchain.svg)](https://badge.fury.io/py/microsoft-agents-a365-observability-extensions-langchain) +# microsoft-agents-a365-observability-extensions-langchain -LangChain observability and tracing extensions for AI agent applications built with the Microsoft Agent 365 SDK. Enable comprehensive monitoring and telemetry for your LangChain-powered agents with automatic instrumentation and OpenTelemetry integration. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-extensions-langchain?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-langchain) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-extensions-langchain?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-langchain) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The LangChain observability extensions specifically provide automatic instrumentation and monitoring for agents built using the LangChain framework, capturing detailed traces, metrics, and performance data. - -## Key Features - -βœ… **Automatic LangChain Instrumentation** - Zero-configuration tracing for chains, agents, and tools -βœ… **Chain Execution Monitoring** - Detailed visibility into sequential and parallel chain operations -βœ… **Agent Workflow Tracing** - Comprehensive tracking of agent reasoning and decision-making -βœ… **Tool Invocation Telemetry** - Granular monitoring of individual tool calls and performance -βœ… **OpenTelemetry Compliance** - Full compatibility with OpenTelemetry standards and tooling -βœ… **Production Ready** - Built for enterprise-scale monitoring and observability +Observability extensions for LangChain framework. This package provides OpenTelemetry tracing integration for LangChain-based AI applications with automatic instrumentation for chains, agents, and tools. ## Installation @@ -22,144 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-observability-extensions-langchain ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 LangChain Observability Extensions automatically instrument your LangChain applications to provide comprehensive monitoring. Key concepts include: - -- **Automatic Instrumentation**: Zero-configuration tracing for LangChain components -- **Chain Tracing**: Monitor the flow and performance of LangChain chains -- **Agent Monitoring**: Track agent reasoning, tool selection, and execution -- **Context Propagation**: Automatic correlation of related operations across async workflows - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-observability-extensions-langchain` -2. Configure the observability system with your service details -3. Enable LangChain instrumentation with a single line of code -4. Your LangChain applications will be automatically traced - -### Basic Integration - -```python -from microsoft_agents_a365.observability.core.config import configure -from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor - -# Configure observability -configure( - service_name="my-langchain-agent", - service_namespace="ai.agents" -) - -# Enable automatic instrumentation -instrumentor = CustomLangChainInstrumentor() -instrumentor.instrument() - -# Your LangChain code is now automatically traced -``` - -## Supported LangChain Components - -| Component | Instrumentation | Description | -|-----------|----------------|-------------| -| **Chains** | Automatic | Sequential and parallel chain execution tracking | -| **Agents** | Automatic | Agent reasoning, tool selection, and execution monitoring | -| **Tools** | Automatic | Individual tool invocation and performance metrics | -| **LLMs** | Automatic | Language model calls, token usage, and latency tracking | -| **Retrievers** | Automatic | Document retrieval and similarity search operations | -| **Memory** | Automatic | Conversation memory and context management | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Observability documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=python) on Microsoft Learn. -### Observability Features +## Support -- **Performance Metrics**: Execution times, token usage, and throughput analysis -- **Error Tracking**: Comprehensive error capture and failure analysis -- **Context Correlation**: Automatic linking of related operations across async workflows -- **Custom Attributes**: Add business-specific metadata to traces and spans +For issues, questions, or feedback: -### Environment Configuration +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -```properties -# Core observability settings -ENABLE_OBSERVABILITY=true -ENABLE_A365_OBSERVABILITY_EXPORTER=true -PYTHON_ENVIRONMENT=production - -# LangChain-specific settings -LANGCHAIN_TRACING_V2=false # Disable to avoid duplicate tracing -``` +## πŸ“‹ **Telemetry** -## Architecture - -The observability extensions follow a layered architecture: - -- **Instrumentor Layer**: Automatic detection and wrapping of LangChain components -- **Span Management**: Hierarchical span creation following OpenTelemetry conventions -- **Context Propagation**: Automatic correlation across async operations and tool calls -- **Export Pipeline**: Efficient batching and export to observability backends - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-observability-core` | Core telemetry and tracing infrastructure | -| `microsoft-agents-a365-runtime` | Agent execution runtime and lifecycle | -| `microsoft-agents-a365-tooling` | Tool management and execution | -| `microsoft-agents-a365-hosting-core` | Agent hosting and middleware | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Research Agent** | LangChain agent with search and analysis tools | `samples/langchain-research-agent/` | -| **Document Assistant** | Multi-step document processing chains | `samples/langchain-document-assistant/` | -| **Data Analyst** | SQL and visualization agent with observability | `samples/langchain-data-analyst/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `microsoft-agents-a365-observability-core >= 0.1.0` - - `langchain >= 0.1.0` - - `langchain-core >= 0.1.0` - - `opentelemetry-api >= 1.20.0` - - `opentelemetry-sdk >= 1.20.0` - - `opentelemetry-instrumentation >= 0.41b0` - -## Common Use Cases - -### Development and Debugging -- Monitor chain execution flow and identify bottlenecks -- Track agent reasoning and tool selection patterns -- Analyze LLM token usage and optimize costs -- Debug complex multi-step agent workflows - -### Production Monitoring -- Monitor agent performance and reliability at scale -- Track success rates and error patterns -- Analyze user interaction patterns and agent effectiveness -- Set up alerts for performance degradation or failures - -### Analytics and Optimization -- Understand agent behavior and usage patterns -- Identify opportunities for workflow optimization -- Monitor cost and performance trade-offs -- Generate insights for agent improvement - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -πŸ“Š [OpenTelemetry Documentation](https://opentelemetry.io/) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-observability-extensions-openai/README.md b/libraries/microsoft-agents-a365-observability-extensions-openai/README.md index 315ca757..0287a398 100644 --- a/libraries/microsoft-agents-a365-observability-extensions-openai/README.md +++ b/libraries/microsoft-agents-a365-observability-extensions-openai/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Observability Extensions - OpenAI Agents -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-observability-extensions-openai.svg)](https://badge.fury.io/py/microsoft-agents-a365-observability-extensions-openai) +# microsoft-agents-a365-observability-extensions-openai -OpenAI Agents SDK observability and tracing extensions for AI agent applications built with the Microsoft Agent 365 SDK. Enable comprehensive monitoring and telemetry for your OpenAI Agents-powered applications with automatic instrumentation and OpenTelemetry integration. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-extensions-openai?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-openai) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-extensions-openai?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-openai) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The OpenAI Agents observability extensions specifically provide automatic instrumentation and monitoring for agents built using the OpenAI Agents SDK, capturing detailed traces, metrics, and performance data. - -## Key Features - -βœ… **Automatic OpenAI Agents Instrumentation** - Zero-configuration tracing for OpenAI Agents SDK components -βœ… **Agent Workflow Monitoring** - Comprehensive tracking of agent execution and decision-making -βœ… **Tool Invocation Telemetry** - Granular monitoring of individual tool calls and performance -βœ… **Thread Management Tracing** - Track conversation threads and message flows -βœ… **OpenTelemetry Compliance** - Full compatibility with OpenTelemetry standards and tooling -βœ… **Production Ready** - Built for enterprise-scale monitoring and observability +Observability extensions for OpenAI Agents SDK. This package provides OpenTelemetry tracing integration for OpenAI Agents-based applications with automatic instrumentation for agent workflows and tool invocations. ## Installation @@ -22,145 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-observability-extensions-openai ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 OpenAI Agents Observability Extensions automatically instrument your OpenAI Agents applications to provide comprehensive monitoring. Key concepts include: - -- **Automatic Instrumentation**: Zero-configuration tracing for OpenAI Agents SDK components -- **Agent Tracing**: Monitor agent creation, execution, and lifecycle events -- **Thread Monitoring**: Track conversation threads and message processing -- **Tool Execution**: Monitor individual tool calls and their performance -- **Context Propagation**: Automatic correlation of related operations across async workflows - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-observability-extensions-openai` -2. Configure the observability system with your service details -3. Enable OpenAI Agents instrumentation with a single line of code -4. Your OpenAI Agents applications will be automatically traced - -### Basic Integration - -```python -from microsoft_agents_a365.observability.core.config import configure -from microsoft_agents_a365.observability.extensions.openai_agents import OpenAIAgentsTraceInstrumentor - -# Configure observability -configure( - service_name="my-openai-agent", - service_namespace="ai.agents" -) - -# Enable automatic instrumentation -instrumentor = OpenAIAgentsTraceInstrumentor() -instrumentor.instrument() - -# Your OpenAI Agents code is now automatically traced -``` - -## Supported OpenAI Agents Components - -| Component | Instrumentation | Description | -|-----------|----------------|-------------| -| **Agents** | Automatic | Agent creation, execution, and lifecycle monitoring | -| **Threads** | Automatic | Conversation thread management and message flow tracking | -| **Tools** | Automatic | Individual tool invocation and performance metrics | -| **Runs** | Automatic | Agent run execution, status changes, and completion tracking | -| **Messages** | Automatic | Message creation, processing, and response generation | -| **Function Calls** | Automatic | Function execution and result processing | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Observability documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=python) on Microsoft Learn. -### Observability Features +## Support -- **Performance Metrics**: Execution times, token usage, and throughput analysis -- **Error Tracking**: Comprehensive error capture and failure analysis -- **Context Correlation**: Automatic linking of related operations across async workflows -- **Custom Attributes**: Add business-specific metadata to traces and spans +For issues, questions, or feedback: -### Environment Configuration +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -```properties -# Core observability settings -ENABLE_OBSERVABILITY=true -ENABLE_A365_OBSERVABILITY_EXPORTER=true -PYTHON_ENVIRONMENT=production - -# OpenAI Agents-specific settings -OPENAI_API_KEY=your_api_key_here -OPENAI_ORG_ID=your_org_id_here -``` +## πŸ“‹ **Telemetry** -## Architecture - -The observability extensions follow a layered architecture: - -- **Instrumentor Layer**: Automatic detection and wrapping of OpenAI Agents SDK components -- **Span Management**: Hierarchical span creation following OpenTelemetry conventions -- **Context Propagation**: Automatic correlation across async operations and tool calls -- **Export Pipeline**: Efficient batching and export to observability backends - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-observability-core` | Core telemetry and tracing infrastructure | -| `microsoft-agents-a365-runtime` | Agent execution runtime and lifecycle | -| `microsoft-agents-a365-tooling` | Tool management and execution | -| `microsoft-agents-a365-hosting-core` | Agent hosting and middleware | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Customer Service Agent** | OpenAI agent with support ticket handling | `samples/openai-customer-service/` | -| **Code Assistant** | Programming assistant with code analysis tools | `samples/openai-code-assistant/` | -| **Data Analysis Agent** | Data processing agent with visualization tools | `samples/openai-data-analyst/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `microsoft-agents-a365-observability-core >= 0.1.0` - - `openai-agents >= 0.2.6` - - `opentelemetry-api >= 1.20.0` - - `opentelemetry-sdk >= 1.20.0` - - `opentelemetry-instrumentation >= 0.41b0` - -## Common Use Cases - -### Development and Debugging -- Monitor agent execution flow and identify bottlenecks -- Track tool selection and execution patterns -- Analyze token usage and optimize costs -- Debug complex multi-step agent workflows - -### Production Monitoring -- Monitor agent performance and reliability at scale -- Track success rates and error patterns -- Analyze user interaction patterns and agent effectiveness -- Set up alerts for performance degradation or failures - -### Analytics and Optimization -- Understand agent behavior and usage patterns -- Identify opportunities for workflow optimization -- Monitor cost and performance trade-offs -- Generate insights for agent improvement - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -πŸ€– [OpenAI Agents Documentation](https://platform.openai.com/docs/assistants/overview) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-observability-extensions-semantickernel/README.md b/libraries/microsoft-agents-a365-observability-extensions-semantickernel/README.md index e74757f4..5dd909a8 100644 --- a/libraries/microsoft-agents-a365-observability-extensions-semantickernel/README.md +++ b/libraries/microsoft-agents-a365-observability-extensions-semantickernel/README.md @@ -1,168 +1,37 @@ -# Microsoft Agent 365 Observability Extensions - Semantic Kernel -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-observability-extensions-semantic-kernel.svg)](https://badge.fury.io/py/microsoft-agents-a365-observability-extensions-semantic-kernel) +# microsoft-agents-a365-observability-extensions-semantickernel -Semantic Kernel observability and tracing extensions for AI agent applications built with the Microsoft Agent 365 SDK. Enable comprehensive monitoring and telemetry for your Semantic Kernel-powered applications with automatic instrumentation and OpenTelemetry integration. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-extensions-semantickernel?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-semantickernel) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-extensions-semantickernel?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-semantickernel) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The Semantic Kernel observability extensions specifically provide automatic instrumentation and monitoring for agents built using the Microsoft Semantic Kernel framework, capturing detailed traces, metrics, and performance data. - -## Key Features - -βœ… **Automatic Semantic Kernel Instrumentation** - Zero-configuration tracing for Semantic Kernel components -βœ… **Kernel Function Monitoring** - Comprehensive tracking of function execution and performance -βœ… **Plugin Invocation Telemetry** - Granular monitoring of individual plugin calls and results -βœ… **Planner Execution Tracing** - Track planning processes and step-by-step execution -βœ… **OpenTelemetry Compliance** - Full compatibility with OpenTelemetry standards and tooling -βœ… **Production Ready** - Built for enterprise-scale monitoring and observability +Observability extensions for Semantic Kernel framework. This package provides OpenTelemetry tracing integration for Semantic Kernel-based applications with automatic instrumentation for kernel functions, plugins, and planners. ## Installation ```bash -pip install microsoft-agents-a365-observability-extensions-semantic-kernel -``` - -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Semantic Kernel Observability Extensions automatically instrument your Semantic Kernel applications to provide comprehensive monitoring. Key concepts include: - -- **Automatic Instrumentation**: Zero-configuration tracing for Semantic Kernel components -- **Kernel Tracing**: Monitor kernel creation, configuration, and execution -- **Function Monitoring**: Track kernel function calls and their performance -- **Plugin Execution**: Monitor individual plugin invocations and results -- **Planner Tracing**: Track planning processes and multi-step executions -- **Context Propagation**: Automatic correlation of related operations across async workflows - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-observability-extensions-semantic-kernel` -2. Configure the observability system with your service details -3. Enable Semantic Kernel instrumentation with a single line of code -4. Your Semantic Kernel applications will be automatically traced - -### Basic Integration - -```python -from microsoft_agents_a365.observability.core.config import configure -from microsoft_agents_a365.observability.extensions.semantic_kernel import SemanticKernelInstrumentor - -# Configure observability -configure( - service_name="my-semantic-kernel-agent", - service_namespace="ai.agents" -) - -# Enable automatic instrumentation -instrumentor = SemanticKernelInstrumentor() -instrumentor.instrument() - -# Your Semantic Kernel code is now automatically traced +pip install microsoft-agents-a365-observability-extensions-semantickernel ``` -## Supported Semantic Kernel Components - -| Component | Instrumentation | Description | -|-----------|----------------|-------------| -| **Kernel** | Automatic | Kernel creation, configuration, and lifecycle monitoring | -| **Functions** | Automatic | Kernel function execution and performance tracking | -| **Plugins** | Automatic | Plugin invocation and result processing | -| **Planners** | Automatic | Planning process execution and step tracking | -| **Memory** | Automatic | Memory operations and retrieval monitoring | -| **Connectors** | Automatic | AI service connector calls and token usage | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Observability documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=python) on Microsoft Learn. -### Observability Features +## Support -- **Performance Metrics**: Execution times, token usage, and throughput analysis -- **Error Tracking**: Comprehensive error capture and failure analysis -- **Context Correlation**: Automatic linking of related operations across async workflows -- **Custom Attributes**: Add business-specific metadata to traces and spans +For issues, questions, or feedback: -### Environment Configuration +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -```properties -# Core observability settings -ENABLE_OBSERVABILITY=true -ENABLE_A365_OBSERVABILITY_EXPORTER=true -PYTHON_ENVIRONMENT=production - -# Semantic Kernel-specific settings -AZURE_OPENAI_API_KEY=your_api_key_here -AZURE_OPENAI_ENDPOINT=your_endpoint_here -OPENAI_API_KEY=your_openai_key_here -``` +## πŸ“‹ **Telemetry** -## Architecture - -The observability extensions follow a layered architecture: - -- **Instrumentor Layer**: Automatic detection and wrapping of Semantic Kernel components -- **Span Management**: Hierarchical span creation following OpenTelemetry conventions -- **Context Propagation**: Automatic correlation across async operations and function calls -- **Export Pipeline**: Efficient batching and export to observability backends - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-observability-core` | Core telemetry and tracing infrastructure | -| `microsoft-agents-a365-runtime` | Agent execution runtime and lifecycle | -| `microsoft-agents-a365-tooling` | Tool management and execution | -| `microsoft-agents-a365-hosting-core` | Agent hosting and middleware | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Planning Agent** | Semantic Kernel agent with multi-step planning | `samples/semantic-kernel-planner/` | -| **Plugin Orchestrator** | Agent with multiple custom plugins | `samples/semantic-kernel-plugins/` | -| **Memory Assistant** | Conversational agent with persistent memory | `samples/semantic-kernel-memory/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `microsoft-agents-a365-observability-core >= 0.1.0` - - `semantic-kernel >= 1.0.0` - - `opentelemetry-api >= 1.20.0` - - `opentelemetry-sdk >= 1.20.0` - - `opentelemetry-instrumentation >= 0.41b0` - -## Common Use Cases - -### Development and Debugging -- Monitor kernel function execution flow and identify bottlenecks -- Track plugin selection and execution patterns -- Analyze token usage across different AI connectors -- Debug complex multi-step planning workflows - -### Production Monitoring -- Monitor agent performance and reliability at scale -- Track success rates and error patterns -- Analyze user interaction patterns and agent effectiveness -- Set up alerts for performance degradation or failures - -### Analytics and Optimization -- Understand agent behavior and usage patterns -- Identify opportunities for workflow optimization -- Monitor cost and performance trade-offs -- Generate insights for agent improvement - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -🧠 [Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-runtime/README.md b/libraries/microsoft-agents-a365-runtime/README.md index b7c5c616..1cdc7c28 100644 --- a/libraries/microsoft-agents-a365-runtime/README.md +++ b/libraries/microsoft-agents-a365-runtime/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Runtime -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-runtime.svg)](https://badge.fury.io/py/microsoft-agents-a365-runtime) +# microsoft-agents-a365-runtime -Core runtime utilities and environment management for AI agent applications built with the Microsoft Agent 365 SDK. Provides essential Power Platform API discovery, environment configuration, and version management for enterprise-grade conversational AI agents. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-runtime?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-runtime) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-runtime?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-runtime) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The runtime package provides core utilities for environment management, Power Platform API discovery, and version handling that enable agents to operate seamlessly across different deployment environments. - -## Key Features - -βœ… **Power Platform API Discovery** - Automatic discovery of Power Platform API endpoints across environments -βœ… **Environment Management** - Intelligent environment detection and configuration utilities -βœ… **Authentication Scopes** - Environment-specific authentication scope resolution -βœ… **Version Management** - Automated version generation and SDK version handling -βœ… **Multi-Environment Support** - Support for development, test, preprod, and production environments -βœ… **Enterprise Ready** - Production-grade utilities for large-scale deployments +Core runtime utilities and environment management for AI agent applications. This package provides essential Power Platform API discovery, environment configuration, and authentication scope resolution. ## Installation @@ -22,142 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-runtime ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Runtime provides essential utilities for agent applications to operate across different environments. Key concepts include: - -- **Environment Detection**: Automatic detection of current deployment environment -- **API Discovery**: Dynamic discovery of Power Platform API endpoints -- **Authentication Scopes**: Environment-specific authentication scope resolution -- **Version Management**: Automated version generation for SDK packages - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-runtime` -2. Import the runtime utilities in your agent application -3. Use environment detection and API discovery for configuration -4. Leverage version utilities for package management - -### Basic Usage - -```python -from microsoft_agents_a365.runtime import ( - get_observability_authentication_scope, - PowerPlatformApiDiscovery, - ClusterCategory -) - -# Get authentication scope for current environment -auth_scope = get_observability_authentication_scope() - -# Discover Power Platform API endpoints -discovery = PowerPlatformApiDiscovery("prod") -token_audience = discovery.get_token_audience() -tenant_endpoint = discovery.get_tenant_endpoint("your-tenant-id") -``` - -## Core Runtime Components - -| Component | Purpose | Description | -|-----------|---------|-------------| -| **Environment Utils** | Environment Detection | Detect current environment and get appropriate configuration | -| **Power Platform API Discovery** | API Endpoint Resolution | Discover Power Platform API endpoints for different environments | -| **Version Utils** | Version Management | Generate and manage SDK package versions | -| **Cluster Categories** | Environment Classification | Support for multiple deployment cluster categories | - -## Supported Environments - -| Environment | Cluster Category | Authentication Scope | -|-------------|------------------|---------------------| -| **Development** | `preprod` | `https://api.preprod.powerplatform.com/.default` | -| **Test** | `test` | `https://api.test.powerplatform.com/.default` | -| **Production** | `prod` | `https://api.powerplatform.com/.default` | -| **Government** | `gov` | Government cloud endpoints | -| **Sovereign Clouds** | `mooncake`, `dod`, etc. | Region-specific endpoints | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Microsoft Agent 365 Developer documentation](https://learn.microsoft.com/microsoft-agent-365/developer/?tabs=python) on Microsoft Learn. -### API Discovery Features +## Support -- **Tenant Endpoint Resolution**: Generate tenant-specific API endpoints -- **Island Cluster Support**: Support for tenant island cluster endpoints -- **Multi-Cloud Support**: Support for sovereign and government clouds -- **Dynamic Configuration**: Runtime configuration based on environment detection +For issues, questions, or feedback: -### Environment Configuration +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -The runtime automatically detects environments through: -- Environment variable detection (`PYTHON_ENVIRONMENT`) -- Automatic environment classification -- Fallback to production configuration for unknown environments -- Support for custom environment configurations +## πŸ“‹ **Telemetry** -## Architecture - -The runtime follows a utility-focused architecture: - -- **Environment Layer**: Environment detection and configuration management -- **Discovery Layer**: Power Platform API endpoint discovery and resolution -- **Version Layer**: SDK version management and generation utilities -- **Configuration Layer**: Environment-specific configuration resolution - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-observability-core` | Provides authentication scopes for observability services | -| `microsoft-agents-a365-tooling` | Environment detection for tool configuration | -| `microsoft-agents-a365-hosting-core` | Runtime environment configuration for hosting | -| `microsoft-agents-a365-notifications` | Environment-aware notification routing | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Multi-Environment Agent** | Agent that adapts to different environments | `samples/multi-env-agent/` | -| **Power Platform Integration** | Agent with Power Platform API discovery | `samples/power-platform-agent/` | -| **Enterprise Deployment** | Production-ready agent with environment management | `samples/enterprise-deployment/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - No external dependencies (lightweight core utilities) - -## Common Use Cases - -### Development and Testing -- Automatically configure agents for different development environments -- Discover appropriate API endpoints for testing scenarios -- Manage version generation during development cycles -- Support local development with preprod configurations - -### Production Deployment -- Automatically detect production environments and configure accordingly -- Resolve correct Power Platform API endpoints for production workloads -- Generate appropriate version strings for release packages -- Support multi-tenant deployments with tenant-specific endpoints - -### Enterprise Integration -- Support sovereign cloud deployments (Government, DoD, etc.) -- Integrate with existing enterprise environment management -- Provide consistent configuration across multiple deployment environments -- Enable environment-aware authentication and API access - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -🏒 [Power Platform Documentation](https://docs.microsoft.com/power-platform/) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-tooling-extensions-agentframework/README.md b/libraries/microsoft-agents-a365-tooling-extensions-agentframework/README.md index ed115007..b0e22d32 100644 --- a/libraries/microsoft-agents-a365-tooling-extensions-agentframework/README.md +++ b/libraries/microsoft-agents-a365-tooling-extensions-agentframework/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Tooling Extensions - Agent Framework -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-agentframework.svg)](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-agentframework) +# microsoft-agents-a365-tooling-extensions-agentframework -Agent Framework integration tools and MCP tool registration services for AI agent applications built with the Microsoft Agent 365 SDK. Provides specialized tooling for integrating MCP (Model Context Protocol) servers with Agent Framework agents and projects. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-tooling-extensions-agentframework?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-agentframework) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-tooling-extensions-agentframework?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-agentframework) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The Agent Framework tooling extensions specifically provide integration with Microsoft Agent Framework, enabling seamless registration and management of MCP tool servers within the Agent Framework ecosystem. - -## Key Features - -βœ… **Agent Framework Integration** - Native integration with Microsoft Agent Framework -βœ… **MCP Tool Registration** - Automatic registration of MCP servers with Agent Framework agents -βœ… **Azure Identity Support** - Built-in Azure authentication with DefaultAzureCredential -βœ… **Tool Resource Management** - Comprehensive management of tool definitions and resources -βœ… **Multi-Environment Support** - Support for development and production deployment scenarios -βœ… **Enterprise Ready** - Production-grade tooling for Agent Framework-based agent deployments +Agent Framework specific tools and services for AI agent development. Provides MCP (Model Context Protocol) tool registration service for dynamically adding MCP servers to Agent Framework agents. ## Installation @@ -22,261 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-tooling-extensions-agentframework ``` -### Prerequisites - -The Agent Framework tooling extensions require the Agent Framework Core package: - -```bash -# Core Agent Framework (includes Azure OpenAI and OpenAI support by default) -# also includes workflows and orchestrations -pip install agent-framework-core --pre -``` - -**Optional Agent Framework packages:** -```bash -# Core + Azure AI integration -pip install agent-framework-azure-ai --pre - -# Core + Microsoft Copilot Studio integration -pip install agent-framework-copilotstudio --pre - -# Core + both Microsoft Copilot Studio and Azure AI integration -pip install agent-framework-microsoft agent-framework-azure-ai --pre -``` - -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Agent Framework Tooling Extensions enable seamless integration between MCP tool servers and Agent Framework agents. Key concepts include: - -- **MCP Tool Registration**: Automatic registration of tool definitions with Agent Framework -- **Agent Resource Management**: Management of agent resources and configurations -- **Tool Discovery**: Dynamic discovery and registration of available tools -- **Service Integration**: Integration with various service providers and backends - -### Basic Usage - -```python -import asyncio -from agent_framework import ChatAgent -from agent_framework.azure import AzureOpenAIChatClient -from microsoft_agents_a365.tooling.extensions.agentframework import ( - McpToolRegistrationService, -) - -async def main(): - # Initialize the MCP tool registration service - service = McpToolRegistrationService() - - # Create Azure OpenAI chat client - chat_client = AzureOpenAIChatClient( - api_key='', - endpoint='', - deployment_name='', - api_version='', - ) - - # Create agent with MCP tools from all configured servers - agent = await service.add_tool_servers_to_agent( - chat_client=chat_client, - agent_instructions="You are a helpful assistant that can provide weather and restaurant information.", - initial_tools=[], # Your existing tools - agentic_app_id="user-123", - auth_token="your-auth-token" - ) - -if __name__ == "__main__": - asyncio.run(main()) -``` - -### Advanced Configuration - -```python -import asyncio -from agent_framework import ChatAgent -from agent_framework.azure import AzureOpenAIChatClient -from microsoft_agents_a365.tooling.extensions.agentframework import ( - McpToolRegistrationService, -) - -async def main(): - # Initialize with custom logger - import logging - - logger = logging.getLogger("my-agent") - - service = McpToolRegistrationService( - logger=logger - ) - - # Create Azure OpenAI chat client - chat_client = AzureOpenAIChatClient( - api_key='', - endpoint='', - deployment_name='', - api_version='', - ) - - # Define existing tools (if any) - existing_tools = [ - # Your existing tools go here - ] - - # Create agent with comprehensive instructions and all MCP tools - agent = await service.add_tool_servers_to_agent( - chat_client=chat_client, - agent_instructions=""" - You are a helpful AI assistant with access to various tools and services. - - Guidelines: - 1) Always be helpful and accurate - 2) Use available tools when appropriate to provide better assistance - 3) Explain your reasoning when using tools - - You have access to MCP (Model Context Protocol) tools that are automatically - loaded from configured servers. Use these tools to enhance your capabilities. - """, - initial_tools=existing_tools, - agentic_app_id="user-123", - auth_token="your-auth-token" - ) - - # The agent now has all MCP tools from configured servers - print(f"Agent created with {len(agent.tools)} total tools") - -if __name__ == "__main__": - asyncio.run(main()) -``` - -## Configuration - -The library supports various configuration options through environment variables: - -- `AGENT_FRAMEWORK_ENDPOINT`: The Agent Framework endpoint URL -- `AGENT_FRAMEWORK_API_KEY`: API key for Agent Framework authentication -- `MCP_TOOLS_DIRECTORY`: Directory containing MCP tool definitions -- `AGENT_ENVIRONMENT`: Deployment environment (development, staging, production) - -## Agent Framework Integration +## Usage -This library provides deep integration with Microsoft Agent Framework using the `ChatAgent` pattern: +For usage examples and detailed documentation, see the [Tooling documentation](https://learn.microsoft.com/microsoft-agent-365/developer/tooling?tabs=python) on Microsoft Learn. -### MCP Tool Server Registration - -Automatically register MCP tools from all configured servers with your Agent Framework agents: - -```python -from agent_framework import ChatAgent -from agent_framework.azure import AzureOpenAIChatClient -from microsoft_agents_a365.tooling.extensions.agentframework import ( - McpToolRegistrationService, -) - -service = McpToolRegistrationService() - -# Create Azure OpenAI chat client -chat_client = AzureOpenAIChatClient( - api_key='', - endpoint='', - deployment_name='', - api_version='', -) - -# Register all MCP tools from configured servers -agent = await service.add_tool_servers_to_agent( - chat_client=chat_client, - agent_instructions="You are a helpful assistant with access to various tools.", - initial_tools=[], # Your existing tools - agentic_app_id="user-123", - auth_token="your-token" -) -``` - -### How It Works - -The `add_tool_servers_to_agent` method: - -1. **Discovers MCP Servers**: Uses the MCP server configuration service to find all configured servers -2. **Retrieves Tools**: Connects to each server and retrieves available tool definitions -3. **Combines Tools**: Merges your existing tools with the MCP tools -4. **Creates New Agent**: Returns a new `ChatAgent` instance with all tools configured - -### Agent Configuration - -Configure agents with different chat clients: - -```python -# Using Azure OpenAI (recommended) -from agent_framework.azure import AzureOpenAIChatClient - -chat_client = AzureOpenAIChatClient( - api_key='', - endpoint='', - deployment_name='', - api_version='', -) - -# Alternative: Using OpenAI directly -from agent_framework.openai import OpenAIChatClient -chat_client = OpenAIChatClient() -``` - -## Development - -### Prerequisites - -- Python 3.11 or higher -- Agent Framework Core SDK (`agent-framework-core`) -- Azure Identity (for authentication) - -### Development Setup - -1. Clone the repository -2. Install development dependencies: - ```bash - pip install -e ".[dev]" - ``` -3. Run tests: - ```bash - pytest - ``` - -### Code Style +## Support -This project uses: -- **Black** for code formatting -- **Ruff** for linting -- **MyPy** for type checking +For issues, questions, or feedback: -Run the formatter and linter: -```bash -black microsoft_agents_a365/ -ruff check microsoft_agents_a365/ -mypy microsoft_agents_a365/ -``` +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -## Contributing +## πŸ“‹ **Telemetry** -We welcome contributions! Feel free to open issues or submit pull requests to help improve this project. +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License. See the [LICENSE](https://github.com/microsoft/Agent365/blob/main/LICENSE.md) file for details. - -## Support - -For support and questions: -- File issues on [GitHub Issues](https://github.com/microsoft/Agent365/issues) -- Check the [documentation](https://github.com/microsoft/Agent365/tree/main/python) -- Join the community discussions - -## Related Libraries - -This library is part of the Microsoft Agent 365 SDK ecosystem: +Copyright (c) Microsoft Corporation. All rights reserved. -- `microsoft-agents-a365-runtime` - Core runtime and utilities -- `microsoft-agents-a365-tooling` - Base tooling framework -- `microsoft-agents-a365-tooling-extensions-openai` - OpenAI integration -- `microsoft-agents-a365-tooling-extensions-semantickernel` - Semantic Kernel integration -- `microsoft-agents-a365-observability-core` - Observability and monitoring \ No newline at end of file +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/README.md b/libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/README.md index 53016086..53fd6b21 100644 --- a/libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/README.md +++ b/libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Tooling Extensions - Azure AI Foundry -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-azureaifoundry.svg)](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-azureaifoundry) +# microsoft-agents-a365-tooling-extensions-azureaifoundry -Azure AI Foundry integration tools and MCP tool registration services for AI agent applications built with the Microsoft Agent 365 SDK. Provides specialized tooling for integrating MCP (Model Context Protocol) servers with Azure AI Foundry agents and projects. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-tooling-extensions-azureaifoundry?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-azureaifoundry) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-tooling-extensions-azureaifoundry?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-azureaifoundry) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The Azure AI Foundry tooling extensions specifically provide integration with Azure AI Foundry (Azure AI Projects and Agents), enabling seamless registration and management of MCP tool servers within the Azure AI ecosystem. - -## Key Features - -βœ… **Azure AI Foundry Integration** - Native integration with Azure AI Projects and Agents -βœ… **MCP Tool Registration** - Automatic registration of MCP servers with Azure AI Foundry agents -βœ… **Azure Identity Support** - Built-in Azure authentication with DefaultAzureCredential -βœ… **Tool Resource Management** - Comprehensive management of tool definitions and resources -βœ… **Multi-Environment Support** - Support for development and production deployment scenarios -βœ… **Enterprise Ready** - Production-grade tooling for Azure-based agent deployments +Azure AI Foundry specific tools and services for AI agent development. Provides MCP (Model Context Protocol) tool registration service for dynamically adding MCP servers to Azure AI Foundry agents. ## Installation @@ -22,154 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-tooling-extensions-azureaifoundry ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Azure AI Foundry Tooling Extensions enable seamless integration between MCP tool servers and Azure AI Foundry agents. Key concepts include: - -- **MCP Tool Registration**: Automatic registration of MCP servers with Azure AI Foundry agents -- **Azure AI Projects Integration**: Native integration with Azure AI Projects and project clients -- **Tool Resource Management**: Management of tool definitions, resources, and configurations -- **Azure Identity Integration**: Seamless authentication using Azure DefaultAzureCredential - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-tooling-extensions-azureaifoundry` -2. Configure Azure credentials and project settings -3. Use the MCP tool registration service to add tools to your agents -4. Deploy and manage your Azure AI Foundry agents with MCP capabilities - -### Basic Usage - -```python -from microsoft_agents_a365.tooling.extensions.azureaifoundry import McpToolRegistrationService -from azure.ai.projects import AIProjectClient -from azure.identity import DefaultAzureCredential - -# Create Azure AI Project client -credential = DefaultAzureCredential() -project_client = AIProjectClient( - credential=credential, - endpoint="your-project-endpoint", - subscription_id="your-subscription-id", - resource_group_name="your-resource-group", - project_name="your-project-name" -) - -# Create MCP tool registration service -registration_service = McpToolRegistrationService() - -# Add MCP tool servers to your Azure AI Foundry agent -await registration_service.add_tool_servers_to_agent( - project_client=project_client, - agent_id="your-agent-id", - auth_token="your-auth-token" -) -``` - -## Core Azure AI Foundry Components - -| Component | Purpose | Description | -|-----------|---------|-------------| -| **McpToolRegistrationService** | Tool Registration | Register MCP servers with Azure AI Foundry agents | -| **Azure Identity Integration** | Authentication | Seamless Azure authentication and credential management | -| **Tool Resource Management** | Resource Management | Manage tool definitions and resources in Azure AI Foundry | -| **Project Client Integration** | Azure Integration | Native integration with Azure AI Projects and clients | - -## Supported Azure AI Foundry Features - -| Feature | Component | Description | -|---------|-----------|-------------| -| **Agent Tool Registration** | MCP server integration | Add MCP tool servers to Azure AI Foundry agents | -| **Azure Authentication** | Identity management | Azure DefaultAzureCredential integration | -| **Project Integration** | Azure AI Projects | Native integration with Azure AI project clients | -| **Resource Management** | Tool resources | Manage tool definitions and configurations | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Tooling documentation](https://learn.microsoft.com/microsoft-agent-365/developer/tooling?tabs=python) on Microsoft Learn. -### Azure AI Foundry Integration +## Support -- **Agent Configuration**: Register MCP tools with existing Azure AI Foundry agents -- **Project Management**: Integration with Azure AI Projects for centralized management -- **Resource Allocation**: Automatic tool resource allocation and configuration -- **Environment Management**: Support for multiple deployment environments +For issues, questions, or feedback: -### MCP Tool Registration +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -The service provides comprehensive MCP tool registration capabilities: -- Automatic discovery of available MCP tool servers -- Registration with Azure AI Foundry agent infrastructure -- Tool resource management and configuration -- Support for both development and production scenarios +## πŸ“‹ **Telemetry** -## Architecture - -The Azure AI Foundry extensions follow a service-oriented architecture: - -- **Registration Layer**: MCP tool registration and management services -- **Azure Integration Layer**: Native Azure AI Foundry and identity integration -- **Resource Management Layer**: Tool definition and resource management -- **Configuration Layer**: Environment-specific configuration and settings - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-tooling` | Core tooling utilities and MCP server configuration | -| `microsoft-agents-a365-runtime` | Runtime utilities and environment management | -| `microsoft-agents-a365-observability-core` | Observability and monitoring for Azure deployments | -| `microsoft-agents-a365-hosting-core` | Agent hosting and middleware services | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Azure AI Foundry Agent** | Basic agent with MCP tool integration | `samples/azure-foundry-agent/` | -| **Multi-Tool Agent** | Agent with multiple MCP tool servers | `samples/multi-tool-azure-agent/` | -| **Enterprise Azure Deployment** | Production-ready Azure AI Foundry deployment | `samples/enterprise-azure-deployment/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `microsoft-agents-a365-tooling >= 0.1.0` - - `azure-ai-projects >= 1.0.0` - - `azure-ai-agents >= 1.1.0b4` - - `azure-identity >= 1.12.0` - -## Common Use Cases - -### Azure AI Foundry Development -- Register MCP tool servers with Azure AI Foundry agents -- Integrate with Azure AI Projects for centralized agent management -- Leverage Azure identity for secure authentication and authorization -- Deploy agents with comprehensive tooling capabilities - -### Enterprise Azure Deployment -- Manage MCP tool registration across multiple Azure environments -- Integrate with existing Azure infrastructure and identity systems -- Support multi-tenant deployments with Azure AI Foundry -- Enable enterprise-scale agent deployments with Azure tooling - -### Development and Testing -- Test MCP tool integration in Azure AI Foundry environments -- Validate agent configurations with Azure AI Projects -- Support development workflows with Azure tooling integration -- Enable debugging and monitoring with Azure observability - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -☁️ [Azure AI Foundry Documentation](https://learn.microsoft.com/azure/ai-studio/) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-tooling-extensions-openai/README.md b/libraries/microsoft-agents-a365-tooling-extensions-openai/README.md index 768de3f0..a242cb0a 100644 --- a/libraries/microsoft-agents-a365-tooling-extensions-openai/README.md +++ b/libraries/microsoft-agents-a365-tooling-extensions-openai/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Tooling Extensions - OpenAI -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-openai.svg)](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-openai) +# microsoft-agents-a365-tooling-extensions-openai -OpenAI Agents SDK integration tools and MCP tool registration services for AI agent applications built with the Microsoft Agent 365 SDK. Provides specialized tooling for integrating MCP (Model Context Protocol) servers with OpenAI Agents SDK applications. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-tooling-extensions-openai?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-openai) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-tooling-extensions-openai?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-openai) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The OpenAI tooling extensions specifically provide integration with the OpenAI Agents SDK, enabling seamless registration and management of MCP tool servers within OpenAI-based agent applications. - -## Key Features - -βœ… **OpenAI Agents SDK Integration** - Native integration with OpenAI Agents SDK and framework -βœ… **MCP Tool Registration** - Automatic registration of MCP servers with OpenAI agents -βœ… **Multiple Server Types** - Support for hosted, streamable HTTP, SSE, and stdio MCP servers -βœ… **Dynamic Tool Management** - Runtime addition and management of MCP tool servers -βœ… **Authentication Integration** - Seamless integration with Microsoft Agent 365 authentication -βœ… **Enterprise Ready** - Production-grade tooling for OpenAI-based agent deployments +OpenAI Agents SDK specific tools and services for AI agent development. Provides MCP (Model Context Protocol) tool registration service for dynamically adding MCP servers to OpenAI Agents SDK-based agents. ## Installation @@ -22,145 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-tooling-extensions-openai ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 OpenAI Tooling Extensions enable seamless integration between MCP tool servers and OpenAI Agents SDK applications. Key concepts include: - -- **MCP Tool Registration**: Automatic registration of MCP servers with OpenAI agents -- **OpenAI Agents Integration**: Native integration with OpenAI Agents SDK framework -- **Multiple Server Types**: Support for various MCP server deployment types -- **Dynamic Tool Management**: Runtime management of tool servers and configurations - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-tooling-extensions-openai` -2. Configure your OpenAI agent application with MCP support -3. Use the MCP tool registration service to add tools to your agents -4. Deploy and manage your OpenAI agents with MCP capabilities - -### Basic Usage - -```python -from microsoft_agents_a365.tooling.extensions.openai import McpToolRegistrationService -from agents import Agent -from microsoft_agents.hosting.core import Authorization, TurnContext - -# Create MCP tool registration service -registration_service = McpToolRegistrationService() - -# Add MCP tool servers to your OpenAI agent -await registration_service.add_tool_servers_to_agent( - agent=your_openai_agent, - agentic_app_id="user-123", - auth=authorization_context, - context=turn_context, - auth_token="your-auth-token" -) -``` - -## Core OpenAI Integration Components - -| Component | Purpose | Description | -|-----------|---------|-------------| -| **McpToolRegistrationService** | Tool Registration | Register MCP servers with OpenAI Agents SDK applications | -| **MCPServerInfo** | Server Configuration | Configuration model for MCP server information and settings | -| **Multiple Server Types** | Server Support | Support for hosted, streamable HTTP, SSE, and stdio servers | -| **Authentication Integration** | Security | Integration with Microsoft Agent 365 authentication systems | - -## Supported MCP Server Types - -| Server Type | Component | Description | -|-------------|-----------|-------------| -| **Hosted** | MCPServerHosted | Fully hosted MCP servers with remote endpoints | -| **Streamable HTTP** | MCPServerStreamableHttp | HTTP-based streaming MCP servers | -| **Server-Sent Events** | MCPServerSSE | SSE-based real-time MCP servers | -| **Standard I/O** | MCPServerStdio | Process-based MCP servers using stdio communication | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Tooling documentation](https://learn.microsoft.com/microsoft-agent-365/developer/tooling?tabs=python) on Microsoft Learn. -### OpenAI Agents Integration +## Support -- **Agent Configuration**: Register MCP tools with existing OpenAI Agents SDK applications -- **Dynamic Tool Addition**: Runtime addition of MCP tool servers to active agents -- **Server Type Selection**: Choose appropriate MCP server types for different scenarios -- **Authentication Flow**: Seamless integration with Microsoft Agent 365 authentication +For issues, questions, or feedback: -### MCP Tool Management +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -The service provides comprehensive MCP tool management capabilities: -- Automatic discovery of available MCP tool servers -- Registration with OpenAI Agents SDK framework -- Support for multiple concurrent MCP server types -- Runtime management of tool server configurations +## πŸ“‹ **Telemetry** -## Architecture - -The OpenAI tooling extensions follow a service-oriented architecture: - -- **Registration Layer**: MCP tool registration and management services -- **OpenAI Integration Layer**: Native OpenAI Agents SDK integration and compatibility -- **Server Management Layer**: Multi-type MCP server support and configuration -- **Authentication Layer**: Microsoft Agent 365 authentication and authorization - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-tooling` | Core tooling utilities and MCP server configuration | -| `microsoft-agents-a365-runtime` | Runtime utilities and environment management | -| `microsoft-agents-a365-hosting-core` | Agent hosting and middleware services | -| `microsoft-agents-a365-observability-extensions-openai` | OpenAI observability and monitoring | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **OpenAI MCP Agent** | Basic OpenAI agent with MCP tool integration | `samples/openai-mcp-agent/` | -| **Multi-Tool OpenAI Agent** | Agent with multiple MCP server types | `samples/multi-tool-openai-agent/` | -| **Enterprise OpenAI Deployment** | Production-ready OpenAI agent deployment | `samples/enterprise-openai-deployment/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `microsoft-agents-a365-tooling >= 0.1.0` - - `openai-agents` - - `asyncio-throttle` - -## Common Use Cases - -### OpenAI Agents Development -- Register MCP tool servers with OpenAI Agents SDK applications -- Integrate with existing OpenAI agent workflows and frameworks -- Leverage Microsoft Agent 365 tooling infrastructure with OpenAI agents -- Deploy agents with comprehensive MCP tooling capabilities - -### Enterprise OpenAI Deployment -- Manage MCP tool registration across multiple OpenAI environments -- Integrate with existing Microsoft Agent 365 infrastructure -- Support multi-tenant deployments with OpenAI Agents SDK -- Enable enterprise-scale agent deployments with OpenAI tooling - -### Development and Testing -- Test MCP tool integration with OpenAI Agents SDK -- Validate agent configurations with various MCP server types -- Support development workflows with OpenAI tooling integration -- Enable debugging and monitoring with OpenAI observability - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -πŸ€– [OpenAI Agents Documentation](https://platform.openai.com/docs/assistants/overview) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-tooling-extensions-semantickernel/README.md b/libraries/microsoft-agents-a365-tooling-extensions-semantickernel/README.md index fb7f680b..b2ca5524 100644 --- a/libraries/microsoft-agents-a365-tooling-extensions-semantickernel/README.md +++ b/libraries/microsoft-agents-a365-tooling-extensions-semantickernel/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Tooling Extensions - Semantic Kernel -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-semantickernel.svg)](https://badge.fury.io/py/microsoft-agents-a365-tooling-extensions-semantickernel) +# microsoft-agents-a365-tooling-extensions-semantickernel -Microsoft Semantic Kernel integration tools and MCP tool registration services for AI agent applications built with the Microsoft Agent 365 SDK. Provides specialized tooling for integrating MCP (Model Context Protocol) servers with Semantic Kernel-based agent applications. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-tooling-extensions-semantickernel?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-semantickernel) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-tooling-extensions-semantickernel?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling-extensions-semantickernel) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The Semantic Kernel tooling extensions specifically provide integration with the Microsoft Semantic Kernel framework, enabling seamless registration and management of MCP tool servers within Semantic Kernel-based agent applications. - -## Key Features - -βœ… **Semantic Kernel Integration** - Native integration with Microsoft Semantic Kernel framework -βœ… **MCP Tool Registration** - Automatic registration of MCP servers with Semantic Kernel agents -βœ… **Plugin Management** - Seamless integration with Semantic Kernel's plugin architecture -βœ… **Streamable HTTP Support** - Built-in support for MCP streamable HTTP plugins -βœ… **Kernel Function Integration** - Integration with Semantic Kernel's function calling system -βœ… **Enterprise Ready** - Production-grade tooling for Semantic Kernel-based agent deployments +Semantic Kernel specific tools and services for AI agent development. Provides MCP (Model Context Protocol) tool registration service for dynamically adding MCP servers to Semantic Kernel-based agents. ## Installation @@ -22,145 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-tooling-extensions-semantickernel ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Semantic Kernel Tooling Extensions enable seamless integration between MCP tool servers and Semantic Kernel applications. Key concepts include: - -- **MCP Tool Registration**: Automatic registration of MCP servers with Semantic Kernel agents -- **Semantic Kernel Integration**: Native integration with Semantic Kernel framework and plugins -- **Plugin Architecture**: Leverage Semantic Kernel's plugin system for MCP server integration -- **Kernel Function Support**: Integration with Semantic Kernel's function calling capabilities - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-tooling-extensions-semantickernel` -2. Configure your Semantic Kernel application with MCP support -3. Use the MCP tool registration service to add tools to your kernel -4. Deploy and manage your Semantic Kernel agents with MCP capabilities - -### Basic Usage - -```python -from microsoft_agents_a365.tooling.extensions.semantickernel import McpToolRegistrationService -from semantic_kernel import Kernel - -# Create Semantic Kernel instance -kernel = Kernel() - -# Create MCP tool registration service -registration_service = McpToolRegistrationService() - -# Add MCP tool servers to your Semantic Kernel -await registration_service.add_tool_servers_to_kernel( - kernel=kernel, - agentic_app_id="user-123", - auth_token="your-auth-token" -) -``` - -## Core Semantic Kernel Integration Components - -| Component | Purpose | Description | -|-----------|---------|-------------| -| **McpToolRegistrationService** | Tool Registration | Register MCP servers with Semantic Kernel applications | -| **MCPStreamableHttpPlugin** | Plugin Integration | Semantic Kernel plugin for MCP streamable HTTP servers | -| **Kernel Function Support** | Function Integration | Integration with Semantic Kernel's function calling system | -| **Configuration Management** | Setup Management | Configuration and setup of MCP tools within Semantic Kernel | - -## Supported Semantic Kernel Features - -| Feature | Component | Description | -|---------|-----------|-------------| -| **Plugin Architecture** | MCP plugin integration | Leverage Semantic Kernel's plugin system for MCP servers | -| **Function Calling** | Kernel functions | Integration with Semantic Kernel's function calling capabilities | -| **Streamable HTTP** | MCPStreamableHttpPlugin | Support for MCP streamable HTTP server integration | -| **Tool Registration** | Dynamic registration | Runtime registration of MCP tools with Semantic Kernel | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Tooling documentation](https://learn.microsoft.com/microsoft-agent-365/developer/tooling?tabs=python) on Microsoft Learn. -### Semantic Kernel Integration +## Support -- **Plugin Registration**: Register MCP tools as Semantic Kernel plugins -- **Kernel Function Integration**: Seamless integration with Semantic Kernel's function system -- **Dynamic Tool Addition**: Runtime addition of MCP tool servers to active kernels -- **Configuration Management**: Centralized configuration of MCP tools within Semantic Kernel +For issues, questions, or feedback: -### MCP Tool Management +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -The service provides comprehensive MCP tool management capabilities: -- Automatic discovery of available MCP tool servers -- Registration with Semantic Kernel's plugin architecture -- Integration with Semantic Kernel's function calling system -- Support for streamable HTTP MCP server types +## πŸ“‹ **Telemetry** -## Architecture - -The Semantic Kernel tooling extensions follow a plugin-oriented architecture: - -- **Registration Layer**: MCP tool registration and management services -- **Semantic Kernel Integration Layer**: Native Semantic Kernel framework integration -- **Plugin Management Layer**: Semantic Kernel plugin system integration -- **Function Integration Layer**: Kernel function calling system support - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-tooling` | Core tooling utilities and MCP server configuration | -| `microsoft-agents-a365-runtime` | Runtime utilities and environment management | -| `microsoft-agents-a365-observability-extensions-semantickernel` | Semantic Kernel observability and monitoring | -| `microsoft-agents-a365-hosting-core` | Agent hosting and middleware services | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **Semantic Kernel MCP Agent** | Basic Semantic Kernel agent with MCP tools | `samples/semantic-kernel-mcp-agent/` | -| **Multi-Plugin SK Agent** | Agent with multiple MCP plugins | `samples/multi-plugin-sk-agent/` | -| **Enterprise SK Deployment** | Production-ready Semantic Kernel deployment | `samples/enterprise-sk-deployment/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `microsoft-agents-a365-tooling >= 0.1.0` - - `semantic-kernel >= 1.0.0` - - `aiohttp >= 3.8.0` - -## Common Use Cases - -### Semantic Kernel Development -- Register MCP tool servers with Semantic Kernel applications -- Integrate with existing Semantic Kernel workflows and plugins -- Leverage Microsoft Agent 365 tooling infrastructure with Semantic Kernel -- Deploy agents with comprehensive MCP tooling capabilities - -### Enterprise Semantic Kernel Deployment -- Manage MCP tool registration across multiple Semantic Kernel environments -- Integrate with existing Microsoft Agent 365 infrastructure -- Support multi-tenant deployments with Semantic Kernel framework -- Enable enterprise-scale agent deployments with Semantic Kernel tooling - -### Development and Testing -- Test MCP tool integration with Semantic Kernel framework -- Validate agent configurations with Semantic Kernel plugins -- Support development workflows with Semantic Kernel tooling integration -- Enable debugging and monitoring with Semantic Kernel observability - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -🧠 [Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. diff --git a/libraries/microsoft-agents-a365-tooling/README.md b/libraries/microsoft-agents-a365-tooling/README.md index 8fa32db2..5c80dd90 100644 --- a/libraries/microsoft-agents-a365-tooling/README.md +++ b/libraries/microsoft-agents-a365-tooling/README.md @@ -1,20 +1,9 @@ -# Microsoft Agent 365 Tooling -[![PyPI version](https://badge.fury.io/py/microsoft-agents-a365-tooling.svg)](https://badge.fury.io/py/microsoft-agents-a365-tooling) +# microsoft-agents-a365-tooling -Cross-framework utilities and shared components for AI agent tooling built with the Microsoft Agent 365 SDK. Provides core tooling functionality including MCP (Model Context Protocol) server configuration, utilities, and services shared across different AI frameworks. +[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-tooling?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling) +[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-tooling?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-tooling) -## What is this? - -This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive framework for building enterprise-grade conversational AI agents. The tooling package provides core utilities, configuration management, and services that are shared across different AI framework integrations, enabling consistent tooling experiences across the entire SDK ecosystem. - -## Key Features - -βœ… **MCP Server Configuration** - Comprehensive Model Context Protocol server configuration management -βœ… **Cross-Framework Utilities** - Shared utilities that work across different AI frameworks -βœ… **Tooling Gateway Integration** - Built-in integration with Microsoft Agent 365 tooling gateway -βœ… **Configuration Services** - Centralized configuration management for MCP tool servers -βœ… **URL Generation** - Automatic MCP server URL generation and endpoint management -βœ… **Enterprise Ready** - Production-grade tooling infrastructure for large-scale deployments +Core tooling functionality for MCP (Model Context Protocol) tool server management in applications built with the Microsoft Agent 365 SDK. This package provides the foundation for discovering, registering, and managing tool servers across different AI frameworks. ## Installation @@ -22,147 +11,27 @@ This library is part of the Microsoft Agent 365 SDK for Python - a comprehensive pip install microsoft-agents-a365-tooling ``` -## Quick Start - -### Basic Concepts - -The Microsoft Agent 365 Tooling package provides foundational utilities for managing and configuring AI agent tooling. Key concepts include: - -- **MCP Server Configuration**: Structured configuration for Model Context Protocol servers -- **Tooling Gateway**: Centralized gateway for managing agent tools and services -- **Configuration Services**: Services for managing and retrieving tool configurations -- **Cross-Framework Compatibility**: Utilities that work across different AI frameworks - -### Getting Started - -1. Install the package: `pip install microsoft-agents-a365-tooling` -2. Import the tooling utilities in your agent application -3. Configure MCP servers and tooling gateway integration -4. Use shared utilities across your AI framework implementations - -### Basic Usage - -```python -from microsoft_agents_a365.tooling import ( - MCPServerConfig, - McpToolServerConfigurationService, - build_mcp_server_url -) - -# Configure MCP server -mcp_config = MCPServerConfig( - mcp_server_name="my-tool-server", - mcp_server_unique_name="my-unique-server-id" -) - -# Use configuration service to list available MCP servers -config_service = McpToolServerConfigurationService() -mcp_servers = await config_service.list_tool_servers( - agentic_app_id="agent-123", - auth_token="your-auth-token" -) -``` - -## Core Tooling Components - -| Component | Purpose | Description | -|-----------|---------|-------------| -| **MCPServerConfig** | Configuration Model | Structured configuration for MCP server instances | -| **McpToolServerConfigurationService** | Configuration Service | Service for managing MCP tool server configurations | -| **Utility Functions** | Helper Functions | URL generation, gateway resolution, and common utilities | -| **Constants** | Configuration Constants | Shared constants used across tooling components | - -## Supported Tooling Features - -| Feature | Component | Description | -|---------|-----------|-------------| -| **MCP Server Management** | Configuration and URL generation | Manage Model Context Protocol server configurations | -| **Tooling Gateway** | Gateway integration utilities | Connect to Microsoft Agent 365 tooling gateway | -| **Cross-Framework Support** | Shared utilities | Common functionality across AI frameworks | -| **Configuration Management** | Centralized configuration | Manage tool configurations and settings | +## Usage -## Advanced Usage +For usage examples and detailed documentation, see the [Tooling documentation](https://learn.microsoft.com/microsoft-agent-365/developer/tooling?tabs=python) on Microsoft Learn. -### MCP Server Configuration +## Support -- **Server Registration**: Register and configure MCP servers with unique identifiers -- **URL Generation**: Automatic generation of MCP server endpoints and URLs -- **Configuration Validation**: Built-in validation for server configuration parameters -- **Service Discovery**: Discover and connect to configured MCP servers +For issues, questions, or feedback: -### Tooling Gateway Integration +- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section +- See the [main documentation](../../../README.md) for more information -The tooling package provides seamless integration with the Microsoft Agent 365 tooling gateway: -- Digital worker endpoint resolution -- MCP base URL configuration -- Gateway service discovery -- Cross-framework tool coordination +## πŸ“‹ **Telemetry** -## Architecture - -The tooling package follows a service-oriented architecture: - -- **Models Layer**: Data models for configuration and server definitions -- **Services Layer**: Configuration services and management functionality -- **Utils Layer**: Shared utilities and helper functions -- **Integration Layer**: Cross-framework compatibility and gateway integration - -## Integration with Microsoft Agent 365 SDK - -This package works seamlessly with other Microsoft Agent 365 SDK components: - -| Package | Integration | -|---------|-------------| -| `microsoft-agents-a365-tooling-extensions-azureaifoundry` | Azure AI Foundry-specific tooling extensions | -| `microsoft-agents-a365-tooling-extensions-openai` | OpenAI-specific tooling integrations | -| `microsoft-agents-a365-tooling-extensions-semantickernel` | Semantic Kernel tooling extensions | -| `microsoft-agents-a365-runtime` | Runtime utilities and environment management | - -## Sample Applications - -Check out these working examples: - -| Sample | Description | Location | -|--------|-------------|----------| -| **MCP Server Setup** | Basic MCP server configuration and management | `samples/mcp-server-setup/` | -| **Multi-Framework Tooling** | Tooling utilities across different AI frameworks | `samples/multi-framework-tooling/` | -| **Gateway Integration** | Integration with Microsoft Agent 365 tooling gateway | `samples/gateway-integration/` | - -## Requirements - -- **Python**: 3.11+ -- **Dependencies**: - - `pydantic >= 2.0.0` - - `typing-extensions >= 4.0.0` - -## Common Use Cases - -### Framework Integration -- Configure MCP servers for different AI frameworks -- Manage tool configurations across multiple framework implementations -- Provide consistent tooling experiences across AI frameworks -- Enable cross-framework tool sharing and coordination - -### Enterprise Deployment -- Centralize tool configuration management across multiple agents -- Integrate with existing enterprise tooling infrastructure -- Manage MCP server deployments at scale -- Support multi-tenant tooling configurations - -### Development and Testing -- Provide shared utilities for development across different frameworks -- Enable consistent configuration patterns across development teams -- Support testing with standardized tool configurations -- Facilitate debugging with unified tooling utilities - -## Quick Links - -πŸ“¦ [All SDK Packages on PyPI](TODO: Update when packages are published) -πŸ“– [Complete Documentation](https://github.com/microsoft/Agent365/tree/main/python) -πŸ’‘ [Python Samples Repository](https://github.com/microsoft/Agent365/tree/main/samples) -πŸ› [Report Issues](https://github.com/microsoft/Agent365/issues) -πŸ”§ [Model Context Protocol Specification](https://modelcontextprotocol.io/) +Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +## Trademarks + +*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Copyright (c) Microsoft Corporation. All rights reserved. + +Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. \ No newline at end of file