Quickstart: Create a web research agent

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

In this quickstart, you create a Microsoft Foundry project, deploy a model, and build and test a web research agent. You can also reuse an existing project and model deployment. The agent uses web search to find current public information and a reusable skill to prefer primary sources, check dates, and cite evidence. The Microsoft Copilot harness coordinates the agent's tool and skill workflow. The resource remains a prompt agent that you invoke through the Responses API.

Prerequisites

  • An Azure subscription. Create one for free.
  • Permission to create resource groups, Foundry resources, and model deployments, and to assign project roles in your subscription. For example, Contributor and Role Based Access Control Administrator together provide resource-creation and role-assignment permissions. If you reuse an existing project and model deployment, you need the Foundry User role on that project instead.
  • Available model quota in a region supported by the Copilot harness. This quickstart uses Canada Central and gpt-5.4-mini. If you choose another region or model, confirm that it supports the harness, reasoning, and tool calling.
  • Permission from your organization to use web search. Web search has extra costs and terms, and data flows outside the Azure compliance boundary. For background, see web search data handling and administrator controls.

Create a resource group

If you already have a Foundry project in a supported region, skip to Deploy a model.

Use a dedicated resource group so you can delete the quickstart resources together when you finish.

  1. Open the Azure portal and sign in.
  2. Search for Resource groups, open the service, and select Create.
  3. Select your Subscription.
  4. Enter a unique Resource group name, such as rg-research-<unique-suffix>.
  5. Set Region to Canada Central.
  6. Select Review + create, then Create. Wait for confirmation that the portal created the resource group.

Create a Foundry project

  1. Open Microsoft Foundry, sign in, and ensure the New Foundry toggle is on.

  2. Select Create new project from the project selector. If you're opening Foundry for the first time, use the create-project option on the welcome page.

  3. Enter a Project name, such as research-<unique-suffix>.

  4. Expand Advanced options and set:

    Setting Value
    Foundry resource A globally unique name, such as research-<unique-suffix>-resource
    Region Canada Central
    Subscription The subscription you used for the resource group
    Resource group The resource group you created

  5. Select Create and wait for creation to finish. If a welcome dialog appears, select Let's go to open the project home page.

The project region must support the Copilot harness. Don't accept a default region without checking it.

Deploy a model

If your project already has a compatible model deployment, note its name and skip to Create the prompt agent.

  1. Select Build > Models.
  2. Select Deploy > Deploy a base model.
  3. Search for and select gpt-5.4-mini.
  4. Select Deploy > Custom settings to review the deployment settings.
  5. Use gpt-5.4-mini as the deployment name and Global Standard as the deployment type.
  6. Set Tokens per Minute Rate Limit to 100000, if your quota permits. This research workflow makes several model and tool calls. A lower limit can cause rate-limit errors; if you encounter one, wait before retrying or increase the limit within your quota.
  7. Select Deploy and wait for the deployment to finish.

Global Standard inference isn't restricted to the project's region. Choose a deployment type that meets your organization's data-processing requirements.

Create the prompt agent

  1. Return to your project Home page.

  2. On the project home page, under Build an agent, select Create an agent.

  3. Enter a unique agent name.

  4. Keep interaction mode set to Text.

  5. Select Use the Microsoft Copilot harness.

  6. Select Create to open the playground.

  7. In Model, select a deployed model that meets the prerequisites. If you try both this workflow and the Azure Developer CLI workflow, select the same model deployment in both.

  8. In Instructions, enter:

    Use the attached official-source research skill for current-information requests. Use web search and cite the sources you consulted.

Create the research skill

  1. In the playground's Tools section, select Add > Add skills.

  2. On the New skill tab, select Write skill.

  3. Enter a unique name, such as official-source-research-<unique-suffix>.

  4. Enter this description: Research current public information with web search and cite authoritative sources.

  5. Add these instructions:

    # Official-source research

When a request requires current public information:

1. Use web search instead of relying on model memory.
1. Prefer official websites, documentation, and release notes over secondary sources.
1. Check publication and release dates. Don't present an older result as current.
1. Verify important facts with two official sources when possible. If only one is available, say so.
1. Distinguish sourced facts from your own synthesis, and state any uncertainty or source conflict.
1. Return a concise answer, key facts with citations, and a source list with titles, dates, and URLs.

  6. Select Create. The new skill is attached to the agent and saved in the project for reuse.

  1. In the playground's Tools section, select Add > Add tools.
  2. On the Configured tab, select Web search, and then select Add tool.
  3. Keep Search the web with Bing Search selected, and then select Add.
  4. Select Save and start new chat, and then wait for the new active version before testing it.

Under Tools, confirm that Harness tools, Web search, and the research skill are listed.

Test the research workflow

Send this prompt in the agent chat:

What is the latest stable Python release? Use official Python sources. Return its version and release date, summarize two changes, and cite the release page and What's New page.

Verify that the response:

  • Uses current information instead of relying only on model memory.
  • Cites official python.org sources for the release and What's New pages.
  • Includes the version, release date, and two sourced changes.
  • Reports uncertainty instead of inventing a fact if the sources are incomplete or inconsistent.

Select Traces beneath the response. In the completed response details, confirm that the tool calls include skill and web search. You can view these response details without Application Insights. Full distributed tracing requires an Application Insights connection and isn't required for this quickstart.

Clean up resources

If you created a dedicated resource group for this quickstart:

  1. In the Azure portal, open Resource groups and select your quickstart group.
  2. Confirm that it contains only resources you want to delete.
  3. Select Delete resource group, enter the group name, and confirm deletion.

Deleting the group deletes the Foundry resource, project, model deployment, agents, skills, and any other resources in that group.

If you reused an existing or shared project, delete only your quickstart agent and skill from the project's agent and skill lists. If prompted, confirm termination of that agent's sessions after its requests finish. Don't delete the shared project, model deployment, or resource group.

Additional prerequisites

  • A Bash shell. The commands in this pivot use Bash syntax.

  • Azure Developer CLI (azd) version 1.37.0 or later. If it's not installed, use the command for your operating system:

    Operating system Installation command
    Windows (PowerShell, before opening Bash) winget install microsoft.azd
    macOS brew tap azure/azd && brew install azd
    Linux curl -fsSL https://aka.ms/install-azd.sh \| bash

  • Foundry extensions, installed in the next section, including azure.ai.agents version 1.0.0-beta.22 or later, azure.ai.projects version 1.0.0-beta.15 or later, and azure.ai.skills version 1.0.0-beta.9 or later. The microsoft.foundry bundle includes these commands.

Install the Foundry extensions and sign in

Install the Foundry extension bundle from the default extension registry, update its dependencies, and then authenticate to Azure:

azd extension install microsoft.foundry
azd extension update microsoft.foundry
azd auth login

Enable the Copilot harness preview in the current Bash shell:

export AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS=true

Set this environment variable again when you open a new shell or run these commands in a CI job.

Verify the installed azd and extension versions:

azd version
azd ai agent version
azd ai project version
azd ai skill version

Set the agent names

Use the same unique suffix in the agent and skill names:

AGENT_NAME="release-research-<unique-suffix>"
SKILL_NAME="official-source-research-<unique-suffix>"

Use names that are unique within the project. Deploying with an existing agent name creates another version of that agent. Deploying with an existing skill name creates another immutable version of that skill.

Initialize the agent project

Choose one of the following setup paths. Both paths continue at Create the research skill.

Create a new Foundry project and model deployment

Initialize a prompt agent project without an existing project ID:

azd ai agent init "$AGENT_NAME" \
  --no-prompt \
  --kind prompt \
  --agent-name "$AGENT_NAME" \
  --model gpt-5.4-mini \
  --description "Researches current software releases using official public sources." \
  --instructions "Use the attached official-source research skill for current-information requests. Use web search and cite the sources you consulted."

cd "$AGENT_NAME"

The command creates the local project and azure.yaml. If it reports that subscription, location, or model setup is deferred, complete the following commands before deploying. Don't run init again.

Set the subscription ID, region, new resource group name, and project name:

azd env set AZURE_SUBSCRIPTION_ID "<subscription-id>"
azd env set AZURE_LOCATION canadacentral
azd env set AZURE_RESOURCE_GROUP "rg-$AGENT_NAME"
azd env set AZURE_AI_PROJECT_NAME "$AGENT_NAME"

Find your subscription ID in the Azure portal under Subscriptions. Use a new resource group name, not a group containing resources you need to keep.

Declare the model deployment:

azd ai project deployment add \
  --model OpenAI/gpt-5.4-mini \
  --name gpt-5.4-mini \
  --version 2026-03-17 \
  --sku GlobalStandard \
  --capacity 100 \
  --location canadacentral \
  --no-prompt

Capacity 100 assigns 100K tokens per minute for this model. Reduce it if necessary to fit your quota; a lower limit can require waiting before retrying a rate-limited request. Global Standard inference isn't restricted to Canada Central.

These commands configure the resources; azd up creates them after you configure the harness, web search, and skill.

Use an existing Foundry project and model deployment

Use this path instead of the new project steps. In the Azure portal, open your Foundry project and copy its Resource ID from Properties. In Foundry, select Build > Models and note the name of a compatible deployment. Set both values:

PROJECT_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
MODEL_DEPLOYMENT="<model-deployment-name>"

Initialize the agent against those existing resources:

azd ai agent init "$AGENT_NAME" \
  --no-prompt \
  --kind prompt \
  --agent-name "$AGENT_NAME" \
  --project-id "$PROJECT_ID" \
  --model-deployment "$MODEL_DEPLOYMENT" \
  --description "Researches current software releases using official public sources." \
  --instructions "Use the attached official-source research skill for current-information requests. Use web search and cite the sources you consulted."

cd "$AGENT_NAME"

The command creates a local project directory containing azure.yaml and targets the existing Foundry project. It doesn't create a new Foundry resource or model deployment.

Create the research skill

Create a folder for the skill.

mkdir -p "skills/$SKILL_NAME"

In that folder, create a file named SKILL.md. Replace <unique-suffix> with the same suffix that you used in SKILL_NAME.

---
name: official-source-research-<unique-suffix>
description: Research current public information with web search and cite authoritative sources.
---

# Official-source research

When a request requires current public information:

1. Use web search instead of relying on model memory.
1. Prefer official websites, documentation, and release notes over secondary sources.
1. Check publication and release dates. Don't present an older result as current.
1. Verify important facts with two official sources when possible. If only one is available, say so.
1. Distinguish sourced facts from your own synthesis, and state any uncertainty or source conflict.
1. Return a concise answer, key facts with citations, and a source list with titles, dates, and URLs.

The skill defines a reusable research method. Web search supplies the current information that the method operates on.

Configure the harness, web search, and skill

In azure.yaml, add the skill as a sibling service. Then update the generated azure.ai.agent service to depend on the skill, select the Copilot harness, and add the web search tool. Keep the generated project, model, name, and other fields.

services:
  # Keep the generated ai-project service.

  official-source-research-<unique-suffix>:
    host: azure.ai.skill
    uses:
      - ai-project
    archive: ./skills/official-source-research-<unique-suffix>

  <agent-service-name>:
    host: azure.ai.agent
    uses:
      - ai-project
      - official-source-research-<unique-suffix>
    kind: prompt
    instructions: >-
      Use the attached official-source research skill for current-information requests.
      Use web search and cite the sources you consulted.
    harness:
      type: microsoft_copilot_preview
    skills:
      - official-source-research-<unique-suffix>
    tools:
      - type: web_search

Use the actual generated project and service keys if they differ from the example. The skill service's archive field points to the directory that contains SKILL.md. azd packages the directory and publishes an immutable skill version during deployment. General web search doesn't require a separate project connection. The web_search entry is part of the prompt agent definition and is separate from the skill service dependency.

The agent's skills list attaches the skill. Its uses list ensures that azd deploys the skill before the agent. Both lists reference the skill's service key.

Review the agent definition

Open azure.yaml, or print it from the terminal:

cat azure.yaml

Confirm that the agent service has kind: prompt, harness.type: microsoft_copilot_preview, type: web_search in tools, and the skill service key in both skills and uses. Also confirm that the skill service points to the folder that contains SKILL.md.

Deploy the agent

Create the configured resources and deploy the skill and agent:

azd up --no-prompt

Wait for the command to report that the deployment completed successfully.

For the new-project path, azd creates the resource group, Foundry resource, project, and model deployment. For the existing-project path, it reuses the project and model. Both paths publish the skill and agent.

Inspect and invoke the agent

Inspect the deployed agent as structured JSON:

azd ai agent show --output json

Confirm that the agent is enabled, its latest version is active, and its definition contains:

  • kind: prompt
  • harness.type: microsoft_copilot_preview
  • A top-level reference to the immutable version of your research skill
  • A web_search tool

Start a new conversation and invoke the agent:

azd ai agent invoke --new-conversation --no-prompt \
  "What is the latest stable Python release? Use official Python sources. Return its version and release date, summarize two changes, and cite the release page and What's New page."

Verify that the response:

  • Uses current information instead of relying only on model memory
  • Cites official python.org sources for the release and What's New pages
  • Includes the version, release date, and two sourced changes
  • Reports uncertainty instead of inventing a fact if the sources are incomplete or inconsistent

To inspect tool calls, open Microsoft Foundry, select your project, then Build > Agents and your agent. Select Traces and open the completed conversation. Confirm that it contains skill and web search tool calls. A new project can show Responses details without distributed trace data; connecting Application Insights is optional for this quickstart.

Clean up resources

Wait for any running requests to finish before cleaning up.

If you followed the new-project path and the resource group contains only this quickstart's resources, run:

azd down

Review the resources listed and confirm deletion. This step deletes the provisioned resources, including the project and model deployment. Don't run it against infrastructure you need to keep.

If you followed the existing-project path, delete only the agent, its versions, and the skill:

azd ai agent delete --force --no-prompt
azd ai skill delete "$SKILL_NAME" --force --no-prompt

These commands don't delete the Foundry project or model deployment. If you used a shared project, don't run azd down or delete resources that other developers use.

Related content

  • Last updated on