Gestire le sessioni dell'agente ospitato

Questo articolo illustra come creare e gestire sessioni per gli agenti ospitati nel servizio Foundry Agent. Le sessioni forniscono risorse di calcolo sandbox isolate per ogni richiesta, in modo da poter eseguire più conversazioni o attività contemporaneamente senza stato condiviso.

Prerequisiti

Un agente ospitato distribuito con una active versione. Per informazioni su come controllare lo stato della versione, vedere Gestire gli agenti ospitati .

interfaccia della riga di comando di Azure versione 2.80 o successiva, autenticata con az login.

Python SDK: azure-ai-projects>=2.1.0 e azure-identity.

Azure Developer CLI versione 1.23.0 o successiva.
L'estensione degli agenti di Foundry:
```
azd ext install azure.ai.agents
```

Configurare le variabili

Gli esempi di API REST in questo articolo usano az rest per chiamare direttamente gli endpoint del servizio Foundry Agent. Impostare le variabili seguenti prima di eseguire i comandi:

ACCOUNT_NAME="<your-foundry-account-name>"
PROJECT_NAME="<your-project-name>"
BASE_URL="https://${ACCOUNT_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}"
API_VERSION="v1"
RESOURCE="https://ai.azure.com"

Importante

Il --resource parametro è obbligatorio per tutte le az rest chiamate agli endpoint del piano dati del servizio Foundry Agent. Senza di esso, az rest non può derivare il gruppo di destinatari corretto Microsoft Entra dall'URL e l'autenticazione non riesce.

Nota

Le operazioni di sessione sono una funzionalità di anteprima. Includere l'intestazione Foundry-Features: HostedAgents=V1Preview in ogni richiesta REST.

Configurare il client

Tutti gli esempi di Python in questo articolo usano la configurazione client seguente:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project = AIProjectClient(
    endpoint="<your-project-endpoint>",
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

Nota

Le operazioni di sessione utilizzano il sottocliente di anteprima project.beta.agents.

Creare una sessione

Crea una sessione per stabilire una sandbox isolata per il tuo agente. Ogni sessione richiede una chiave di isolamento che identifica il proprietario della sessione. L'endpoint dell'agente risolve automaticamente la versione attiva.

AGENT_NAME="my-agent"

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/sessions?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "x-session-isolation-key=user-123" "Foundry-Features=HostedAgents=V1Preview" \
    --body "{}"

session = project.beta.agents.create_session(
    agent_name="my-agent",
    isolation_key="user-123",
    body={},
)
print(f"Session created (ID: {session.agent_session_id}, status: {session.status})")

Le sessioni vengono create automaticamente quando si richiama un agente tramite azd. La creazione manuale della sessione non è attualmente disponibile come comando autonomo.

La chiave di isolamento è una stringa definita dall'utente. Usarlo per raggruppare sessioni per utente, tenant o qualsiasi altro limite logico.

Richiamare un agente attraverso una sessione

Dopo aver creato una sessione, richiamare l'agente inviando richieste tramite l'API Risposte OpenAI con l'ID sessione associato alla richiesta. Per gli agenti che usano il protocollo Chiamate, vedere Distribuire un agente ospitato : gli agenti di chiamata gestiscono direttamente lo stato e non usano sessioni gestite dalla piattaforma.

AGENT_NAME="my-agent"
SESSION_ID="<session-id>"

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/openai/responses?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --body "{
        \"input\": \"Find me hotels in Seattle under \$200 per night\",
        \"stream\": false,
        \"agent_session_id\": \"${SESSION_ID}\"
    }"

openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Find me hotels in Seattle under $200 per night",
    extra_body={
        "agent_session_id": session.agent_session_id,
    },
)
print(f"Response: {response.output_text}")

Quando si chiama get_openai_client con agent_name, il client viene configurato automaticamente per instradare le richieste all'endpoint dell'agente corretto.

azd ai agent invoke --input "Find me hotels in Seattle under $200 per night"

Elencare sessioni

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

sessions = project.beta.agents.list_sessions(agent_name="my-agent")
for item in sessions:
    print(f"Session: {item.agent_session_id} (status: {item.status})")

L'elenco di sessioni non è attualmente disponibile come comando autonomo. Usare l'API REST o l'SDK.

Ottenere i dettagli della sessione

SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

session = project.beta.agents.get_session(
    agent_name="my-agent",
    session_id="<session-id>",
)
print(f"Session ID: {session.agent_session_id}, Status: {session.status}")

La gestione delle sessioni non è attualmente disponibile come comando autonomo. Usare l'API REST o l'SDK.

Eliminare una sessione

L'eliminazione di una sessione termina la sandbox e ne rilascia le risorse. La chiave di isolamento deve corrispondere alla chiave usata al momento della creazione della sessione.

SESSION_ID="<session-id>"
ISOLATION_KEY="user-123"

az rest --method DELETE \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "x-session-isolation-key=${ISOLATION_KEY}" "Foundry-Features=HostedAgents=V1Preview"

project.beta.agents.delete_session(
    agent_name="my-agent",
    session_id="<session-id>",
    isolation_key="user-123",
)

La gestione delle sessioni non è attualmente disponibile come comando autonomo. Usare l'API REST o l'SDK.

Operazioni dei file di sessione

Caricare e scaricare file nelle sandbox di sessione dell'agente. Ogni file ha come ambito una sessione specifica. La dimensione massima del file per il caricamento è di 50 MB.

Caricare un file

SESSION_ID="<session-id>"

az rest --method PUT \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files/content?api-version=${API_VERSION}&path=data.csv" \
    --resource "${RESOURCE}" \
    --body @data.csv \
    --headers "Content-Type=application/octet-stream" "Foundry-Features=HostedAgents=V1Preview"

project.beta.agents.upload_session_file(
    agent_name="my-agent",
    session_id="<session-id>",
    content_or_file_path="./data.csv",
    path="data.csv",
)

Il content_or_file_path parametro accetta una stringa di percorso del file. L'SDK legge e carica automaticamente il contenuto del file.

azd ai agent files upload --file ./data.csv --target-path data.csv

Elencare i file in una sessione

SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files?api-version=${API_VERSION}&path=." \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

files = project.beta.agents.get_session_files(
    agent_name="my-agent",
    agent_session_id="<session-id>",
    path=".",
)
for entry in files.entries:
    print(f"  {entry.name} (size: {entry.size}, directory: {entry.is_dir})")

azd ai agent files list .

Scaricare un file

SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files/content?api-version=${API_VERSION}&path=data.csv" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --output-file output.csv

content_bytes = b"".join(
    project.beta.agents.download_session_file(
        agent_name="my-agent",
        agent_session_id="<session-id>",
        path="data.csv",
    )
)
with open("./output.csv", "wb") as f:
    f.write(content_bytes)

azd ai agent files download --file data.csv --target-path ./output.csv

Eliminare un file

SESSION_ID="<session-id>"

az rest --method DELETE \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files?api-version=${API_VERSION}&path=data.csv" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

project.beta.agents.delete_session_file(
    agent_name="my-agent",
    agent_session_id="<session-id>",
    path="data.csv",
)

azd ai agent files remove --file data.csv

Passaggi successivi

Gestire gli agenti ospitati

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-05-01