Guida introduttiva: Eseguire il deployment del tuo primo agente ospitato

• Azure Developer CLI (AZD) 1.25.3 o versione successiva.

• Estensione azd microsoft.foundry . Installare e verificare l'estensione dopo l'installazione di AZD:

  azd ext install microsoft.foundry
  

• 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. La procedura tramite l’SDK Python in questa guida introduttiva crea e indirizza una versione dell’agente ospitato, ma non genera la struttura di base di un nuovo progetto Foundry né crea una distribuzione di un modello per te. Se hai bisogno del flusso di provisioning completo, usa la scheda Azure Developer CLI in questo articolo.

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

• 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 valore 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

Una volta completata l'operazione, viene visualizzato il messaggio Definizione dell'agente IA aggiunta correttamente 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

Compilare e distribuire il contenitore dell'agente:

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 di Foundry e creare un progetto Foundry oppure selezionare un progetto 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 in 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>

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 temporanea di convalida, modificare lo script in modo da ignorare i passaggi di ripristino e delete_version(...) dopo aver esaminato le implicazioni relative all'instradamento del traffico.

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 "Framework", seleziona 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. Per "Configurazione 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 (anteprima) in Foundry Toolkit Explorer.

Passaggio 7: Richiamare l'agente

1. In Esplora risorse di Foundry Toolkit, espandi Agenti ospitati (anteprima) e seleziona il tuo 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..

1. 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.
2. 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: 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

azd elenca le risorse eliminate e richiede la conferma. La pulizia richiede 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.

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.