diff --git a/README.md b/README.md index 00652613..660501ec 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,64 @@ -# Agent 365 SDK Samples +# Microsoft Agent 365 SDK Samples and Prompts +This repository contains sample agents and prompts for building with the Microsoft Agent 365 SDK. The Microsoft Agent 365 SDK extends the Microsoft 365 Agents SDK with enterprise-grade capabilities for building sophisticated agents. It 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. +- **Sample agents** are available in C# (.NET), Python, and Node.js/TypeScript +- **Prompts** to help you get started with AI-powered development tools like Cursor IDE -## 📋 **Telemetry** +> #### 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/en-us/microsoft-agent-365/developer/). -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. +## Current Repository State + +This samples repository is currently in active development and contains: +- **Sample Agents**: Production-ready examples in C#/.NET, Python, and Node.js/TypeScript demonstrating observability, notifications, tooling, and hosting patterns +- **Prompts**: Guides for using AI-powered development tools (e.g., Cursor IDE) to accelerate agent development + +## Documentation + +For comprehensive documentation and guides, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). + +### Microsoft Agent 365 SDK + +The sample agents in this repository use the Microsoft Agent 365 SDK, which provides enterprise-grade extensions for observability, notifications, runtime utilities, and developer tools. Explore the SDK repositories below: + +- [Microsoft Agent 365 SDK - C# /.NET repository](https://github.com/microsoft/Agent365-dotnet) +- [Microsoft Agent 365 SDK - Python repository](https://github.com/microsoft/Agent365-python) +- [Microsoft Agent 365 SDK - Node.js/TypeScript repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft Agent 365 SDK Samples repository](https://github.com/microsoft/Agent365-Samples) - You are here + +## 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 https://cla.opensource.microsoft.com. + +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. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments. + +## Useful Links + +### Microsoft 365 Agents SDK + +The core SDK for building conversational AI agents for Microsoft 365 platforms. + +- [Microsoft 365 Agents SDK - C# /.NET repository](https://github.com/Microsoft/Agents-for-net) +- [Microsoft 365 Agents SDK - NodeJS /TypeScript repository](https://github.com/Microsoft/Agents-for-js) +- [Microsoft 365 Agents SDK - Python repository](https://github.com/Microsoft/Agents-for-python) +- [Microsoft 365 Agents documentation](https://learn.microsoft.com/microsoft-365/agents-sdk/) + +## Additional Resources + +For language-specific documentation and additional resources, explore the following links: + +- [.NET documentation](https://learn.microsoft.com/dotnet/api/?view=m365-agents-sdk&preserve-view=true) +- [Node.js documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) +- [Python documentation](https://learn.microsoft.com/python/api/?view=m365-agents-sdk&preserve-view=true) ## 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 file for details. \ No newline at end of file diff --git a/dotnet/semantic-kernel/sample-agent/README.md b/dotnet/semantic-kernel/sample-agent/README.md index d2437e59..971a452c 100644 --- a/dotnet/semantic-kernel/sample-agent/README.md +++ b/dotnet/semantic-kernel/sample-agent/README.md @@ -1,172 +1,58 @@ -# Agent 365 Sample Agent - .NET Semantic Kernel +# Semantic Kernel Sample Agent - C#/.NET -This directory contains a sample agent implementation using .NET and Semantic Kernel, hosted on an ASP.NET Core web service. This agent will handle multiple "turns" to get the required information from the user. +This sample demonstrates how to build an agent using Semantic Kernel in C#/.NET with the Microsoft Agent 365 SDK. It covers: -This Agent Sample is intended to introduce you to the basics of integrating Agent 365 and Semantic Kernel with the Microsoft 365 Agents SDK in order to build powerful Agents. It can also be used as the base for a custom Agent that you choose to develop. +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -## Demonstrates +This sample uses the [Microsoft Agent 365 SDK for .NET](https://github.com/microsoft/Agent365-dotnet). -This sample demonstrates how to build an agent using the Agent 365 framework with .NET and Semantic Kernel. It shows the three key Agent 365 concepts; Notifications, Observability, and Tooling, and shows how by combining these concepts, powerful scenarios can be unlocked. +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- [.NET 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)+ -- Azure OpenAI or OpenAI API key -- Optional: [Microsoft 365 Agents Playground](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/test-with-toolkit-project) -- Optional: [dev tunnel](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started) - -## How to run this sample - -### Configuration - -1. You will need an Azure OpenAI or OpenAI resource using, e.g., model `gpt-4o-mini` -2. Configure OpenAI in `appsettings.json` - ```json - "AIServices": { - "AzureOpenAI": { - "DeploymentName": "", // This is the Deployment (as opposed to model) Name of the Azure OpenAI model - "Endpoint": "", // This is the Endpoint of the Azure OpenAI model deployment - "ApiKey": "" // This is the API Key of the Azure OpenAI model deployment - }, - "OpenAI": { - "ModelId": "", // This is the Model ID of the OpenAI model - "ApiKey": "" // This is the API Key of the OpenAI model - }, - "UseAzureOpenAI": true // This is a flag to determine whether to use the Azure OpenAI model or the OpenAI model - } - ``` -3. For information on how to create an Azure OpenAI deployment, see [Create and deploy an Azure OpenAI in Azure AI Foundry Models resource](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/create-resource?pivots=web-portal). -4. Verify the local development settings in `Properties/launchSettings.json` are configured for your environment. - -### Run using Microsoft 365 Agents Playground - -1. If you haven't done so already, install the Agents Playground: - ```bash - winget install agentsplayground - ``` -2. Start the agent in Visual Studio or VS Code in debug mode -3. Start Agents Playground at a command prompt: - ```bash - agentsplayground - ``` - The tool will open a web browser showing the Microsoft 365 Agents Playground, ready to send messages to your agent. -4. Interact with the agent via the browser - - -### Run using WebChat or Teams - -**Overview of running and testing an agent:** -- Provision an Azure Bot in your Azure Subscription -- Configure your agent settings to use the desired authentication type -- Run an instance of the agent app (either locally or deployed to Azure) -- Test in a client - -#### Setup - -1. Create an Azure Bot with one of these authentication types - - [SingleTenant, Client Secret](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-single-secret) - - [SingleTenant, Federated Credentials](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-federated-credentials) - - [User Assigned Managed Identity](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-managed-identity) - - > **Note:** Be sure to follow the **Next Steps** at the end of these docs to configure your agent settings. - - > **IMPORTANT:** If you want to run your agent locally via devtunnels, the only supported auth type is Client Secrets and Certificates. - -2. Running the agent - - **Option A: Run the agent locally** - - - Requires a tunneling tool to allow for local development and debugging when connected to an external client such as Microsoft Teams. - - **For Client Secret or Certificate authentication types only.** Federated Credentials and Managed Identity will not work via a tunnel to a local agent and must be deployed to an App Service or container. - - Steps: - 1. Run `dev tunnels`. Follow [Create and host a dev tunnel](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started?tabs=windows) and host the tunnel with anonymous user access as shown below: - ```bash - devtunnel host -p 3978 --allow-anonymous - ``` - 2. On the Azure Bot, select **Settings**, then **Configuration**, and update the **Messaging endpoint** to `{tunnel-url}/api/messages` - 3. Start the agent in Visual Studio - - **Option B: Deploy agent code to Azure** - - 1. Deploy using Visual Studio Publish or any tool used to deploy web applications. - 2. On the Azure Bot, select **Settings**, then **Configuration**, and update the **Messaging endpoint** to `https://{{appServiceDomain}}/api/messages` - -#### Testing this agent with WebChat - -1. Select **Test in WebChat** on the Azure Bot resource in the Azure portal - -#### Testing this agent in Teams or Microsoft 365 - -1. Update the `manifest.json` file: - - Edit the `manifest.json` file in the `appManifest` folder - - Replace `<>` with your AppId (created above) *everywhere* it appears - - Replace `<>` with your agent URL (for example, the tunnel host name) - - Zip the contents of the `appManifest` folder to create `manifest.zip` (include all three files): - - `manifest.json` - - `outline.png` - - `color.png` -2. Ensure your Azure Bot has the **Microsoft Teams** channel added under **Channels**. -3. Navigate to the Microsoft 365 admin center. Under **Settings** and **Integrated Apps**, select **Upload Custom App**. -4. Select the `manifest.zip` file created in the previous step. -5. After a short period, the agent will appear in Microsoft Teams and Microsoft 365 Copilot. - -#### Enabling JWT token validation - -1. By default, ASP.NET token validation is disabled to support local debugging. -2. Enable it by updating `appsettings.json`: - ```json - "TokenValidation": { - "Enabled": true, - "Audiences": [ - "{{ClientId}}" // This is the Client ID used for the Azure Bot - ], - "TenantId": "{{TenantId}}" - }, - ``` - -### Developing the agent / Understanding the code - -- See the [Agent Code Walkthrough](./Agent-Code-Walkthrough.md) for a detailed explanation of the code. - -### Troubleshooting - -#### Missing OpenAI key in appsettings.json - - - **Error when project is run through Visual Studio** - - When the project is run through Visual Studio, the following error occurs: - ``` - System.ArgumentException: 'The value cannot be an empty string or composed entirely of whitespace. (Parameter 'endpoint')' - ``` - The exception has call stack: - ``` - > System.Private.CoreLib.dll!System.ArgumentException.ThrowNullOrWhiteSpaceException(string argument, string paramName) Line 113 C# - System.Private.CoreLib.dll!System.ArgumentException.ThrowIfNullOrWhiteSpace(string argument, string paramName) Line 98 C# - Microsoft.SemanticKernel.Connectors.OpenAI.dll!Microsoft.SemanticKernel.Verify.NotNullOrWhiteSpace(string str, string paramName) Line 38 C# - Microsoft.SemanticKernel.Connectors.AzureOpenAI.dll!Microsoft.SemanticKernel.AzureOpenAIServiceCollectionExtensions.AddAzureOpenAIChatCompletion(Microsoft.Extensions.DependencyInjection.IServiceCollection services, string deploymentName, string endpoint, string apiKey, string serviceId, string modelId, string apiVersion, System.Net.Http.HttpClient httpClient) Line 30 C# - SemanticKernelSampleAgent.dll!Program.
$(string[] args) Line 33 C# - ``` - - - **Error when project is run through command line** - - When the project is run through the the command line: - ```bash - dotnet run - ``` - The following error occurs: - ``` - C:\Agent365-Samples\dotnet\semantic-kernel\sample-agent\MyAgent.cs(145,48): warning CS8602: Dereference of a possibly null reference. - Unhandled exception. System.ArgumentException: The value cannot be an empty string or composed entirely of whitespace. (Parameter 'endpoint') - at System.ArgumentException.ThrowNullOrWhiteSpaceException(String argument, String paramName) - at System.ArgumentException.ThrowIfNullOrWhiteSpace(String argument, String paramName) - at Microsoft.SemanticKernel.AzureOpenAIServiceCollectionExtensions.AddAzureOpenAIChatCompletion(IServiceCollection services, String deploymentName, String endpoint, String apiKey, String serviceId, String modelId, String apiVersion, HttpClient httpClient) - at Program.
$(String[] args) in C:\Agent365-samples\dotnet\semantic-kernel\sample-agent\Program.cs:line 33 - ``` - - - **Solution** - - Configure the OpenAI or Azure OpenAI settings in `appsettings.json` as described in the [Configuration](#configuration) section above. - -## Further reading -To learn more about Agent 365, see [Agent 365](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/). +- .NET 8.0 or higher +- Microsoft Agent 365 SDK +- Semantic Kernel 1.66.0 or higher +- Azure/OpenAI API credentials + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=dotnet) guide for complete instructions. + +For a detailed explanation of the agent code and implementation, see the [Agent Code Walkthrough](Agent-Code-Walkthrough.md). + +## Support + +For issues, questions, or feedback: + +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-dotnet/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/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. + +## Additional Resources + +- [Microsoft Agent 365 SDK - .NET repository](https://github.com/microsoft/Agent365-dotnet) +- [Microsoft 365 Agents SDK - .NET repository](https://github.com/Microsoft/Agents-for-net) +- [Semantic Kernel documentation](https://learn.microsoft.com/semantic-kernel/) +- [.NET API documentation](https://learn.microsoft.com/dotnet/api/?view=m365-agents-sdk&preserve-view=true) + +## 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/nodejs/claude/sample-agent/README.md b/nodejs/claude/sample-agent/README.md index fede5f75..7915f6b3 100644 --- a/nodejs/claude/sample-agent/README.md +++ b/nodejs/claude/sample-agent/README.md @@ -1,75 +1,56 @@ -# Sample Agent - Node.js Claude +# Claude Sample Agent - Node.js -This directory contains a sample agent implementation using Node.js and Claude Agent SDK. +This sample demonstrates how to build an agent using Claude in Node.js with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Node.js and Claude Agent SDK. +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). -## Prerequisites - -- Node.js 18+ -- Anthropic API access -- Claude Agent SDK -- Agents SDK +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). -## How to run this sample +## Prerequisites -1. **Setup environment variables** - ```bash - # Copy the template environment file - cp .env.template .env - ``` +- Node.js 18.x or higher +- Microsoft Agent 365 SDK +- Claude Agent SDK 0.1.1 or higher +- Claude API credentials -2. **Install dependencies** - ```bash - npm install - ``` +## Running the Agent - **Note** Be sure to create the folder `./packages/` and add the a365 packages here for the preinstall script to work. +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. -3. **Build the project** - ```bash - npm run build - ``` +## Support -4. **Start the agent** - ```bash - npm start - ``` +For issues, questions, or feedback: -5. **Optionally, while testing you can run in dev mode** - ```bash - npm run dev - ``` +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/) +- **Security**: For security issues, please see [SECURITY.md](SECURITY.md) -6. **Start AgentsPlayground to chat with your agent** - ```bash - agentsplayground - ``` +## Contributing -The agent will start and be ready to receive requests through the configured hosting mechanism. +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 . -## Documentation +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. -For detailed information about this sample, please refer to: +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. -- **[AGENT-CODE-WALKTHROUGH.md](AGENT-CODE-WALKTHROUGH.md)** - Detailed code explanation and architecture walkthrough +## Additional Resources -## 📚 Related Documentation +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [Claude API documentation](https://docs.anthropic.com/) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) -- [Claude Agent SDK Documentation](https://docs.claude.com/en/docs/agent-sdk/typescript.md) -- [Microsoft Agent 365 Tooling](https://github.com/microsoft/Agent365-nodejs/tree/main/packages/agents-a365-tooling-extensions-claude) -- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/typescript-sdk/tree/main) -- [AgentsPlayground](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/test-with-toolkit-project?tabs=windows) +## Trademarks -## 🤝 Contributing +*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.* -1. Follow the existing code patterns and structure -2. Add comprehensive logging and error handling -3. Update documentation for new features -4. Test thoroughly with different authentication methods +## License -## 📄 License +Copyright (c) Microsoft Corporation. All rights reserved. -This project is licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. \ No newline at end of file diff --git a/nodejs/devin/sample-agent/README.md b/nodejs/devin/sample-agent/README.md index 95f9951f..3e49431f 100644 --- a/nodejs/devin/sample-agent/README.md +++ b/nodejs/devin/sample-agent/README.md @@ -1,64 +1,55 @@ -# Sample Agent - Node.js Devin - -This directory contains a sample agent implementation using Node.js and Devin API. - -## Demonstrates - -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Node.js and Devin API. - -## Prerequisites - -- Node.js 24+ -- Devin API access -- Agents SDK - -## How to run this sample - -1. **Setup environment variables** - - ```bash - # Copy the template environment file - cp .env.example .env - ``` - -2. **Install dependencies** - - ```bash - npm install - ``` - -3. **Build the project** - - ```bash - npm run build - ``` - -4. **Start the agent** - - ```bash - npm run start - ``` - -5. **Start AgentsPlayground to chat with your agent** - ```bash - npm run test-tool - ``` - -The agent will start and be ready to receive requests through the configured hosting mechanism. - -## 📚 Related Documentation - -- [Devin API Documentation](https://docs.devin.ai/api-reference/overview) -- [Microsoft Agent 365 SDK](https://github.com/microsoft/Agents-for-js) -- [AgentsPlayground](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/test-with-toolkit-project?tabs=windows) - -## 🤝 Contributing - -1. Follow the existing code patterns and structure -2. Add comprehensive logging and error handling -3. Update documentation for new features -4. Test thoroughly with different authentication methods - -## 📄 License - -This project is licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. +# Devin Sample Agent - Node.js + +This sample demonstrates how to build an agent using Devin in Node.js with the Microsoft Agent 365 SDK. It covers: + +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK + +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). + +## Prerequisites + +- Node.js 18.x or higher +- Microsoft Agent 365 SDK +- Devin API credentials + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. + +## Support + +For issues, questions, or feedback: + +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/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. + +## Additional Resources + +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [Devin API documentation](https://docs.devin.ai/) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) + +## 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/nodejs/langchain/quickstart-before/README.md b/nodejs/langchain/quickstart-before/README.md index f36a85b8..81daf678 100644 --- a/nodejs/langchain/quickstart-before/README.md +++ b/nodejs/langchain/quickstart-before/README.md @@ -69,4 +69,4 @@ For detailed information about this sample, please refer to: ## 📄 License -This project is licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. +This project is licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. \ No newline at end of file diff --git a/nodejs/langchain/sample-agent/README.md b/nodejs/langchain/sample-agent/README.md index a5dcb8c0..fa34162c 100644 --- a/nodejs/langchain/sample-agent/README.md +++ b/nodejs/langchain/sample-agent/README.md @@ -1,43 +1,58 @@ -# Sample Agent - Node.js LangChain +# LangChain Sample Agent - Node.js -This directory contains a sample agent implementation using Node.js and LangChain. +This sample demonstrates how to build an agent using LangChain in Node.js with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Node.js and LangChain. +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Node.js 18+ -- LangChain -- Agents SDK +- Node.js 18.x or higher +- Microsoft Agent 365 SDK +- LangChain 1.0.1 or higher +- Azure/OpenAI API credentials + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. + +For a detailed explanation of the agent code and implementation, see the [Agent Code Walkthrough](Agent-Code-Walkthrough.md). + +## Support + +For issues, questions, or feedback: + +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/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. -## How to run this sample +## Additional Resources -1. **Setup environment variables** - ```bash - # Copy the example environment file - cp .env.example .env - ``` +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [LangChain documentation](https://js.langchain.com/) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) -2. **Install dependencies** - ```bash - npm install - ``` +## Trademarks -3. **Build the project** - ```bash - npm run build - ``` +*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.* -4. **Start the agent** - ```bash - npm start - ``` +## License -5. **Optionally, while testing you can run in dev mode** - ```bash - npm run dev - ``` +Copyright (c) Microsoft Corporation. All rights reserved. -The agent will start and be ready to receive requests through the configured hosting mechanism. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. \ No newline at end of file diff --git a/nodejs/n8n/sample-agent/README.md b/nodejs/n8n/sample-agent/README.md index ab5772d3..12c64acd 100644 --- a/nodejs/n8n/sample-agent/README.md +++ b/nodejs/n8n/sample-agent/README.md @@ -1,54 +1,57 @@ -# n8n Agent +# n8n Sample Agent - Node.js -A Microsoft Agent 365 that integrates with n8n workflows for AI-powered automation. +This sample demonstrates how to build an agent using n8n in Node.js with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This agent receives messages from Microsoft 365 (Teams, email, Word comments) and forwards them to an n8n workflow via webhook. The n8n workflow processes the request and returns a response. +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Node.js 18+ +- Node.js 18.x or higher +- Microsoft Agent 365 SDK - n8n instance with webhook endpoint -- Agentic Authentication registration - -## How to run this sample - -1. **Configure n8n webhook:** - - Create a workflow in n8n with a webhook trigger - - Configure the webhook to accept POST requests - - The webhook should expect a JSON body with `text`, `from`, `type`, and optional `mcpServers` fields - - Return a JSON response with an `output` field containing the response text - -1. **Set environment variables:** - Copy `.env.example` to `.env` and configure: - - ```bash - cp .env.example .env - ``` - -1. **Install dependencies** - ```bash - npm install - ``` - -1. **Build the project** - ```bash - npm run build - ``` - -1. **Start the agent** - ```bash - npm start - ``` - -1. **Optionally, while testing you can run in dev mode** - ```bash - npm run dev - ``` - -1. **Optionally, for testing you can use the Agents Playground:** - ```bash - # Launch Agents Playground for testing - npm run test-tool - ``` + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. + +For a detailed explanation of the agent code and implementation, see the [Agent Code Walkthrough](Agent-Code-Walkthrough.MD). + +## Support + +For issues, questions, or feedback: + +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/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. + +## Additional Resources + +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [n8n documentation](https://docs.n8n.io/) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) + +## 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/nodejs/openai/sample-agent/README.md b/nodejs/openai/sample-agent/README.md index cb7a0c78..648c0560 100644 --- a/nodejs/openai/sample-agent/README.md +++ b/nodejs/openai/sample-agent/README.md @@ -1,75 +1,56 @@ -# Sample Agent - Node.js OpenAI +# OpenAI Sample Agent - Node.js -This directory contains a sample agent implementation using Node.js and OpenAI. +This sample demonstrates how to build an agent using OpenAI in Node.js with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Node.js and OpenAI. +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Node.js 18+ -- OpenAI API access +- Node.js 18.x or higher +- Microsoft Agent 365 SDK - OpenAI Agents SDK -- Agents SDK - -## How to run this sample - -1. **Setup environment variables** - ```bash - # Copy the template environment file - cp .env.template .env - ``` +- Azure/OpenAI API credentials -2. **Install dependencies** - ```bash - npm install - ``` +## Running the Agent - **Note** Be sure to create the folder `./packages/` and add the a365 packages here for the preinstall script to work. +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. -3. **Build the project** - ```bash - npm run build - ``` +## Support -4. **Start the agent** - ```bash - npm start - ``` +For issues, questions, or feedback: -5. **Optionally, while testing you can run in dev mode** - ```bash - npm run dev - ``` +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/) +- **Security**: For security issues, please see [SECURITY.md](SECURITY.md) -6. **Start AgentsPlayground to chat with your agent** - ```bash - agentsplayground - ``` +## Contributing -The agent will start and be ready to receive requests through the configured hosting mechanism. +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 . -## Documentation +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. -For detailed information about this sample, please refer to: +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. -- **[AGENT-CODE-WALKTHROUGH.md](AGENT-CODE-WALKTHROUGH.md)** - Detailed code explanation and architecture walkthrough +## Additional Resources -## 📚 Related Documentation +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [OpenAI API documentation](https://platform.openai.com/docs/) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) -- [OpenAI Agent SDK Documentation](https://platform.openai.com/docs/guides/agents) -- [Microsoft Agent 365 Tooling](https://github.com/microsoft/Agent365-nodejs/tree/main/packages/agents-a365-tooling-extensions-openai) -- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/typescript-sdk/tree/main) -- [AgentsPlayground](https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/test-with-toolkit-project?tabs=windows) +## Trademarks -## 🤝 Contributing +*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.* -1. Follow the existing code patterns and structure -2. Add comprehensive logging and error handling -3. Update documentation for new features -4. Test thoroughly with different authentication methods +## License -## 📄 License +Copyright (c) Microsoft Corporation. All rights reserved. -This project is licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. \ No newline at end of file diff --git a/nodejs/perplexity/sample-agent/README.md b/nodejs/perplexity/sample-agent/README.md index f5418185..d0777e91 100644 --- a/nodejs/perplexity/sample-agent/README.md +++ b/nodejs/perplexity/sample-agent/README.md @@ -1,95 +1,55 @@ -# Agent Sample - Perplexity AI +# Perplexity Sample Agent - Node.js -This directory contains a sample agent implementation using Node.js and Perplexity AI. +This sample demonstrates how to build an agent using Perplexity in Node.js with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Agent 365 framework with Node.js and Perplexity AI. +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). -## Features - -- ✅ **Chat with Perplexity** - Natural language conversations using Perplexity's Sonar models. -- ✅ **Playground notification handling** - Responds to notifications triggered in the playground UI (@mention in word documents, emails, custom, etc.) +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Node.js 18+ -- Perplexity AI API Key from -- Agents SDK - -## How to run this sample - -### 1. Setup environment variables - -Copy the template and fill in your values: - -```powershell -# Copy the template environment file -cp .env.template .env -``` - -**Minimum required:** - -```bash -PERPLEXITY_API_KEY=your_perplexity_api_key_here -AGENT_ID=perplexity-agent -PORT=3978 -``` - -**For production/M365 integration, also add:** - -```bash -CLIENT_ID=your_bot_app_id -CLIENT_SECRET=your_bot_secret -TENANT_ID=your_tenant_id -``` - -See `.env.template` for all available options. - -### 2. Install dependencies +- Node.js 18.x or higher +- Microsoft Agent 365 SDK +- Perplexity API credentials -```powershell -npm install -``` +## Running the Agent -### 3. Build the sample +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. -```powershell -npm run build -``` +## Support -### 4. Start the agent +For issues, questions, or feedback: -```powershell -npm start -``` +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/) +- **Security**: For security issues, please see [SECURITY.md](SECURITY.md) -You should see: +## Contributing -```powershell -🚀 Perplexity Agent listening on port 3978 - App ID: your-app-id - Debug: false +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 . -✅ Agent ready to receive messages! -``` +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. -### 5. To test with M365 Agents Playground +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. -In a new terminal: +## Additional Resources -```powershell -npm run test-tool -``` +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [Perplexity API documentation](https://docs.perplexity.ai/) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) -This opens the M365 Agents Playground where you can chat with your agent. +## Trademarks -### 5. Optionally, while testing you can run in dev mode (auto-reload) +*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.* -```powershell -npm run dev -``` +## License -This watches for file changes and auto-restarts the server. +Copyright (c) Microsoft Corporation. All rights reserved. -The agent will start and be ready to receive requests through the configured hosting mechanism. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. diff --git a/nodejs/perplexity/sample-agent/package-lock.json b/nodejs/perplexity/sample-agent/package-lock.json index e778bf22..efa30bd2 100644 --- a/nodejs/perplexity/sample-agent/package-lock.json +++ b/nodejs/perplexity/sample-agent/package-lock.json @@ -1,18 +1,18 @@ { - "name": "perplexity-poc", + "name": "perplexity-agent-sample", "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "perplexity-poc", + "name": "perplexity-agent-sample", "version": "1.0.0", "license": "ISC", "dependencies": { - "@microsoft/agents-a365-notifications": "file:../../microsoft-agents-a365-notifications-2025.10.10.tgz", - "@microsoft/agents-a365-observability": "file:../../microsoft-agents-a365-observability-2025.10.10.tgz", - "@microsoft/agents-a365-runtime": "file:../../microsoft-agents-a365-runtime-2025.10.10.tgz", - "@microsoft/agents-a365-tooling": "file:../../microsoft-agents-a365-tooling-2025.10.10.tgz", + "@microsoft/agents-a365-notifications": "*", + "@microsoft/agents-a365-observability": "*", + "@microsoft/agents-a365-runtime": "*", + "@microsoft/agents-a365-tooling": "*", "@microsoft/agents-hosting": "^1.0.15", "@perplexity-ai/perplexity_ai": "^0.12.0", "dotenv": "^17.2.2", diff --git a/nodejs/vercel-sdk/sample-agent/README.md b/nodejs/vercel-sdk/sample-agent/README.md index 80076d7e..eae123cd 100644 --- a/nodejs/vercel-sdk/sample-agent/README.md +++ b/nodejs/vercel-sdk/sample-agent/README.md @@ -1,43 +1,56 @@ -# Sample Agent - Node.js Vercel AI SDK +# Vercel AI SDK Sample Agent - Node.js -This directory contains a sample agent implementation using Node.js and Vercel AI SDK. +This sample demonstrates how to build an agent using Vercel AI SDK in Node.js with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Node.js and Vercel AI SDK. +This sample uses the [Microsoft Agent 365 SDK for Node.js](https://github.com/microsoft/Agent365-nodejs). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Node.js 18+ -- Vercel AI SDK -- Agents SDK +- Node.js 18.x or higher +- Microsoft Agent 365 SDK +- Vercel AI SDK (ai) 5.0.72 or higher +- Azure/OpenAI API credentials + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=nodejs) guide for complete instructions. + +## Support + +For issues, questions, or feedback: + +- **Issues**: Please file issues in the [GitHub Issues](https://github.com/microsoft/Agent365-nodejs/issues) section +- **Documentation**: See the [Microsoft Agents 365 Developer documentation](https://learn.microsoft.com/en-us/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. -## How to run this sample +## Additional Resources -1. **Setup environment variables** - ```bash - # Copy the example environment file - cp .env.example .env - ``` +- [Microsoft Agent 365 SDK - Node.js repository](https://github.com/microsoft/Agent365-nodejs) +- [Microsoft 365 Agents SDK - Node.js repository](https://github.com/Microsoft/Agents-for-js) +- [Vercel AI SDK documentation](https://sdk.vercel.ai/docs) +- [Node.js API documentation](https://learn.microsoft.com/javascript/api/?view=m365-agents-sdk&preserve-view=true) -2. **Install dependencies** - ```bash - npm install - ``` +## Trademarks -3. **Build the project** - ```bash - npm run build - ``` +*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.* -4. **Start the agent** - ```bash - npm start - ``` +## License -5. **Optionally, while testing you can run in dev mode** - ```bash - npm run dev - ``` +Copyright (c) Microsoft Corporation. All rights reserved. -The agent will start and be ready to receive requests through the configured hosting mechanism. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. diff --git a/python/agent-framework/sample-agent/README.md b/python/agent-framework/sample-agent/README.md index 3636336d..e315def9 100644 --- a/python/agent-framework/sample-agent/README.md +++ b/python/agent-framework/sample-agent/README.md @@ -1,41 +1,58 @@ -# Sample Agent - Python AgentFramework +# Agent Framework Sample Agent - Python -This directory contains a sample agent implementation using Python and Microsoft's Agent Framework SDK. +This sample demonstrates how to build an agent using Agent Framework in Python with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Python and Agent Framework SDK, including: -- Azure OpenAI integration with AgentFramework -- MCP (Model Context Protocol) tool integration -- Microsoft Agent 365 observability and tracing -- Multiple authentication modes (anonymous and agentic) -- Microsoft 365 Agents SDK hosting patterns +This sample uses the [Microsoft Agent 365 SDK for Python](https://github.com/microsoft/Agent365-python). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Python 3.11+ -- Azure OpenAI access -- Azure CLI (for authentication) +- Python 3.x +- Microsoft Agent 365 SDK +- Agent Framework (agent-framework-azure-ai) +- Azure/OpenAI API credentials + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=python) guide for complete instructions. + +For a detailed explanation of the agent code and implementation, see the [Agent Code Walkthrough](AGENT-CODE-WALKTHROUGH.md). + +## 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/en-us/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 . -## Documentation +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. -For detailed information about this sample, please refer to: +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. -- **[AGENT-TESTING.md](AGENT-TESTING.md)** - Complete setup and testing guide with step-by-step instructions -- **[AGENT-CODE-WALKTHROUGH.md](AGENT-CODE-WALKTHROUGH.md)** - Detailed code explanation and architecture walkthrough +## Additional Resources -## 📚 Related Documentation +- [Microsoft Agent 365 SDK - Python repository](https://github.com/microsoft/Agent365-python) +- [Microsoft 365 Agents SDK - Python repository](https://github.com/Microsoft/Agents-for-python) +- [Agent Framework documentation](https://github.com/microsoft/Agent365-python/tree/main/packages/agent-framework) +- [Python API documentation](https://learn.microsoft.com/python/api/?view=m365-agents-sdk&preserve-view=true) -- [Agent Framework SDK](https://github.com/microsoft/agent-framework) -- [Microsoft Agent 365 SDK for Python](https://github.com/microsoft/Agent365-python) +## Trademarks -## 🤝 Contributing +*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.* -1. Follow the existing code patterns and structure -2. Add comprehensive logging and error handling -3. Update documentation for new features -4. Test thoroughly with different authentication methods +## License -## 📄 License +Copyright (c) Microsoft Corporation. All rights reserved. -This project is licensed under the MIT License - see the [LICENSE](../../LICENSE.md) file for details. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. \ No newline at end of file diff --git a/python/agent-framework/sample-agent/SETUP-GUIDE-Unofficial.md b/python/agent-framework/sample-agent/SETUP-GUIDE-Unofficial.md deleted file mode 100644 index a978c561..00000000 --- a/python/agent-framework/sample-agent/SETUP-GUIDE-Unofficial.md +++ /dev/null @@ -1,184 +0,0 @@ -# Quick Setup Guide - -> **NOTE: This file should be removed before Ignite.** - -Get the A365 Python SDK sample running in 7 simple steps. - -## Setup Steps - -### 1. Verify Python installation - -First, ensure you have Python 3.11 or higher installed: - -```powershell -# Check if Python is installed -python --version -``` - -If Python is not found: -- Download and install Python 3.11+ from -- Make sure to check "Add Python to PATH" during installation -- Restart VS Code and try again - -**✅ Success Check**: You should see Python 3.11.x or higher - -### 2. Verify prerequisites - -Ensure you have the required Microsoft Agent365 packages: - -```powershell -# Navigate to the agent-framework directory (parent of sample-agent) -cd .. - -# Check if dist folder exists with required wheel files -ls dist -``` - -If the dist folder doesn't exist or is empty, you have two options: - -#### Option A: Download from GitHub Actions (Recommended) -1. Create the dist folder: `mkdir dist` -2. Download the required .whl files: - - Visit: https://github.com/microsoft/Agent365-python (get the packages from main) - - Click on **Artifacts** → **python-3.11** - - Download the zip file and extract the wheel files into the dist folder: - - `microsoft_agents_a365_tooling-*.whl` - - `microsoft_agents_a365_tooling_extensions_agentframework-*.whl` - - `microsoft_agents_a365_observability_core-*.whl` - - `microsoft_agents_a365_observability_extensions_agent_framework-*.whl` - - `microsoft_agents_a365_runtime-*.whl` - - `microsoft_agents_a365_notifications-*.whl` - -#### Option B: Install from PyPI -If packages are available on PyPI, you can install them directly (skip to step 6 and modify the installation command). - -**✅ Success Check**: The dist folder should contain the Microsoft Agent365 wheel files. - -```powershell -# Return to sample-agent directory for next steps -cd sample-agent -``` - -### 3. Set up environment configuration - -Open PowerShell in VS Code (Terminal → New Terminal) and navigate to the sample-agent directory: - -```powershell -# Navigate to the sample-agent directory (where this README is located) -# Make sure you're in the sample-agent folder -cd sample-agent - -# Copy the environment template -copy .env.template .env -``` - -### 4. Update environment variables - -Open the newly created `.env` file and update the following values: - -```env -AZURE_OPENAI_API_KEY= -AZURE_OPENAI_ENDPOINT= -AZURE_OPENAI_DEPLOYMENT= -AZURE_OPENAI_API_VERSION="2024-02-01" -``` - -### 5. Install uv - -uv is a fast Python package manager. Open PowerShell in VS Code (Terminal → New Terminal) and run: - -```powershell -# Install uv -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - -# Add uv to PATH for this session (only if not already there) -if ($env:PATH -notlike "*$env:USERPROFILE\.local\bin*") { - $env:PATH += ";$env:USERPROFILE\.local\bin" -} - -# Test that uv works -uv --version -``` - -### 6. Set up the project - -Continue in the same terminal (make sure you're still in the sample-agent directory): - -```powershell -# Verify you're in the right directory - you should see pyproject.toml -ls pyproject.toml - -# Create virtual environment with pip included -uv venv .venv - -# Activate the virtual environment -.\.venv\Scripts\Activate.ps1 - -# Verify setup - you should see (.venv) in your prompt -python --version -``` - -**✅ Success Check**: Your terminal shows `(.venv)` at the beginning and you can see `pyproject.toml` in the directory - -### 7. Install dependencies - -Install all dependencies from the local wheel files and PyPI: - -```powershell -uv pip install -e . --find-links ../dist --pre -``` - -**Important**: You may see some warning messages about dependencies. **This is normal and expected** - the agent will work correctly. - -**✅ Success Check**: "Installed X packages" message appears - -### 8. Start the agent - -```powershell -python start_with_generic_host.py -``` - -**✅ Success Check**: You should see: -``` -🚀 Starting server on localhost:3978 -🎯 Ready for testing! -======== Running on http://localhost:3978 ======== -``` - -## Testing with Microsoft 365 Agents Playground - -After starting the server, you can test it using the Microsoft 365 Agents Playground. - -In a separate terminal, start the playground: - -```powershell -agentsplayground -``` - -You should see the Microsoft 365 Agents Playground running locally and ready to interact with your agent. - -## Troubleshooting - -### Common Issues - -- **"python is not recognized"** → Install Python 3.11+ from python.org and check "Add Python to PATH" - -- **"uv not found"** → Restart your terminal and try step 4 again - -- **"No module named 'dotenv'"** → Try: `uv pip install python-dotenv` - -- **"No module named..."** → Make sure you see `(.venv)` in your prompt and that the installation command in step 6 completed successfully. Most missing dependencies should already be included in requirements.txt, but if you still get errors, you can install them individually: - ```powershell - # For any additional missing modules: - uv pip install - ``` - -- **Dependency conflict warnings** → These are expected! Continue with the next step - the agent will work fine - -- **"No solution found when resolving dependencies"** → Make sure you're using the installation process in step 6 and that the dist folder exists with wheel files - -- **Agent won't start** → Check you're in the sample-agent directory and that all installation steps completed successfully - -## Done! - -Your agent is now running and ready for testing. Configuration values will be provided during the bug bash session. diff --git a/python/openai/sample-agent/AGENT-TESTING.md b/python/openai/sample-agent/AGENT-TESTING.md deleted file mode 100644 index 3a696eb9..00000000 --- a/python/openai/sample-agent/AGENT-TESTING.md +++ /dev/null @@ -1,473 +0,0 @@ -# Agent Testing Guide - -This document provides comprehensive testing instructions for the OpenAI Agent sample, including setup, testing scenarios, troubleshooting, and validation steps. - -## Overview - -The OpenAI Agent sample supports multiple testing modes and scenarios: -- **Local Development Testing**: Using console output and direct interaction -- **Microsoft 365 Agents SDK Testing**: Through the generic host server -- **MCP Tool Testing**: Validating external tool integrations -- **Observability Testing**: Verifying tracing and monitoring capabilities -- **Authentication Testing**: Both anonymous and agentic authentication modes - -## Prerequisites - -### Required Software -- Python 3.11 or higher -- OpenAI API key with sufficient credits -- Access to Microsoft Agent 365 MCP servers (for tool testing) - -### Environment Setup -1. Install uv (Python package manager): - ```powershell - # On Windows - powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - - # Or using pip if you prefer - pip install uv - ``` - -2. Create and activate a virtual environment: - ```powershell - uv venv venv - .\venv\Scripts\Activate.ps1 - ``` - -3. Create your environment configuration file: - ```powershell - Copy-Item .env.template .env - ``` - Or create a new `.env` file with the required variables. - -4. Configure your environment variables in `.env`: - - Copy the `.env.template` file as a starting point - - At minimum, set your `OPENAI_API_KEY` - - Review other variables in `.env.template` and configure as needed for your testing scenario - - **Model Configuration**: You can specify different OpenAI models: - ```env - OPENAI_MODEL=gpt-4o-mini # Default, cost-effective - OPENAI_MODEL=gpt-4o # More capable, higher cost - OPENAI_MODEL=gpt-3.5-turbo # Legacy compatibility - ``` - -5. Install all dependencies (ensure your virtual environment is activated): - - **Using pyproject.toml with uv** - ```powershell - # Install dependencies using pyproject.toml - uv pip install -e . - ``` - - **Note**: The pyproject.toml includes all required packages and a local index configuration pointing to `../../dist` for package resolution. - ```toml - # Local packages from local index - # - Update package versions to match your built wheels - "microsoft_agents_a365_tooling==0.1.0", - "microsoft_agents_a365_tooling_extensions_openai==0.1.0", - "microsoft_agents_a365_observability==0.1.0", - "microsoft_agents_a365_observability_extensions_openai==0.1.0", - "microsoft_agents_a365_notifications==0.1.0", - ``` - - **Important**: Verify these package versions match your locally built wheels in the `../../dist` directory and ensure the directory path is correct before installation. - -## Testing Scenarios - -### 1. Basic Agent Functionality Testing - -#### Basic Conversation Testing -- **Purpose**: Test AI model integration and response generation through proper endpoints -- **Setup**: Use the hosted server mode with `/api/messages` endpoint -- **Test Cases**: - - Simple greeting: "Hello, how are you?" - - Information request: "What can you help me with?" - - Complex query: "Explain quantum computing in simple terms" - -**Expected Results**: -- Coherent, helpful responses -- Response times under 10 seconds -- No authentication or API key errors - -### 2. Server Hosting Testing - -#### Start the Generic Host Server -```powershell -uv run python start_with_generic_host.py -``` - -**Expected Console Output for the Python server:** -``` -================================================================================ -Microsoft Agents SDK Integration - OFFICIAL IMPLEMENTATION -================================================================================ - -🔒 Authentication: Anonymous (or Agentic if configured) -Using proper Microsoft Agents SDK patterns -🎯 Compatible with Agents Playground - -🚀 Starting server on localhost:3978 -📚 Microsoft 365 Agents SDK endpoint: http://localhost:3978/api/messages -❤️ Health: http://localhost:3978/api/health -🎯 Ready for testing! -``` - -#### Testing with Microsoft 365 Agents Playground -After starting the server, you can test it using the Microsoft 365 Agents Playground. -In a separate terminal, start the playground: -```powershell -teamsapptester -``` - -You should see the Microsoft 365 Agents Playground running locally - -#### Health Check Testing -- **Test**: `Invoke-RestMethod -Uri http://localhost:3978/api/health` (PowerShell) or `curl http://localhost:3978/api/health` -- **Expected Response**: - ```json - { - "status": "ok", - "openai_agent_initialized": true, - "auth_mode": "anonymous" - } - ``` - -#### Port Conflict Testing -- **Test**: Start multiple instances simultaneously -- **Expected Behavior**: Server automatically tries next available port (3979, 3980, etc.) -- **Validation**: Check console output for actual port used - -### 3. Microsoft 365 Agents SDK Integration Testing - -#### Message Endpoint Testing -- **Endpoint**: `POST http://localhost:3978/api/messages` -- **Test Payload**: - ```json - { - "type": "message", - "text": "Hello, can you help me?", - "from": { - "id": "test-user", - "name": "Test User" - }, - "conversation": { - "id": "test-conversation" - } - } - ``` - - -#### Expected Response Flow -1. Server receives message -2. Agent processes request with observability tracing -3. Response returned with appropriate structure -4. Trace output visible in console (if observability enabled) - -### 4. MCP Tool Integration Testing - -#### Testing from Microsoft 365 Agents Playground -Once you have the agent running and the playground started with `teamsapptester`, you can test MCP tool functionality directly through the playground interface: - -- **Interactive Testing**: Use the playground's chat interface to request tool actions -- **Real-time Feedback**: See tool execution results immediately in the conversation -- **Visual Validation**: Confirm tools are working through the user-friendly interface - -#### Tool Discovery Testing -- **Validation Points**: - - Tools loaded from MCP servers during agent initialization - - Console output shows tool count: "✅ Loaded X tools from MCP servers" - - No connection errors to MCP servers - -#### Tool Functionality Testing -- **Email Tools** (if available): - - "Send an email to test@example.com with subject 'Test' and body 'Hello'" - - "Check my recent emails" - - "Help me organize my inbox" - -- **Calendar Tools** (if available): - - "Create a meeting for tomorrow at 2 PM" - - "Check my availability this week" - - "Show my upcoming appointments" - -#### Tool Error Handling Testing -- **Scenarios**: - - Request tools when MCP servers are unavailable - - Invalid tool parameters - - Authentication failures for tool access - -- **Expected Behavior**: - - Graceful error messages to users - - Agent continues functioning without tools - - Clear error logging for debugging - -### 5. Authentication Testing - -#### Anonymous Authentication Testing -- **Configuration**: Default setup without agentic auth -- **Expected Behavior**: - - Agent starts successfully - - Basic functionality works - - Console shows "🔒 Authentication: Anonymous" - -#### Agentic Authentication Testing -- **Configuration**: Set `USE_AGENTIC_AUTH=true` in `.env` -- **Required Environment Variables**: - ```env - USE_AGENTIC_AUTH=true - AGENT_ID=your_agent_id - CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=client_id - CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=client_secret - CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=tenant_id - ``` - -- **Testing through Agents Playground**: - 1. Ensure that Agentic Auth is set up as in the previous step - 2. Start the AgentsPlayground with `teamsapptester` - 3. Click on **'Mock An Activity'** → **'Trigger Custom Activity'** → **'Custom activity'** - 4. Add the following JSON payload: - ```json - { - "type": "message", - "id": "c4970243-ca33-46eb-9818-74d69f553f63", - "timestamp": "2025-09-24T17:40:19+00:00", - "serviceUrl": "http://localhost:56150/_connector", - "channelId": "agents", - "from": { - "id": "manager@contoso.com", - "name": "Agent Manager", - "role": "user" - }, - "recipient": { - "id": "a365testingagent@testcsaaa.onmicrosoft.com", - "name": "A365 Testing Agent", - "agenticUserId": "ea1a172b-f443-4ee0-b8a1-27c7ab7ea9e5", - "agenticAppId": "933f6053-d249-4479-8c0b-78ab25424002", - "tenantId": "5369a35c-46a5-4677-8ff9-2e65587654e7", - "role": "agenticUser" - }, - "conversation": { - "conversationType": "personal", - "tenantId": "00000000-0000-0000-0000-0000000000001", - "id": "personal-chat-id" - }, - "membersAdded": [], - "membersRemoved": [], - "reactionsAdded": [], - "reactionsRemoved": [], - "locale": "en-US", - "attachments": [], - "entities": [ - { - "id": "email", - "type": "productInfo" - }, - { - "type": "clientInfo", - "locale": "en-US", - "timezone": null - }, - { - "type": "emailNotification", - "id": "c4970243-ca33-46eb-9818-74d69f553f63", - "conversationId": "personal-chat-id", - "htmlBody": "\n
\n Send Email to with subject 'Hello World' and message 'This is a test'.
\n\n\n" - } - ], - "channelData": { - "tenant": { - "id": "00000000-0000-0000-0000-0000000000001" - } - }, - "listenFor": [], - "textHighlights": [] - } - ``` - -- **Expected Behavior**: - - Agent starts with Azure AD authentication - - Console shows "🔒 Authentication: Agentic" - - Tool access uses authenticated context - - Custom activity is processed successfully through the playground - -### 6. Observability Testing - -**Prerequisites**: Ensure your `.env` file includes the observability configuration: -```env -# Observability Configuration -OBSERVABILITY_SERVICE_NAME=openai-agent-sample -OBSERVABILITY_SERVICE_NAMESPACE=agents.samples -``` - -#### Trace Output Validation -- **Expected Console Output**: - ``` - ✅ Agent 365 configured successfully - ✅ OpenAI Agents instrumentation enabled - ``` - -#### Span Creation Testing -- **Test**: Send a message to the agent -- **Expected Trace Elements**: - - Custom span: "process_user_message" - - Span attributes: message length, content preview - - OpenAI API call spans (automatic instrumentation) - - Tool execution spans (if tools are used) - -**Sample Console Output**: -```json -{ - "name": "process_user_message", - "context": { - "trace_id": "0x46eaa206d93e21d1c49395848172f60b", - "span_id": "0x6cd9b00954a506aa" - }, - "kind": "SpanKind.INTERNAL", - "start_time": "2025-10-16T00:01:54.794475Z", - "end_time": "2025-10-16T00:02:00.824454Z", - "status": { - "status_code": "UNSET" - }, - "attributes": { - "user.message.length": 59, - "user.message.preview": "Send Email to YourEmail@microsoft.com saying Hel...", - "response.length": 133, - "response.preview": "The email saying \"Hello World!\" has been successfu..." - }, - "resource": { - "attributes": { - "service.namespace": "agent365-samples", - "service.name": "openai-sample-agent" - } - } -} - -{ - "name": "generation", - "context": { - "trace_id": "0x46eaa206d93e21d1c49395848172f60b", - "span_id": "0xdbf26b9b8650a9a8" - }, - "kind": "SpanKind.INTERNAL", - "parent_id": "0xc1cb4ce42060555a", - "start_time": "2025-10-16T00:01:58.936096Z", - "end_time": "2025-10-16T00:02:00.823995Z", - "status": { - "status_code": "OK" - }, - "attributes": { - "gen_ai.operation.name": "chat", - "gen_ai.provider.name": "openai", - "gen_ai.request.model": "gpt-4o-mini", - "gen_ai.usage.input_tokens": 1328, - "gen_ai.usage.output_tokens": 33, - "gen_ai.response.content.0.message_content": "The email saying \"Hello World!\" has been successfully sent..." - } -} -``` - -#### Error Tracing Testing -- **Test**: Force an error (invalid API key, network issues) -- **Expected Behavior**: - - Exceptions recorded in spans - - Error status set on spans - - Detailed error information in traces - -## Troubleshooting Common Issues - -### Agent Startup Issues - -#### OpenAI API Key Problems -- **Error**: "OpenAI API key is required" -- **Solution**: Verify `OPENAI_API_KEY` in `.env` file -- **Validation**: Check API key has sufficient credits - -#### Import Errors -- **Error**: "Required packages not installed" -- **Solution**: Run `uv pip install -e .` -- **Note**: Ensure using Python 3.11+ and correct virtual environment - -#### Port Binding Errors -- **Error**: "error while attempting to bind on address" -- **Solution**: Server automatically tries next port, or set custom `PORT` in `.env` - -### Runtime Issues - -#### MCP Server Connection Failures -- **Symptoms**: "Error setting up MCP servers" in logs -- **Causes**: Network issues, authentication problems, server unavailability -- **Solutions**: - - Check network connectivity - - Verify bearer token or agentic auth configuration - - Confirm MCP server URLs are correct - -#### Observability Configuration Failures -- **Symptoms**: "WARNING: Failed to configure observability" -- **Impact**: Agent continues working, but without tracing -- **Solutions**: - - Check Microsoft Agent 365 SDK package installation - - Verify environment variables are set correctly - - Review console output for specific error details - -#### Model API Errors -- **Symptoms**: API call failures, rate limiting errors -- **Solutions**: - - Check OpenAI API key validity and credits - - Verify model name is supported - - Implement retry logic for rate limiting - -### Testing Environment Issues - -#### Authentication Context Problems -- **Symptoms**: Tools fail to execute, authorization errors -- **Solutions**: - - Verify agentic authentication setup - - Check bearer token validity - - Ensure proper Azure AD configuration - -#### Network Connectivity Issues -- **Symptoms**: Timeouts, connection refused errors -- **Solutions**: - - Check internet connectivity - - Verify firewall settings - - Test MCP server URLs directly - -## Validation Checklist - -### ✅ Basic Functionality -- [ ] Agent initializes without errors -- [ ] Observability configuration succeeds -- [ ] Health endpoint returns 200 OK -- [ ] Basic conversation works -- [ ] Graceful error handling - -### ✅ Server Integration -- [ ] Microsoft 365 Agents SDK endpoint responds -- [ ] Message processing works end-to-end -- [ ] Concurrent requests handled properly -- [ ] Server shutdown is clean - -### ✅ MCP Tool Integration -- [ ] Tools discovered and loaded -- [ ] Tool execution works correctly -- [ ] Tool errors handled gracefully -- [ ] Authentication context passed properly - -### ✅ Observability -- [ ] Traces appear in console output -- [ ] Custom spans created correctly -- [ ] Exception tracking works -- [ ] Performance metrics captured - -### ✅ Authentication -- [ ] Anonymous mode works for development -- [ ] Agentic authentication works for enterprise -- [ ] Proper authentication context propagation -- [ ] Secure credential handling - -### ✅ Configuration -- [ ] Environment variables loaded correctly -- [ ] Default values work appropriately -- [ ] Error messages are clear and actionable -- [ ] Different model configurations work - -This comprehensive testing guide ensures the OpenAI Agent sample is thoroughly validated across all its capabilities and integration points. diff --git a/python/openai/sample-agent/README.md b/python/openai/sample-agent/README.md index 43de6099..01712d01 100644 --- a/python/openai/sample-agent/README.md +++ b/python/openai/sample-agent/README.md @@ -1,17 +1,58 @@ -# Agent 365 SDK Python OpenAI Sample Agent +# OpenAI Sample Agent - Python -This directory contains a sample agent implementation using Python and OpenAI. +This sample demonstrates how to build an agent using OpenAI in Python with the Microsoft Agent 365 SDK. It covers: -## Demonstrates +- **Observability**: End-to-end tracing, caching, and monitoring for agent applications +- **Notifications**: Services and models for managing user notifications +- **Tools**: Model Context Protocol tools for building advanced agent solutions +- **Hosting Patterns**: Hosting with Microsoft 365 Agents SDK -This sample demonstrates how to build an agent using the Microsoft Agent 365 SDK with Python and OpenAI. +This sample uses the [Microsoft Agent 365 SDK for Python](https://github.com/microsoft/Agent365-python). + +For comprehensive documentation and guidance on building agents with the Microsoft Agent 365 SDK, including how to add tooling, observability, and notifications, visit the [Microsoft Agent 365 Developer Documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/). ## Prerequisites -- Python 3.11+ -- OpenAI API access +- Python 3.x +- Microsoft Agent 365 SDK +- OpenAI Agents SDK (openai-agents) +- Azure/OpenAI API credentials + +## Running the Agent + +To set up and test this agent, refer to the [Configure Agent Testing](https://learn.microsoft.com/en-us/microsoft-agent-365/developer/testing?tabs=python) guide for complete instructions. + +For a detailed explanation of the agent code and implementation, see the [Agent Code Walkthrough](AGENT-CODE-WALKTHROUGH.md). + +## 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/en-us/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. + +## Additional Resources + +- [Microsoft Agent 365 SDK - Python repository](https://github.com/microsoft/Agent365-python) +- [Microsoft 365 Agents SDK - Python repository](https://github.com/Microsoft/Agents-for-python) +- [OpenAI API documentation](https://platform.openai.com/docs/) +- [Python API documentation](https://learn.microsoft.com/python/api/?view=m365-agents-sdk&preserve-view=true) + +## 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.* -## How to run this sample +## License -See [AGENT-TESTING.md](AGENT-TESTING.md) for detailed setup and testing instructions. +Copyright (c) Microsoft Corporation. All rights reserved. +Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.