Skip to content

Commit dc63dda

Browse files
paulth1paulth1
committed
fixing merge conflict
2 parents fba4f31 + a4f64e1 commit dc63dda

File tree

174 files changed

+2749
-2036
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

174 files changed

+2749
-2036
lines changed

‎.openpublishing.redirection.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@
55
"redirect_url": "/azure/ai-foundry/how-to/connections-add",
66
"redirect_document_id": false
77
},
8+
{
9+
"source_path": "articles/ai-foundry/how-to/develop/connections-add-sdk.md",
10+
"redirect_url": "/azure/ai-foundry/how-to/connections-add?pivots=hub-project",
11+
"redirect_document_id": false
12+
},
813
{
914
"source_path": "articles/ai-foundry/how-to/develop/vscode.md",
1015
"redirect_url": "/azure/ai-foundry/how-to/develop/get-started-projects-vs-code",

‎articles/ai-foundry/agents/how-to/tools/browser-automation-samples.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: How to use the Browser Automation tool with the Azure AI Foundry Agent Service
3+
titleSuffix: Azure AI Foundry
4+
description: Learn how to automate browser use and interact with websites using AI Agents.
5+
services: azure-ai-agent-service
6+
manager: nitinme
7+
ms.service: azure-ai-agent-service
8+
ms.topic: how-to
9+
ms.date: 07/29/2025
10+
author: aahill
11+
ms.author: aahi
12+
ms.custom: azure-ai-agents
13+
---
14+
15+
# How to use the Browser Automation tool (preview)
16+
17+
Use this article to find step-by-step instructions and code samples for using the Browser Automation tool in the Azure AI Foundry Agent Service.
18+
19+
## Prerequisites
20+
21+
* The requirements in the [Browser Automation overview](./deep-research.md).
22+
* Your Azure AI Foundry Project endpoint.
23+
24+
[!INCLUDE [endpoint-string-portal](../../includes/endpoint-string-portal.md)]
25+
26+
Save this endpoint to an environment variable named `PROJECT_ENDPOINT`.
27+
28+
* Your playwright connection ID. You can find it in the Azure AI Foundry portal by selecting **Management center** from the left navigation menu. Then select **Connected resources**.
29+
30+
<!--
31+
:::image type="content" source="../../media/tools/deep-research/bing-resource-name.png" alt-text="A screenshot showing the Playwright connection. " lightbox="../../media/tools/deep-research/bing-resource-name.png":::
32+
-->
33+
Save this name to an environment variable named `PLAYWRIGHT_CONNECTION_NAME`.
34+
35+
* [!INCLUDE [model-name-portal](../../includes/model-name-portal.md)]
36+
37+
Save this name to an environment variable named `MODEL_DEPLOYMENT_NAME`.
38+
39+
## Example code
40+
41+
```python
42+
import os
43+
from azure.identity import DefaultAzureCredential
44+
from azure.ai.agents import AgentsClient
45+
from azure.ai.agents.models import MessageRole
46+
from azure.ai.projects import AIProjectClient
47+
48+
project_endpoint = os.environ["PROJECT_ENDPOINT"] # Ensure the PROJECT_ENDPOINT environment variable is set
49+
50+
project_client = AIProjectClient(
51+
endpoint=project_endpoint,
52+
credential=DefaultAzureCredential()
53+
)
54+
55+
playwright_connection = project_client.connections.get(
56+
name=os.environ["PLAYWRIGHT_CONNECTION_NAME"]
57+
)
58+
print(playwright_connection.id)
59+
60+
with project_client:
61+
agent = project_client.agents.create_agent(
62+
model=os.environ["MODEL_DEPLOYMENT_NAME"],
63+
name="my-agent",
64+
instructions="use the tool to respond",
65+
tools=[{
66+
"type": "browser_automation",
67+
"browser_automation": {
68+
"connection": {
69+
"id": playwright_connection.id,
70+
}
71+
}
72+
}],
73+
)
74+
75+
print(f"Created agent, ID: {agent.id}")
76+
77+
thread = project_client.agents.threads.create()
78+
print(f"Created thread and run, ID: {thread.id}")
79+
80+
# Create message to thread
81+
message = project_client.agents.messages.create(
82+
thread_id=thread.id,
83+
role="user",
84+
content="something you want the tool to perform")
85+
print(f"Created message: {message['id']}")
86+
87+
# Create and process an Agent run in thread with tools
88+
run = project_client.agents.runs.create_and_process(
89+
thread_id=thread.id,
90+
agent_id=agent.id,
91+
)
92+
print(f"Run created, ID: {run.id}")
93+
print(f"Run finished with status: {run.status}")
94+
95+
if run.status == "failed":
96+
print(f"Run failed: {run.last_error}")
97+
98+
run_steps = project_client.agents.run_steps.list(thread_id=thread.id, run_id=run.id)
99+
for step in run_steps:
100+
print(step)
101+
print(f"Step {step['id']} status: {step['status']}")
102+
103+
# Check if there are tool calls in the step details
104+
step_details = step.get("step_details", {})
105+
tool_calls = step_details.get("tool_calls", [])
106+
107+
if tool_calls:
108+
print(" Tool calls:")
109+
for call in tool_calls:
110+
print(f" Tool Call ID: {call.get('id')}")
111+
print(f" Type: {call.get('type')}")
112+
113+
function_details = call.get("function", {})
114+
if function_details:
115+
print(f" Function name: {function_details.get('name')}")
116+
print() # add an extra newline between steps
117+
118+
# Delete the Agent when done
119+
project_client.agents.delete_agent(agent.id)
120+
print("Deleted agent")
121+
122+
# Fetch and log all messages
123+
response_message = project_client.agents.messages.get_last_message_by_role(thread_id=thread.id, role=MessageRole.AGENT)
124+
if response_message:
125+
for text_message in response_message.text_messages:
126+
print(f"Agent response: {text_message.text.value}")
127+
for annotation in response_message.url_citation_annotations:
128+
print(f"URL Citation: [{annotation.url_citation.title}]({annotation.url_citation.url})")
129+
```

‎articles/ai-foundry/agents/how-to/tools/browser-automation.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: 'How to use Browser Automation in Azure AI Foundry Agent Service'
3+
titleSuffix: Azure AI Foundry
4+
description: Learn how to automate browser tasks using AI agents.
5+
services: cognitive-services
6+
manager: nitinme
7+
ms.service: azure-ai-agent-service
8+
ms.topic: how-to
9+
ms.date: 07/28/2025
10+
author: aahill
11+
ms.author: aahi
12+
ms.custom: azure-ai-agents
13+
---
14+
15+
# Browser Automation (preview)
16+
17+
> [!WARNING]
18+
> The Browser Automation tool comes with significant security risks. Both errors in judgment by the AI and the presence of malicious or confusing instructions on web pages which the AI encounters may cause it to execute commands you or others do not intend, which could compromise the security of your or other users' browsers, computers, and any accounts to which the browser or AI has access, including personal, financial, or enterprise systems. By using the Browser Automation tool, you are acknowledging that you bear responsibility and liability for any use of it and of any resulting agents you create with it, including with respect to any other users to whom you make Browser Automation tool functionality available, including through resulting agents. We strongly recommend using the Browser Automation tool on low-privilege virtual machines with no access to sensitive data or critical resources.
19+
20+
21+
The Browser Automation tool enables users to perform real-world browser tasks through natural language prompts. Powered by [Microsoft Playwright Workspaces](/azure/playwright-testing/overview-what-is-microsoft-playwright-testing), it facilitates multi-turn conversations to automate browser-based workflows such as searching, navigating, filling forms, and booking.
22+
23+
## How it works
24+
25+
The interaction begins when the user sends a user query to an agent connected to the Browser Automation tool. For example, *"Show me all available yoga classes this week from the following url \<url\>."* Upon receiving the request, Azure AI Foundry Agent Service creates an isolated browser session using your own provisioned Playwright workspace. Each session is sandboxed for privacy and security. The browser session mimics a real user browsing experience, enabling interaction with complex web UIs (for example, class schedules, filters, or booking pages). The browser performs Playwright-driven actions, such as navigating to relevant pages, and applying filters or parameters based on user preferences (such as time, location, instructor). Combining the model with Playwright allows the model to see the browser screen by parsing the HTML or XML pages into DOM documents, make decisions, and perform actions like clicking, typing, and navigating websites. You should exercise caution when using this tool.
26+
27+
An example flow would be:
28+
29+
1. A user sends a request to the model that includes a call to the Browser Automation tool with the URL you want to go to.
30+
31+
1. The Browser Automation tool receives a response from the model. If the response has action items, those items contain suggested actions to make progress toward the specified goal. For example an action might be a screenshot so the model can assess the current state with an updated screenshot or click with X/Y coordinates indicating where the mouse should be moved.
32+
33+
1. The Browser Automation tool executes the action in a sandboxed environment.
34+
35+
1. After executing the action, The Browser Automation tool captures the updated state of the environment as a screenshot.
36+
37+
1. The tool sends a new request with the updated state, and repeats this loop until the model stops requesting actions or the user decides to stop.
38+
39+
The Browser Automation tool supports multi-turn conversations, allowing the user to refine their request and complete a booking.
40+
41+
## Example scenarios:
42+
43+
- Booking & Reservations: Automate form-filling and schedule confirmation across booking portals.
44+
45+
- Product Discovery: Navigate ecommerce or review sites, search by criteria, and extract summaries.
46+
47+
## Setup
48+
49+
1. Create a [Playwright Workspace](https://aka.ms/pww/docs/manage-workspaces) resource.
50+
51+
1. [Generate an access token](https://aka.ms/pww/docs/manage-access-tokens) for the Playwright Workspace resource.
52+
53+
1. Access the workspace region endpoint in the **Workspace Details** page.
54+
1. Give the project identity a "Contributor" role on the Playwright Workspace resource, or [configure a custom role](https://aka.ms/pww/docs/manage-workspace-access).
55+
56+
1. Create a serverless connection in the Azure AI Foundry project with the Playwright workspace region endpoint and the Playwright workspace Access Token.
57+
58+
1. Go to the [Azure AI Foundry portal](https://ai.azure.com/) and select your project. Go to the **Management center** and select **connected resources**.
59+
60+
1. Create a new **Serverless Model** connection, and enter the following information.
61+
62+
* **Target URI**: The Playwright workspace region endpoint, for example `wss://{region}.api.playwright.microsoft.com/playwrightworkspaces/{workspaceId}/browsers`.
63+
64+
For more information on getting this value, see the [PlayWright documentation](https://aka.ms/pww/docs/configure-service-endpoint)
65+
66+
1. * **Key**: [Get the Playwright access token](https://aka.ms/pww/docs/generate-access-token)
67+
68+
For more information on creating a connection, see [Create a connection](../../../how-to/connections-add.md?pivots=fdp-project).
69+
70+
1. Create a Browser Automation tool with your connection ID.
71+
72+
## Transparency note
73+
74+
Review the [transparency note](/azure/ai-foundry/responsible-ai/agents/transparency-note#enabling-autonomous-actions-with-or-without-human-input-through-action-tools) when using this tool. The Browser Automation tool is a tool that can perform real-world browser tasks through natural language prompts, enabling automated browsing activities without human intervention.
75+
76+
Review the [responsible AI considerations](/azure/ai-foundry/responsible-ai/agents/transparency-note#considerations-when-choosing-a-use-case) when using this tool.

0 commit comments

Comments
 (0)