Guida introduttiva: Eseguire il deployment del tuo primo agente ospitato

• Azure developer CLI (azd) 1.27.1 o versione successiva.

• Estensione azd microsoft.foundry . Installare e verificare l'estensione dopo aver installato azd:

  azd ext install microsoft.foundry
  

• Sessione autenticata azd . Accedere dopo aver installato l'estensione:

  azd auth login
  

• Python 3.13 o versione successiva.

• interfaccia della riga di comando di Azure installato ed autenticato:

  az login
  

• I pacchetti SDK di Python usati in questa guida introduttiva:

  pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv
  

• Progetto Foundry esistente con un modello distribuito. Il percorso Python SDK in questa guida introduttiva crea e instrada una versione dell'agente ospitato, ma non esegue lo scaffolding di un nuovo progetto Foundry o crea automaticamente una distribuzione del modello. Se hai bisogno del flusso di provisioning completo, usa la scheda Azure Developer CLI in questo articolo.

• .NET 10 SDK.

• interfaccia della riga di comando di Azure installato ed autenticato:

  az login
  

• Pacchetti .NET usati in questa guida introduttiva.

  dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
  dotnet add package Azure.Identity
  

  Note

  Le API di distribuzione del codice sorgente sono attualmente disponibili in una versione non definitiva di Azure.AI.Projects. Il pacchetto stabile 2.0.x non include queste API.

• Progetto Foundry esistente con un modello distribuito. Il percorso dell'SDK C# crea e instrada una versione dell'agente ospitato, ma non crea un progetto Foundry o una distribuzione di modelli. Per il flusso di provisioning completo, usare la scheda Azure Developer CLI.

• Codice di Visual Studio.
• Microsoft Foundry Toolkit per Visual Studio Code.

• GitHub Copilot'app.

• L'estensione Microsoft Foundry Canvas. Per installarlo, nella GitHub Copilot App aprirePlug-in>, cercare microsoft-foundrye selezionare Installa. Per altre informazioni, vedere Che cos'è Microsoft Foundry Canvas?

• Azure developer CLI (azd) 1.27.1 o versione successiva. Il canvas usa azd per testare e distribuire l'agente.

• Estensione azd microsoft.foundry . Installare e verificare l'estensione dopo aver installato azd:

  azd ext install microsoft.foundry
  

• Host per agente di codifica con lo Skill Microsoft Foundry installato.

• interfaccia della riga di comando di Azure e Azure Developer CLI (azd) installati ed autenticati:

  az login
  azd auth login
  

Passaggio 1: Inizializzare l'agente di esempio

Inizializzare un nuovo agente ospitato usando l'esempio di base di Agent Framework in una directory vuota:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml" --deploy-mode code

Il flusso interattivo richiede:

• Nome dell'agente: Personalizza il nome o accetta l'impostazione predefinita, agent-framework-agent-basic-responses
• Foundry Project: selezionare Crea un nuovo project Foundry o Usa un project foundry esistente
• Tenant: selezionare il tenant Azure
• Sottoscrizione: selezionare la sottoscrizione Azure
• Location: Selezionare un'area Azure
• Modello: selezionare il modello predefinito, gpt-5.4-mini o un altro modello a cui è possibile accedere
• Versione modello: selezionare l'opzione predefinita
• SKU del modello: selezionare un'opzione con quota disponibile che non è Batch, in genere Standard o GlobalStandard
• Capacità di distribuzione: selezionare il valore predefinito10
• Nome della distribuzione: Seleziona il predefinito, gpt-5.4-mini

Al termine, viene visualizzata la definizione dell'agente di intelligenza artificiale aggiunta al progetto azd. Modificare la directory nella cartella dell'agente appena creata.

cd agent-framework-agent-basic-responses

Passaggio 2: Effettuare il provisioning delle risorse di Azure

Effettuare il provisioning delle risorse definite in azure.yaml:

azd provision

Passaggio 3: Testare l'agente in locale

azd ai agent run

Questo comando crea un ambiente virtuale, installa le dipendenze, avvia l'agente usando il startupCommand definito in azure.yamle apre il controllo agente nel browser in modo da poter chattare con l'agente.

Passaggio 4. Eseguire la distribuzione in Servizio Agente Fonderia

Distribuire il codice sorgente dell'agente. azd comprime il codice sorgente in un file ZIP e lo carica in Foundry. Foundry risolve le dipendenze, compila l'agente ospitato in remoto e lo distribuisce:

azd deploy

Al termine dell'esecuzione del comando, l'output mostra i collegamenti al playground dell'agente e all'endpoint dell'agente:

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

Passaggio 5: Richiamare l'agente

1. Inviare la stessa richiesta all'agente distribuito:

   azd ai agent invoke "Write a haiku about deploying cloud applications."
   

   Dovrebbe essere visualizzata una risposta haiku entro pochi secondi.

2. (Facoltativo) Trasmettere i log dei contenitori durante l'interazione con l'agente:

   azd ai agent monitor --follow
   

Passaggio 1: Creare o scegliere un progetto Foundry

1. Aprire il portale foundry e creare un progetto Foundry oppure selezionare uno esistente.

2. Nel progetto distribuire un modello che supporta la chat, gpt-5.4-miniad esempio .

3. Copiare questi valori dal portale:

   • Endpoint del progetto da Panoramica.
   • Nome della distribuzione da Build>Distribuzioni.

Passaggio 2: Scaricare il codice dell'agente di esempio basic

Clona il repository degli esempi di Foundry.

git clone https://github.com/microsoft-foundry/foundry-samples.git

Passaggio 3: Creare un ambiente Python e configurare le impostazioni

Creare un ambiente virtuale e installare i pacchetti di Python necessari per questa guida introduttiva.

Per macOS o Linux:

python -m venv .venv
source .venv/bin/activate
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Per Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Creare una cartella di lavoro per lo script di distribuzione, quindi creare un .env file in tale cartella:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=basic-agent
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/01-basic/src/agent-framework-agent-basic-responses>

Passaggio 4: Distribuire l'agente ospitato con Python

Creare un file denominato deploy_hosted_agent.py nella stessa cartella di lavoro di .env con il contenuto seguente:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  AgentEndpointConfig,
  CodeConfiguration,
  CodeDependencyResolution,
  FixedRatioVersionSelectionRule,
  HostedAgentDefinition,
  ProtocolConfiguration,
  ProtocolVersionRecord,
  ResponsesProtocolConfiguration,
  VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "basic-agent")
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
  zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
  excluded = {".git", ".venv", "__pycache__", ".env", "deploy_hosted_agent.py"}

  with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
    for path in source_dir.rglob("*"):
      if not path.is_file():
        continue
      if any(part in excluded for part in path.parts):
        continue
      zip_file.write(path, path.relative_to(source_dir))

  return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
  for attempt in range(60):
    time.sleep(10)
    details = project_client.agents.get_version(
      agent_name=agent_name,
      agent_version=version,
    )
    status = details["status"]
    print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

    if status == "active":
      return

    if status == "failed":
      raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

  raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
  code_zip_path.open("rb") as code_stream,
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  original_agent_endpoint = None
  created = None

  try:
    created = project_client.agents.create_version_from_code(
      agent_name=agent_name,
      description="Basic hosted agent deployed from local Python source.",
      definition=HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        code_configuration=CodeConfiguration(
          runtime="python_3_14",
          entry_point=["python", "main.py"],
          dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
        ),
        environment_variables={
          "FOUNDRY_PROJECT_ENDPOINT": endpoint,
          "FOUNDRY_MODEL_NAME": model_name,
        },
        protocol_versions=[
          ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
      ),
      code=code_stream,
    )

    print(f"Created hosted agent version {created.version}")

    wait_for_active_version(project_client, created.version)

    original_agent_endpoint = project_client.agents.get(
      agent_name=agent_name
    ).agent_endpoint
    project_client.agents.update_details(
      agent_name=agent_name,
      agent_endpoint=AgentEndpointConfig(
        version_selector=VersionSelector(
          version_selection_rules=[
            FixedRatioVersionSelectionRule(
              agent_version=created.version,
              traffic_percentage=100,
            ),
          ]
        ),
        protocol_configuration=ProtocolConfiguration(
          responses=ResponsesProtocolConfiguration()
        ),
      ),
    )

    print(f"Agent endpoint configured for version {created.version}")

    with project_client.get_openai_client(agent_name=agent_name) as openai_client:
      response = openai_client.responses.create(
        input="Write a haiku about deploying cloud applications.",
      )

    print(f"Agent response: {response.output_text}")
  finally:
    if original_agent_endpoint is not None:
      project_client.agents.update_details(
        agent_name=agent_name,
        agent_endpoint=original_agent_endpoint,
      )
      print("Agent endpoint restored")

    if created is not None:
      project_client.agents.delete_version(
        agent_name=agent_name,
        agent_version=created.version,
        force=True,
      )
      print(f"Deleted hosted agent version {created.version}")

Eseguire lo script:

python deploy_hosted_agent.py

Lo script comprime l'origine dell'esempio, lo carica come nuova versione dell'agente ospitato, attende il completamento del provisioning, indirizza temporaneamente l'endpoint dell'agente ospitato a tale versione, richiama l'agente distribuito e quindi ripristina la configurazione dell'endpoint precedente ed elimina la versione temporanea.

Passaggio 5: Richiamare l'agente

Al termine dello script, usare l'agente ospitato in uno dei modi seguenti:

1. Modificare deploy_hosted_agent.py e modificare il input valore passato a openai_client.responses.create(...), quindi eseguire di nuovo lo script.
2. Se si desidera una versione instradata persistente anziché una distribuzione di convalida temporanea, adattare lo script in modo da saltare i passaggi di ripristino e delete_version(...) dopo avere esaminato le implicazioni relative all'instradamento del traffico.
3. Se è stato usato lo script di esempio come scritto, la configurazione dell'endpoint viene già ripristinata ed eliminata la versione temporanea dell'agente ospitato dopo la convalida.
4. Se è stato creato un gruppo di risorse dedicato per questa guida introduttiva, è possibile eliminare il gruppo di risorse dal portale di Azure dopo che non è più necessaria la distribuzione del progetto o del modello.

Passaggio 1: Creare o scegliere un progetto Foundry

1. Aprire il portale foundry e creare un progetto Foundry oppure selezionare uno esistente.

2. Nel progetto distribuire un modello che supporta la chat, gpt-5.4-miniad esempio .

3. Copiare questi valori dal portale:

   • Endpoint del progetto da Panoramica.
   • Nome della distribuzione da Build>Distribuzioni.

Passaggio 2: Scaricare l'agente hello-world C#

Clonare il repository degli esempi di Foundry:

git clone https://github.com/microsoft-foundry/foundry-samples.git

La sorgente dell'agente è in samples/csharp/hosted-agents/agent-framework/hello-world/src/hello-world-dotnet-agent-framework.

Passaggio 3: Creare un progetto di distribuzione C#

Creare un'applicazione console e installare i pacchetti necessari:

dotnet new console --name HostedAgentDeployer
cd HostedAgentDeployer
dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
dotnet add package Azure.Identity

Impostare i valori usati dall'applicazione di distribuzione. In PowerShell eseguire:

$env:FOUNDRY_PROJECT_ENDPOINT = "<your-project-endpoint>"
$env:FOUNDRY_MODEL_NAME = "<your-model-deployment-name>"
$env:FOUNDRY_HOSTED_AGENT_NAME = "basic-agent"
$env:FOUNDRY_SAMPLE_PATH = "<full-path-to-hello-world-dotnet-agent-framework>"

Per macOS o Linux, eseguire:

export FOUNDRY_PROJECT_ENDPOINT="<your-project-endpoint>"
export FOUNDRY_MODEL_NAME="<your-model-deployment-name>"
export FOUNDRY_HOSTED_AGENT_NAME="basic-agent"
export FOUNDRY_SAMPLE_PATH="<full-path-to-hello-world-dotnet-agent-framework>"

Passaggio 4: Distribuire l'agente ospitato con C#

Sostituire il contenuto di Program.cs con il codice seguente. I pacchetti SDK di .NET e caricano la directory di origine, quindi non è necessario creare manualmente l'archivio ZIP.

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
  ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
  ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");
var agentName = Environment.GetEnvironmentVariable("FOUNDRY_HOSTED_AGENT_NAME")
  ?? "basic-agent";
var samplePath = Environment.GetEnvironmentVariable("FOUNDRY_SAMPLE_PATH")
  ?? throw new InvalidOperationException("FOUNDRY_SAMPLE_PATH isn't set.");

AIProjectClient projectClient = new(
  endpoint: new Uri(projectEndpoint),
  tokenProvider: new DefaultAzureCredential());

HostedAgentDefinition definition = new(cpu: "0.5", memory: "1Gi")
{
  Versions =
  {
    new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0")
  },
  CodeConfiguration = new(
    runtime: "dotnet_10",
    entryPoint: ["dotnet", "hello-world.dll"],
    dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add(
  "FOUNDRY_PROJECT_ENDPOINT", projectEndpoint);
definition.EnvironmentVariables.Add(
  "AZURE_AI_MODEL_DEPLOYMENT_NAME", modelName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;

try
{
  created = await projectClient.AgentAdministrationClient
    .CreateAgentVersionFromCodeAsync(
      agentName: agentName,
      filePath: samplePath,
      metadata: new AgentVersionFromCodeMetadata(definition));
  Console.WriteLine($"Created hosted agent version {created.Version}");

  for (var attempt = 1; attempt <= 60; attempt++)
  {
    await Task.Delay(TimeSpan.FromSeconds(10));
    created = await projectClient.AgentAdministrationClient
      .GetAgentVersionAsync(agentName, created.Version);
    Console.WriteLine(
      $"Provisioning status: {created.Status} (attempt {attempt}/60)");

    if (created.Status == AgentVersionStatus.Active)
    {
      break;
    }
    if (created.Status == AgentVersionStatus.Failed)
    {
      throw new InvalidOperationException("Hosted agent provisioning failed.");
    }
  }

  if (created.Status != AgentVersionStatus.Active)
  {
    throw new TimeoutException(
      "Timed out waiting for the hosted agent version to become active.");
  }

  ProjectsAgentRecord agent = await projectClient.AgentAdministrationClient
    .GetAgentAsync(agentName);
  originalEndpoint = agent.AgentEndpoint;

  AgentEndpointConfiguration endpoint = new()
  {
    VersionSelector = new(
      [new FixedRatioVersionSelectionRule(created.Version, 100)]),
    ProtocolConfiguration = new()
    {
      Responses = new ResponsesProtocolConfiguration()
    }
  };
  await projectClient.AgentAdministrationClient.PatchAgentAsync(
    agentName,
    new PatchAgentOptions { AgentEndpoint = endpoint });
  Console.WriteLine($"Agent endpoint configured for version {created.Version}");

  ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
    .GetProjectResponsesClientForAgentEndpoint(agentName);
  ResponseResult response = await responsesClient.CreateResponseAsync(
    "Write a haiku about deploying cloud applications.");
  Console.WriteLine($"Agent response: {response.GetOutputText()}");
}
finally
{
  if (originalEndpoint is not null)
  {
    await projectClient.AgentAdministrationClient.PatchAgentAsync(
      agentName,
      new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    Console.WriteLine("Agent endpoint restored");
  }

  if (created is not null)
  {
    await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
      agentName,
      created.Version,
      force: true);
    Console.WriteLine($"Deleted hosted agent version {created.Version}");
  }
}

Il codice segue i modelli di caricamento del codice sorgente e di instradamento degli endpoint dall'esempio di agente di codice di Azure SDK per .NET.

Eseguire l'applicazione:

dotnet run

L'applicazione carica l'origine dell'agente C#, attende il provisioning, indirizza l'endpoint dell'agente alla nuova versione, invia un prompt, ripristina la route precedente ed elimina la versione temporanea.

Passaggio 5: Richiamare l'agente

Al termine dell'applicazione, usare l'agente ospitato in uno dei modi seguenti:

1. In Program.cs, modifica il prompt passato a CreateResponseAsync, quindi esegui nuovamente dotnet run.
2. Per mantenere la versione instradata, rimuovi endpoint-restoration e le chiamate DeleteAgentVersionAsync dopo aver esaminato l'impatto dell'instradamento del traffico.
3. Se è stata usata l'applicazione C# come scritto, ripristina la configurazione dell'endpoint ed elimina la versione temporanea dell'agente ospitato dopo la convalida.
4. Se è stato creato un gruppo di risorse dedicato per questa guida introduttiva, eliminare il gruppo di risorse dal portale di Azure quando non è più necessaria la distribuzione del progetto o del modello.

Passaggio 1: Creare un progetto Foundry

1. Aprire il riquadro comandi (Ctrl+MAIUSC+P) e selezionare Foundry Toolkit: Create Project.
2. Selezionare la sottoscrizione Azure.
3. Creare un nuovo gruppo di risorse o selezionarne uno esistente.
4. Immettere un nome per il progetto Foundry.

Passaggio 2: Distribuire un modello

1. Aprire il riquadro comandi e selezionare Foundry Toolkit: Apri catalogo modelli.
2. Cerca gpt-4.1 e seleziona Distribuisci.
3. Nella pagina di distribuzione del modello selezionare Deploy per Microsoft Foundry.

Passaggio 3: Creare un progetto agente ospitato

1. Aprire il riquadro comandi e selezionare Foundry Toolkit: Crea nuovo agente ospitato.
2. Selezionare Python come linguaggio.
3. Per il Framework, selezionare Agent Framework.
4. Selezionare Responses API come tipo di protocollo.
5. Selezionare Basic come codice di esempio.
6. Seleziona il pulsante Avanti.
7. Scegliere una cartella per i file di progetto e immettere un nome per l'agente.
8. In Configurazione dell'ambiente scegliere Configura con Microsoft Foundry. Il contenuto viene popolato automaticamente con il progetto e il modello creati nei passaggi 1 e 2.
9. Selezionare il pulsante Crea.

Viene visualizzata una nuova finestra di VS Code con il progetto come area di lavoro attiva.

Passaggio 4: Installare le dipendenze

Creare un ambiente virtuale e installare i requisiti.

Per macOS o Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Per Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Passaggio 5: Testare l'agente in locale

Premere F5 per avviare il server HTTP locale con il debug abilitato. Foundry Toolkit Agent Inspector si apre per i test interattivi ed è possibile impostare punti di interruzione nel codice.

Per eseguire il server senza eseguire il debug:

python main.py

L'agente ascolta su http://localhost:8088/. Inviare un prompt di test con curl (o qualsiasi client HTTP):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

Passaggio 6. Eseguire la distribuzione in Servizio Agente Fonderia

1. Apri la tavolozza dei comandi e seleziona Foundry Toolkit: Deploy Hosted Agent. Verrà visualizzata una visualizzazione Web di distribuzione.
2. In Metodo di distribuzione selezionare Codice.
3. Selezionare Remote come modalità del pacchetto.
4. Il nome dell'agente viene popolato automaticamente.
5. Seleziona il pulsante Avanti.
6. La pagina Rivedi e distribuisci viene popolata automaticamente.
7. Selezionare il pulsante Distribuisci .

Al termine della distribuzione, l'agente viene visualizzato in Agenti ospitati in Foundry Toolkit Explorer.

Passaggio 7: Richiamare l'agente

1. Nello strumento di esplorazione di Foundry Toolkit espandere Agenti ospitati e selezionare l'agente. La pagina dei dettagli mostra lo stato nella sezione Dettagli della distribuzione.
2. Seleziona la scheda Playground e invia un prompt di prova come Write a haiku about deploying cloud applications..

Il Canvas di Microsoft Foundry ti guida nella creazione e distribuzione di un agente ospitato dal pannello laterale nell'app GitHub Copilot. Quando si effettuano scelte nell'area di disegno, ogni passaggio viene passato a Copilot con il contesto pertinente del progetto Foundry.

Passaggio 1: Aprire l'area di disegno

1. Nell'app GitHub Copilot, chiedere a Copilot di creare un agente ospitato in Foundry. Per esempio:

   Create a Foundry hosted agent using Microsoft Foundry Canvas
   

2. L'area di disegno si apre nel pannello destro. Se non si apre automaticamente, aprirlo dal pannello di destra.

L'area di lavoro guida attraverso tre fasi, che corrispondono ai seguenti passaggi:

• Creare un agente ospitato. Scegli il tuo progetto Foundry e indica a Copilot cosa vuoi realizzare. È possibile iniziare da un prompt prescritto per velocizzare le operazioni.
• Crea l'agente ospitato. Scegli il modello, gli strumenti, le abilità e i vincoli per il tuo agente tra le risorse del tuo progetto Foundry.
• Distribuire e testare. Testate l'agente localmente e, una volta soddisfatti, distribuitelo in Foundry Agent Service.

Passaggio 2: Connettere un progetto Foundry

1. Aprire il menu del progetto canvas e accedere a Azure se richiesto.
2. Seleziona un abbonamento.
3. Selezionare un progetto Foundry. L'area di disegno mantiene questa selezione quando viene riaperta.

Passaggio 3: Creare l'impalcatura dell'agente

Scegliere come iniziare:

• Seleziona Dammi un'idea per creare la struttura di base di un agente ospitato a partire da un'idea generata.
• Selezionare il prompt di esempio Hello world per iniziare da un agente di base.

Copilot genera la struttura del codice dell'agente nel tuo spazio di lavoro in base alla tua scelta.

Passaggio 4: configura l'agente

In questa fase si connette l'agente alle risorse nel progetto Foundry. Ogni selezione invia una richiesta di Copilot, che aggiorna automaticamente il codice e la configurazione dell'agente:

1. Selezionare un modello distribuito per attivare il ragionamento dell'agente.
2. Collega i toolbox di Foundry e i relativi strumenti per fornire capacità all'agente, ad esempio chiamare API o eseguire codice.
3. Connettere le competenze che consentono di creare un pacchetto di logica riutilizzabile per l'agente.
4. Assegna barriere di protezione per applicare controlli di sicurezza e sui contenuti.

Passaggio 5: Testare l'agente in locale

1. Selezionare Ispeziona in locale. Il canvas esegue azd ai agent run nel terminale integrato di Copilot, rimane in attesa dell'agente sulla porta 8088 e integra Agent Inspector.

2. Inviare una richiesta di test, ad esempio:

   Write a haiku about deploying cloud applications.
   

3. Se l’ispettore segnala un errore, copia il messaggio di errore nell’area del prompt dell’area di disegno e chiedi a Copilot di risolvere il problema.

Passaggio 6. Eseguire la distribuzione in Servizio Agente Fonderia

1. Selezionare Distribuisci in Foundry. Il canvas usa azd e Copilot per distribuire l'agente ospitato.
2. Al termine della distribuzione, usare i collegamenti nell'output per aprire l'area di test dell'agente nel portale Foundry.

Passaggio 1: Apri uno spazio di lavoro con Foundry Skill

Aprire una cartella vuota nell'host dell'agente di codifica, ad esempio GitHub Copilot in Visual Studio Code, interfaccia della riga di comando Copilot o Claude Code. Verifica che la skill microsoft-foundry sia disponibile prima di chiedere all'agente di coding di creare risorse di Azure.

Se l'abilità non è disponibile, consulta Usare l'abilità Microsoft Foundry negli agenti di codifica.

Passaggio 2: Chiedi alla skill di creare l'agente ospitato

Chiedi al tuo agente di codifica di utilizzare la competenza per il flusso di lavoro completo dell'agente ospitato:

Use the Microsoft Foundry Skill hosted-agent quick-start workflow to create my
first hosted agent end to end. Verify my environment first, and stop if I need
to sign in myself. Use Python 3.13, Agent Framework, the Responses API, the
Basic sample, and code deployment. Create a new Foundry project unless I provide
an existing project. Use the model deployment from the Basic sample unless I
provide an existing deployment. Test the agent locally, deploy it to Foundry
Agent Service, and invoke it with: "Write a haiku about deploying cloud
applications."

L'agente di codifica deve esaminare gli strumenti Foundry disponibili quando gli strumenti MCP sono disponibili, caricare il flusso di lavoro di avvio rapido dell'agente ospitato e richiedere o impostare valori predefiniti per i valori mancanti, ad esempio la sottoscrizione, l'area geografica, il nome del progetto e se utilizzare un progetto Foundry esistente.

Passaggio 3: Esaminare e approvare il piano

1. Esaminare il piano, i file, i comandi, le risorse Azure e le assegnazioni di ruolo proposte dall'agente di codifica.
2. Per seguire questa guida introduttiva, seleziona Python 3.13, Agent Framework, Responses API, il codice di esempio Basic e la distribuzione Code.
3. Approvare la creazione di risorse a carico dei costi solo dopo aver verificato la sottoscrizione, l'area, il gruppo di risorse, la distribuzione del modello e la quota.
4. Se l'agente di codifica ti chiede di autenticarti, esegui tu stesso/a az login e azd auth login, quindi chiedi all'agente di codifica di continuare.

Passaggio 4: Creare la struttura di base della competenza e testare l'agente

Consentire all'agente di codifica di creare il progetto dell'agente ospitato, effettuare il provisioning delle risorse quando si sceglie un nuovo progetto Foundry, scrivere valori di ambiente locale, preparare l'ambiente locale ed eseguire un smoke test locale. Per gli agenti in Python, il workflow delle competenze usa azd ai agent run per installare le dipendenze durante la prima esecuzione locale.

Il flusso di lavoro deve anche aggiungere il file di linee guida del progetto richiesto dall'host dell'agente di codifica e controllare la configurazione del progetto generata prima del test locale.

Se l'host dell'agente di codifica non riesce a mantenere in esecuzione un server locale per lo smoke test, usare la scheda di Azure Developer CLI in questo articolo per i comandi del test locale. È possibile continuare a eseguire la distribuzione solo dopo aver deciso di convalidare l'agente in modalità remota.

Passaggio 5: Distribuire e richiamare l'agente ospitato

Una volta superato il test preliminare locale, chiedere all'agente di programmazione di completare la distribuzione e la convalida remota:

Continue with the Microsoft Foundry Skill workflow. Deploy the hosted agent to
Foundry Agent Service, show the deployment status and playground link, and invoke
it remotely with: "Write a haiku about deploying cloud applications." If the
skill workflow requires evaluation suite generation before the final summary,
submit the generation job and show me the follow-up eval command.

Al termine del flusso di lavoro, l'agente di codifica deve visualizzare il nome dell'agente ospitato, la versione, lo stato della distribuzione, l'endpoint, il collegamento al playground, le risorse create, la risposta al prompt dei test e qualsiasi comando di completamento della valutazione.

azd down

Quando l'ambiente ha creato il progetto, azd elenca le risorse, richiede la conferma e le elimina in circa 2-5 minuti.

1. Aprire il portale di Azure e passare al gruppo di risorse che contiene l'agente.
2. Selezionare Elimina gruppo di risorse, digitare il nome del gruppo di risorse da confermare e selezionare Elimina.

Il canvas crea un'area di lavoro basata su azd, pertanto è possibile eseguire la pulizia dalla cartella dell'area di lavoro con azd down.

azd down

Quando l'ambiente ha creato il progetto, azd elenca le risorse, richiede la conferma e le elimina in circa 2-5 minuti.

L'abilità Microsoft Foundry non elimina automaticamente le risorse. Può aiutare l'agente di codifica a identificare le risorse create da questa guida rapida e a scegliere il metodo di pulizia corretto. Tu o il tuo agente di coding continuate comunque a eseguire il comando di pulizia dopo averlo esaminato e approvato.

1. Nella cartella del progetto dell'agente ospitato, chiedi all'agente di codifica di verificare le attività di pulizia:

   Use the Microsoft Foundry Skill to identify the Azure resources created for
   this quickstart. Confirm whether azd down is the right cleanup method for
   this project, and show me the resources before any deletion command runs.
   

2. Se il progetto agente ospitato è stato creato con azd e il gruppo di risorse contiene solo risorse di avvio rapido, eseguire:

   azd down
   

3. Approvare l'eliminazione solo dopo aver verificato il gruppo di risorse e le risorse elencate dal comando.

Se il tuo agente di coding non riesce a eseguire i comandi di pulizia, usa la scheda dell'interfaccia della riga di comando per sviluppatori di Azure in questo articolo oppure elimina il gruppo di risorse dal portale di Azure.