Tripadvisor tool

use-cases/agents/3p-tool/PartnerContributingGuide.md

@@ -0,0 +1,38 @@
+# 3p Tool Partner Contributing Guide
+
+## Who should read this?
+This contributing guide is designed for partners who want to bring their APIs as part of the **Azure AI Foundry Tool Catalog** so that customers can integrate your APIs with Azure AI Agent service through a tool to retrieve data or integrating with a workflow.
+
+## Prepare your PR
+Your PR needs to create a new folder with the tool name and include the following information: 
+- `README.md` (required): follow this [template](./README_template_for_parter.md) as an example and this README file will serve as public documentation for help customers set up and use the tool with your API through Azure AI Agent service
+  - The name, logo, and description in this README file will be used in the Azure AI Foundry Portal user experience and marketing materials.
+  - It must include how customers set up an account with your API directly and your customer support contact or website.
+  - Customers should be able to follow this README file and successfully use the tool with Azure AI Agent service.
+- `sample code` (required): using at least one of the SDK below
+  - (recommended) Python: [Azure AI Projects client library for Python | Microsoft Learn](https://learn.microsoft.com/en-us/python/api/overview/azure/ai-projects-readme?view=azure-python-preview#create-agent-with-openapi)
+  - .NET/C#: [Azure AI Projects client library for .NET - Azure for .NET Developers | Microsoft Learn](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.projects-readme?view=azure-dotnet-preview)
+  - JavaScript: [Azure AI Projects client library for JavaScript | Microsoft Learn](https://learn.microsoft.com/en-us/javascript/api/overview/azure/ai-projects-readme?view=azure-node-preview)
+  - Requirements fot the code sample:
+    - you should have tested the code sample works end to end with the OpenAPI spec in this PR before submitting
+    - include the process of creating an `openApi` tool with your OpenAPI spec
+    - for `agent creation`, provide a user-friendly name and useful instructions customized for your API
+    - for `message creation`, provide an example of a user query that can be used with your API and expected response in comments
+- `OpenAPI spec` (required): the OpenAPI spec for your API
+  - Your OpenAPI should be updated based on the requirements [here](https://learn.microsoft.com/en-us/azure/ai-services/agents/how-to/tools/openapi-spec?tabs=python&pivots=overview#authenticating-with-api-key) to support appropriate authentication method
+  - If you require customers to update the OpenAPI spec, please provide **clear** instructions and **placeholder** on where they should update in the OpenAPI spec file and the README.file.
+  - This OpenAPI spec will also be used in the Azure AI Foundry Portal user experience.
+- `media` folder (optional): if you need to include any screenshots, please add the screenshots in this folder and refer to them.
+
+## Submit your PR
+Before you submit the PR, please double check:
+- you have **everything** required above ready
+- you have **fully** tested your code sample
+
+Then, you can go ahead and create a PR. By creating a PR, you automatically agree to the Contributor License Agreement and see more details [here](../../../CONTRIBUTING.md). 
+
+When creating the PR, please make sure you give your PR a reviewer-friendly name. We will come back to you within 10 business days. 
+
+## Once your PR is approved
+- customers will see a folder for the tool in `main` branch
+- Azure AI Foundry Portal team will work to bring your tool to the Portal user experience.

use-cases/agents/3p-tool/README.md

@@ -0,0 +1,34 @@
+# Connect with partner-authored tools in Azure AI Agent Service
+
+## Overview
+The tool catalog in Azure AI Foundry portal is the hub to discover and use a wide range of tools for building AI agents with Azure AI Agent Service. The tool catalog features tools for extending your agents' abilities using hosted tools, and ones offered from partners such as Tripadvisor, and Morningstar. You can discover all tools offered by **partners** in this folder.
+
+> [!IMPORTANT]
+> * Your use of connected non-Microsoft services is subject to the terms between you and the service provider. By connecting to a non-Microsoft service, you acknowledge that some of your data, such as prompt content, is passed to the non-Microsoft service, and/or your application might receive data from the non-Microsoft service. You're responsible for your use of non-Microsoft data. 
+> * Using tools from tool catalog may incur usage with tool providers, review the pricing plan with your selected tool data providers.
+> * Code samples and OpenAPI spec are provided by partners as-is. **need help from CELA to rewrite this**
+
+## Get Started
+1. Create an Azure AI Agent following the [documentation](https://learn.microsoft.com/en-us/azure/ai-services/agents/quickstart)
+
+1. Select tools provided by our partners for your agent
+
+|Tool  |Description  |
+|---------|---------|
+| [Tripadvisor](./Tripadvisor/README.md) | This tool lets you access Tripadvisor's useful travel platform that can, for example, provide travel guidance and reviews. |
+
+1. Review the README file provided by the partner and get started!
+
+## Frequently Asked Questions
+1. Can I set up an account through Microsoft with the tool provided by a partner?
+
+   No, you have to create an account with the partner directly.
+
+1. I am running into issues with the code sample, how should I troubleshoot?
+
+   If this is an issue with Azure AI Agent service, please refer to your [support plan](https://support.microsoft.com/en-us). If this is an issue with the OpenAPI spec, code sample or authentication, please refer to the `customer support contact` provided by each partner in the README file.
+
+1. I want to learn more about Azure AI Agent service, where should I go?
+
+   Please visit the public documentation [here](https://learn.microsoft.com/en-us/azure/ai-services/agents/)
+

use-cases/agents/3p-tool/README_template_for_partner.md

@@ -0,0 +1,48 @@
+# <tool_name>
+<tool_name> will be used in Azure AI Foundry Portal experience and marketing materials.
+
+Requirement:
+- Must exist and be written in English.
+- Must be unique and distinguishable from any existing tool/agent template.
+- Should be the name of your product or organization.
+- Can't be longer than 30 characters.
+- Can't contain the words *API*, *Tool*, *Azure AI Agent Service*, *Azure AI*, *Agent*, or any of our other Azure AI Foundry product names (for example, Document Intelligence).
+- Can't end in a nonalphanumeric character, including carriage return, new line, or blank space.
+- Good example: Tripadvisor
+- Bad example: Tripadvisor Tool 
+
+## Description
+<tool_description>
+
+<tool_descrption> will be used in Azure AI Foundry Portal experience and marketing materials.
+
+Requirement:
+- Ensure your description complies with the [Marketplace guidelines](https://learn.microsoft.com/en-us/legal/marketplace/certification-policies#10013-description). 
+- Must exist and be written in English. 
+- Must be free of grammatical and spelling errors. 
+- Length should be within 1 sentence, under 10 words 
+- Cannot contain *Azure AI Agent Service* or other Azure AI Foundry product names (such as Document Intelligence) 
+- If your tool includes multiple operations, the description should cover all operations.
+
+## Prerequisites
+<prerequisites_in_bullet_points>
+
+Requirement:
+- Must include how to create a new account with your service
+- Include any other requirements to set up the account, such as uploading data, etc
+- Recommend including screenshots if possible to help customers understand. Store the screenshots in `media` folder 
+
+## Setup
+<setup_in_bullet_points>
+
+Requirement:
+- If you require customers to use `connection` as authentication methods, walk customers from step by step to retrieve the secret (API key, token etc) and how to create a `customKeys` connection to store the secret
+- Recommend including screenshots if possible to help customers understand. Store the screenshots in `media` folder 
+
+## Use <tool_name>
+<explanation_for_using_your_code_sample>
+
+## Customer Support Contact
+<your_customer_support_contact_or_website>
+
+By providing this customer support contact or website, customers will reach out to you directly if they run into issues with the OpenAPI spec, code sample, authentication etc. Customers will reach out to Microsoft if they run into issues with Azure AI Agent service.

use-cases/agents/3p-tool/Tripadvisor/README.md

@@ -0,0 +1,58 @@
+# Tripadvisor
+
+## Description
+Get travel data, guidance and reviews
+
+## Prerequisites
+
+* Obtain an API key for your [Tripadvisor developer account](https://www.tripadvisor.com/developers?screen=credentials).
+* Make sure when you put 0.0.0.0/0 for the IP address restriction to allow traffic from Azure AI Agent Service.
+
+## Setup
+1. Go to [Azure AI Foundry portal](https://ai.azure.com/) and select your AI Project. Select **Management Center**.
+
+   :::image type="content" source="../../media/tools/licensed-data/project-assets.png" alt-text="A screenshot showing the selectors for the management center for an AI project." lightbox="../../media/tools/licensed-data/project-assets.png":::
+
+1. Select **+new connection** in the settings page.
+
+   :::image type="content" source="./media/connected-resources.png" alt-text="A screenshot showing the connections for the selected AI project." lightbox="../../media/tools/licensed-data/connected-resources.png":::
+
+1. Select **custom keys** in **other resource types**.
+
+   :::image type="content" source="./media/custom-keys.png" alt-text="A screenshot showing the custom key option in the settings page." lightbox="../../media/tools/licensed-data/custom-keys.png":::
+
+1. Enter the following information to create a connection to store your Tripadvisor key:
+   1. Set **Custom keys** to "key", with the value being your Tripadvisor API key.
+   1. Make sure **is secret** is checked.
+   1. Set the connection name to your connection name. You use this connection name in your sample code or Foundry Portal later.
+   1. For the **Access** setting, you can choose either *this project only* or *shared to all projects*. Just make sure in your code, the connection string of the project you entered has access to this connection.
+
+   :::image type="content" source="./media/connect-custom-resource.png" alt-text="A screenshot showing the screen for adding Tripadvisor connection information." lightbox="../../media/tools/licensed-data/connect-custom-resource.png":::
+
+## Use Tripadvisor tool through Foundry portal
+
+1. To use the Tripadvisor tool in the Azure AI Foundry, in the **Create and debug** screen for your agent, scroll down the **Setup** pane on the right to **action**. Then select **Add**.
+
+1. Select **Tripadvisor** and follow the prompts to add the tool. 
+
+1. Give a name for your Tripadvisor tool and provide an optional description.
+
+    :::image type="content" source="./media/add-data-source.png" alt-text="A screenshot showing the Tripadvisor data source." lightbox="../../media/tools/licensed-data/add-data-source.png":::
+
+1. Select the custom key connection you just created. 
+
+    :::image type="content" source="./media/add-connection.png" alt-text="A screenshot showing the connection for your Tripadvisor tool, and a JSON example." lightbox="../../media/tools/licensed-data/add-connection.png":::
+
+1. Finish and start chatting.
+
+## Connect Tripadvisor through code-first experience
+
+You can follow the [code sample](./tripadvisor.py) to use Tripadvisor through Agent SDK.
+
+1. Remember to store and import Tripadvisor [OpenAPI spec](./tripadvisor.json).
+
+1. Make sure you have updated the authentication method to be `connection` and fill in the connection ID of your custom key connection.
+   ``` python
+   auth = OpenApiConnectionAuthDetails(security_scheme=OpenApiConnectionSecurityScheme(connection_id="your_connection_id"))
+   ```
+## Customer Support Contact