Guida introduttiva: Creare un agente di ricerca Web

Importante

Gli elementi contrassegnati come anteprima in questo articolo sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio e Microsoft non lo consiglia per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

In questo argomento di avvio rapido si crea un progetto Microsoft Foundry, si esegue il deploy di un modello e si compila e si testa un agente di ricerca Web. È anche possibile riutilizzare un progetto esistente e una distribuzione del modello. L'agente usa la ricerca Web per trovare le informazioni pubbliche correnti e una competenza riutilizzabile per preferire origini primarie, controllare le date e citare prove. L'harness Microsoft Copilot coordina il flusso di lavoro degli strumenti e delle competenze dell'agente. La risorsa rimane un agente di prompt che viene richiamato tramite l'API Risposte.

Prerequisites

  • Una sottoscrizione di Azure. Creane uno gratis.
  • Autorizzazione per creare gruppi di risorse, risorse Foundry e distribuzioni di modelli e per assegnare ruoli di progetto nella sottoscrizione. Ad esempio, Collaboratore e Amministratore del controllo degli accessi basato sui ruoli forniscono autorizzazioni per la creazione di risorse e l'assegnazione di ruoli. Se si riutilizza un progetto esistente e una distribuzione del modello, è invece necessario il ruolo Utente Foundry in tale progetto.
  • Quota del modello disponibile in un'area supportata dal Copilot harness. Questa guida introduttiva usa Canada centrale e gpt-5.4-mini. Se si sceglie un'altra area o un altro modello, verificare che supporti l'harness, il ragionamento e il tool calling.
  • Autorizzazione della tua organizzazione a usare la ricerca sul Web. La ricerca Web prevede costi e termini aggiuntivi e flussi di dati al di fuori del limite di conformità Azure. Per informazioni generali, vedere Gestione dei dati di ricerca Web e controlli di amministratore.

Creare un gruppo di risorse

Se si dispone già di un progetto Foundry in un'area supportata, passare a Distribuire un modello.

Usare un gruppo di risorse dedicato per poter eliminare insieme le risorse di avvio rapido al termine.

  1. Aprire il portale Azure ed eseguire l'accesso.
  2. Cercare Gruppi di risorse, aprire il servizio e selezionare Crea.
  3. Selezionare la sottoscrizione.
  4. Immettere un nome univoco del gruppo di risorse, ad esempio rg-research-<unique-suffix>.
  5. Impostare Regione su Canada Central.
  6. Selezionare Rivedi + crea, quindi Crea. Attendere la conferma che il portale ha creato il gruppo di risorse.

Creare un progetto Foundry

  1. Aprire Microsoft Foundry, accedere e verificare che l'interruttore New Foundry sia attivato.

  2. Selezionare Crea nuovo progetto dal selettore di progetto. Se si apre Foundry per la prima volta, usare l'opzione create-project nella pagina iniziale.

  3. Inserisci un nome Project, come research-<unique-suffix>.

  4. Espandere Opzioni avanzate e impostare:

    Impostazione Value
    Risorsa Foundry Nome univoco globale, ad esempio research-<unique-suffix>-resource
    Area geografica Canada centrale
    Subscription Sottoscrizione usata per il gruppo di risorse
    Gruppo di risorse Il gruppo di risorse che hai creato
  5. Selezionare Crea e attendere il completamento della creazione. Se viene visualizzata una finestra di dialogo di benvenuto, selezionare Inizia per aprire la home page del progetto.

L'area del progetto deve supportare il framework Copilot. Non accettare un'area predefinita senza controllarla.

Distribuire un modello

Se il progetto ha già una distribuzione compatibile del modello, prendere nota del nome e passare a Creare l'agente prompt.

  1. Selezionare Build>Modelli.
  2. Selezionare Distribuisci>Distribuisci un modello di base.
  3. Cerca e seleziona gpt-5.4-mini.
  4. Selezionare Distribuisci>impostazioni personalizzate per esaminare le impostazioni di distribuzione.
  5. Usare gpt-5.4-mini come nome di distribuzione e Global Standard come tipo di distribuzione.
  6. Impostare Limite di token al minuto su 100000, se la quota lo consente. Questo workflow di ricerca effettua diverse chiamate a modelli e strumenti. Un limite inferiore può causare errori di limitazione della frequenza; se ne riscontri uno, attendi prima di riprovare o aumenta il limite entro la quota.
  7. Selezionare Distribuisci e attendere il completamento della distribuzione.

L'inferenza standard globale non è limitata all'area del progetto. Scegliere un tipo di implementazione che soddisfi i requisiti di elaborazione dei dati dell'organizzazione.

Crea l'agente prompt

  1. Torna alla pagina Home del progetto.

  2. Nella home page del progetto, in Compila un agente, selezionare Crea un agente.

  3. Immettere un nome agente univoco.

  4. Mantenere la modalità di interazione impostata su Testo.

  5. Selezionare Usa harness Microsoft Copilot.

  6. Selezionare Create per aprire il playground.

  7. In Modello selezionare un modello distribuito che soddisfi i prerequisiti. Se si prova sia questo flusso di lavoro che il flusso di lavoro di Azure Developer CLI, selezionare la stessa distribuzione del modello in entrambi.

  8. Nelle Istruzioni, immettere:

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

Creare la skill di ricerca

  1. Nella sezione Strumenti del playground selezionare Aggiungi>Aggiungi competenze.

  2. Nella scheda Nuova capacità selezionare Capacità di scrittura.

  3. Immettere un nome univoco, ad esempio official-source-research-<unique-suffix>.

  4. Immettere questa descrizione: Research current public information with web search and cite authoritative sources.

  5. Aggiungere queste istruzioni:

    # 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. Seleziona Crea. La nuova competenza viene associata all'agente e salvata nel progetto per il riutilizzo.

  1. Nella sezione Strumenti del playground selezionare Aggiungi>Aggiungi strumenti.
  2. Nella scheda Configurato, selezionare Ricerca Web, quindi selezionare Aggiungi strumento.
  3. Mantenere selezionata l'opzione Cerca sul Web con Ricerca Bing e quindi selezionare Aggiungi.
  4. Selezionare Salva e avvia una nuova chat e quindi attendere la nuova versione attiva prima di testarla.

In Strumenti verificare che siano elencati gli strumenti Harness, la ricerca Web e la skill di ricerca.

Testare il flusso di lavoro di ricerca

Invia questo prompt nella chat dell'agente:

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.

Verificare che la risposta:

  • Usa le informazioni correnti anziché basarsi solo sulla memoria del modello.
  • Cita le fonti ufficiali python.org per il rilascio e le pagine Novità.
  • Comprende la versione, la data di rilascio e due modifiche con fonte specificata.
  • Segnala incertezza invece di inventare un fatto se le fonti sono incomplete o incoerenti.

Selezionare Tracce sotto la risposta. Nei dettagli della risposta completata verificare che le chiamate dello strumento includano skill e ricerca Web. È possibile visualizzare questi dettagli della risposta senza Application Insights. Il tracciamento distribuito completo richiede una connessione ad Application Insights e non è necessario per questa guida introduttiva.

Pulire le risorse

Se è stato creato un gruppo di risorse dedicato per questa guida introduttiva:

  1. Nel portale di Azure aprire Gruppi di risorse e selezionare il gruppo di avvio rapido.
  2. Verificare che contenga solo le risorse da eliminare.
  3. Selezionare Elimina gruppo di risorse, immettere il nome del gruppo e confermare l'eliminazione.

L'eliminazione del gruppo elimina la risorsa Foundry, il progetto, la distribuzione del modello, gli agenti, le competenze e qualsiasi altra risorsa in tale gruppo.

Se è stato riutilizzato un progetto esistente o condiviso, eliminare solo l'agente di avvio rapido e la capacità dagli elenchi degli agenti e delle capacità del progetto. Se richiesto, confermare la terminazione delle sessioni dell'agente dopo che le richieste sono terminate. Non eliminare il progetto condiviso, la distribuzione del modello o il gruppo di risorse.

Per il progetto completato e uno smoke test automatizzato, vedere l'esempio di guida introduttiva a alla ricerca web.

Prerequisiti aggiuntivi

  • Una shell Bash. I comandi in questo pivot usano la sintassi Bash.

  • Azure Developer CLI (azd) versione 1.37.0 o successiva. Se non è installato, usare il comando per il sistema operativo:

    Sistema operativo Comando di installazione
    Windows (PowerShell, prima di aprire Bash) winget install microsoft.azd
    macOS brew tap azure/azd && brew install azd
    Linux curl -fsSL https://aka.ms/install-azd.sh \| bash
  • Estensioni foundry, installate nella sezione successiva, tra cui azure.ai.agents versione 1.0.0-beta.22 o successiva, azure.ai.projects versione 1.0.0-beta.15 o successiva e azure.ai.skills versione 1.0.0-beta.9 o successiva. Il bundle microsoft.foundry comprende questi comandi.

Installare le estensioni Foundry e accedere

Installare il bundle dell'estensione Foundry dal registro predefinito delle estensioni, aggiornarne le dipendenze e quindi eseguire l'autenticazione in Azure:

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

Abilitare l'anteprima Copilot harness nella shell Bash corrente:

export AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS=true

Impostare di nuovo questa variabile di ambiente quando si apre una nuova shell o si eseguono questi comandi in un processo di integrazione continua.

Verificare le versioni installate di azd e dell'estensione:

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

Impostare i nomi degli agenti

Usare lo stesso suffisso univoco nei nomi dell'agente e delle competenze:

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

Usare nomi univoci all'interno del progetto. La distribuzione con un nome agente esistente crea un'altra versione dell'agente. La distribuzione con un nome di skill esistente crea un'altra versione non modificabile di tale skill.

Inizializzare il progetto dell'agente

Scegliere uno dei percorsi di installazione seguenti. Entrambi i percorsi proseguono in Creare la capacità di ricerca.

Creare un nuovo progetto Foundry e il deployment del modello

Inizializzare un progetto prompt agent senza un ID progetto esistente:

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"

Il comando crea il progetto locale e azure.yaml. Se segnala che la sottoscrizione, la posizione o la configurazione del modello è differita, completare i comandi seguenti prima della distribuzione. Non eseguire di nuovo init.

Impostare l'ID sottoscrizione, l'area, il nome del nuovo gruppo di risorse e il nome del progetto:

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"

Trova l'ID della sottoscrizione nel portale di Azure alla voce Sottoscrizioni. Usare un nuovo nome del gruppo di risorse, non un gruppo contenente le risorse che è necessario conservare.

Dichiarare la distribuzione del modello:

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

Capacità 100 assegna 100.000 token al minuto per questo modello. Ridurlo se necessario per adattarlo alla quota; con un limite inferiore può essere necessario attendere prima di riprovare una richiesta soggetta a limitazione della frequenza. L'inferenza standard globale non è limitata al Canada centrale.

Questi comandi configurano le risorse; azd up le crea dopo aver configurato l'harness, la ricerca Web e la skill.

Usare un progetto Foundry esistente e una distribuzione del modello

Usare questo percorso anziché la procedura per un nuovo progetto. Nel portale di Azure aprire il progetto Foundry e copiarne l'ID risorsa da Proprietà. In Foundry, selezionare Crea>Modelli e prendere nota del nome di una distribuzione compatibile. Impostare entrambi i valori:

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

Inizializzare l'agente rispetto a tali risorse esistenti:

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"

Il comando crea una directory di progetto locale contenente azure.yaml e ha come destinazione il progetto Foundry esistente. Non crea una nuova risorsa Foundry o una distribuzione del modello.

Creare la skill di ricerca

Creare una cartella per la skill.

mkdir -p "skills/$SKILL_NAME"

In quella cartella creare un file denominato SKILL.md. Sostituire <unique-suffix> con lo stesso suffisso usato 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.

La skill definisce un metodo di ricerca riutilizzabile. La ricerca Web fornisce le informazioni correnti su cui opera il metodo.

Configurare l'harness, la ricerca Web e la competenza

In azure.yamlaggiungere la competenza come servizio di pari livello. Aggiornare quindi il servizio generato azure.ai.agent facendolo dipendere dalla skill, selezionare il Copilot harness e aggiungere lo strumento di ricerca Web. Mantenere il progetto generato, il modello, il nome e altri campi.

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

Usare le chiavi effettive del progetto e del servizio generate se differiscono dall'esempio. Il campo archive del servizio skill punta alla directory che contiene SKILL.md. azd crea un pacchetto della directory e pubblica una versione non modificabile della competenza durante la distribuzione. La ricerca Web generale non richiede una connessione di progetto separata. La voce web_search a parte della definizione dell'agente di prompt ed è separata dalla dipendenza del servizio della competenza.

L'elenco skills dell'agente collega la competenza. Il suo elenco uses garantisce che azd distribuisca la competenza prima dell'agente. Entrambi gli elenchi fanno riferimento alla chiave del servizio della skill.

Esaminare la definizione dell'agente

Aprire azure.yamlo stamparlo dal terminale:

cat azure.yaml

Verificare che il servizio agente abbia kind: prompt, harness.type: microsoft_copilot_preview, type: web_search in tools e la chiave del servizio skill sia in entrambi uses e skills. Verificare anche che il servizio skill punti alla cartella che contiene SKILL.md.

Distribuire l'agente

Creare le risorse configurate e distribuire la skill e l'agente:

azd up --no-prompt

Attendere che il comando segnali che la distribuzione è stata completata correttamente.

Per il percorso del nuovo progetto, azd crea il gruppo di risorse, la risorsa Foundry, il progetto e la distribuzione del modello. Per il percorso del progetto esistente, riutilizza il progetto e il modello. Entrambi i percorsi pubblicano la skill e l'agent.

Esaminare e invocare l'agente

Esamina l'agente distribuito come JSON strutturato:

azd ai agent show --output json

Verificare che l'agente sia abilitato, che la versione più recente sia attiva e che la relativa definizione contenga:

  • kind: prompt
  • harness.type: microsoft_copilot_preview
  • Un riferimento di primo livello alla versione non modificabile della tua competenza di ricerca
  • Uno web_search strumento

Avviare una nuova conversazione e richiamare l'agente:

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."

Verificare che la risposta:

  • Usa le informazioni correnti invece di basarsi solo sulla memoria del modello
  • Cita le origini python.org ufficiali per le pagine della release e Novità
  • Include la versione, la data di rilascio e due modifiche provenienti da fonti
  • Segnala incertezza invece di inventare un fatto se le fonti sono incomplete o incoerenti

Per esaminare le chiamate agli strumenti, aprire Microsoft Foundry, selezionare il progetto, quindi Build>agenti e l'agente. Selezionare Traces e aprire la conversazione completata. Verificare che contenga skill e chiamate agli strumenti di ricerca Web. Un nuovo progetto può visualizzare i dettagli delle risposte senza dati di traccia distribuiti; La connessione di Application Insights è facoltativa per questa guida introduttiva.

Pulire le risorse

Attendere il completamento delle richieste in esecuzione prima di eseguire la pulizia.

Se è stato seguito il percorso new-project e il gruppo di risorse contiene solo le risorse di questa guida introduttiva, eseguire:

azd down

Esaminare le risorse elencate e confermare l'eliminazione. Questo passaggio elimina le risorse di cui è stato effettuato il provisioning, incluso il progetto e la distribuzione del modello. Non eseguirlo sull'infrastruttura da conservare.

Se è stato seguito il percorso del progetto esistente, eliminare solo l'agente, le relative versioni e la skill:

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

Questi comandi non eliminano il progetto Foundry o la distribuzione del modello. Se è stato usato un progetto condiviso, non eseguire azd down o eliminare risorse usate da altri sviluppatori.