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>"
AGENT_NAME="<your-agent-name>"
BASE_URL="https://${ACCOUNT_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}"
API_VERSION="v1"
RESOURCE="https://ai.azure.com"

az rest --method GET \
    --url "${BASE_URL}/agents?api-version=${API_VERSION}" \
    --resource "${RESOURCE}"

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

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

for agent in project.agents.list():
    print(agent.name)

azd ai agent show

az rest --method GET \
    --url "${BASE_URL}/agents/${AGENT_NAME}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}"

La risposta include la versione, lo stato e la definizione più recenti dell'agente.

agent = project.agents.get(agent_name="my-agent")
print(f"Name: {agent.name}")
print(f"Status: {agent.versions['latest']['status']}")

azd ai agent show

az rest --method GET \
    --url "${BASE_URL}/agents/${AGENT_NAME}/versions/1?api-version=${API_VERSION}" \
    --resource "${RESOURCE}"

agent_version = project.agents.get_version(
    agent_name="my-agent", agent_version="1"
)
print(f"Version: {agent_version.version}")
print(f"Status: {agent_version['status']}")

Le informazioni sulla versione sono incluse nell'output di azd ai agent show.

az rest --method GET \
    --url "${BASE_URL}/agents/${AGENT_NAME}/versions?api-version=${API_VERSION}" \
    --resource "${RESOURCE}"

for version in project.agents.list_versions(agent_name="my-agent"):
    print(f"Version: {version.version}, Status: {version['status']}")

Le informazioni sulla versione sono incluse nell'output di azd ai agent show.

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/versions?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --body '{
        "definition": {
            "kind": "hosted",
            "image": "myregistry.azurecr.io/my-agent:v2",
            "cpu": "1",
            "memory": "2Gi",
            "container_protocol_versions": [
                {"protocol": "responses", "version": "1.0.0"}
            ]
        }
    }'

Sostituire responses con invocations se l'agente usa il protocollo Invocazioni, o includere entrambi per supportare entrambi i protocolli. Per informazioni dettagliate sulla selezione del protocollo, vedere Distribuire un agente ospitato.

from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        image="myregistry.azurecr.io/my-agent:v2",
        container_protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="1.0.0"),
        ],
    ),
)
print(f"Created version: {agent.version}")

Sostituire responses con invocations se l'agente usa il protocollo Invocazioni o passare entrambi per esporre entrambi i protocolli.

Le nuove versioni vengono create automaticamente quando si esegue azd deploy con il codice o la configurazione aggiornati.

Eseguire il polling dello stato della versione dopo la creazione:

import time

def wait_for_version_active(project, agent_name, agent_version, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(10)
        version = project.agents.get_version(
            agent_name=agent_name, agent_version=agent_version
        )
        status = version["status"]
        print(f"Version status: {status} (attempt {attempt + 1})")
        if status == "active":
            return
        if status == "failed":
            raise RuntimeError(f"Version provisioning failed: {dict(version)}")
    raise RuntimeError("Timed out waiting for version to become active")

az rest --method DELETE \
    --url "${BASE_URL}/agents/${AGENT_NAME}/versions/1?api-version=${API_VERSION}" \
    --resource "${RESOURCE}"

project.agents.delete_version(agent_name="my-agent", agent_version="1")

Non attualmente supportato come comando autonomo. Usare l'API REST o l'SDK.

az rest --method DELETE \
    --url "${BASE_URL}/agents/${AGENT_NAME}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}"

project.agents.delete(agent_name="my-agent")

Non attualmente supportato come comando autonomo. Usare l'API REST o l'SDK.

Trasmettere i log da una sessione dell'agente specifica:

AGENT_VERSION="<version>"
SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/${AGENT_NAME}/versions/${AGENT_VERSION}/sessions/${SESSION_ID}:logstream?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" "Accept=text/event-stream"

L'endpoint logstream restituisce Eventi Inviati dal Server (SSE) con event: log frame. Ogni frame contiene un payload JSON con i campi timestamp, stream (stdout, stderr o status) e message.

Timeout:

• Durata massima della connessione: 30 minuti
• Timeout di inattività: 2 minuti

La visualizzazione dei log dei contenitori non è attualmente supportata tramite Python SDK. Usare l'API REST o l'interfaccia della riga di comando per sviluppatori di Azure.

Monitorare un agente in esecuzione con informazioni sullo stato e sul log in tempo reale:

azd ai agent monitor

Questo comando legge il nome e la versione dell'agente dalla voce del azd servizio nella configurazione del progetto.

Il routing degli endpoint viene configurato applicando patch all'oggetto agente. Usare PATCH /agents/{agent_name} con Content-Type: application/merge-patch+json:

az rest --method PATCH \
    --url "${BASE_URL}/agents/${AGENT_NAME}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Content-Type=application/merge-patch+json" "Foundry-Features=AgentEndpoints=V1Preview" \
    --body '{
        "agent_endpoint": {
            "version_selector": {
                "version_selection_rules": [
                    {"agent_version": "1", "traffic_percentage": 100, "type": "FixedRatio"}
                ]
            },
            "protocols": ["responses"]
        }
    }'

Impostare protocols su ["invocations"] o ["responses", "invocations"] in modo che corrisponda ai protocolli esposti dall'agente.

Per suddividere il traffico tra due versioni (ad esempio, 90/10 per una distribuzione canary):

az rest --method PATCH \
    --url "${BASE_URL}/agents/${AGENT_NAME}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Content-Type=application/merge-patch+json" "Foundry-Features=AgentEndpoints=V1Preview" \
    --body '{
        "agent_endpoint": {
            "version_selector": {
                "version_selection_rules": [
                    {"agent_version": "1", "traffic_percentage": 90, "type": "FixedRatio"},
                    {"agent_version": "2", "traffic_percentage": 10, "type": "FixedRatio"}
                ]
            },
            "protocols": ["responses"]
        }
    }'

from azure.ai.projects.models import (
    AgentEndpoint,
    AgentEndpointProtocol,
    FixedRatioVersionSelectionRule,
    VersionSelector,
)

endpoint_config = AgentEndpoint(
    version_selector=VersionSelector(
        version_selection_rules=[
            FixedRatioVersionSelectionRule(
                agent_version="1", traffic_percentage=100
            ),
        ]
    ),
    protocols=[AgentEndpointProtocol.RESPONSES],
)

project.beta.agents.patch_agent_details(
    agent_name="my-agent",
    agent_endpoint=endpoint_config,
)

Il routing degli endpoint viene configurato automaticamente durante azd deploy. Per personalizzare la distribuzione del traffico, usare l'API REST o l'SDK.

Usare il --query parametro per estrarre direttamente dai dettagli dell'agente instance_identity.principal_id :

AGENT_IDENTITY=$(az rest --method GET \
    --url "${BASE_URL}/agents/${AGENT_NAME}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --query "instance_identity.principal_id" \
    --output tsv)

echo "Agent identity principal ID: ${AGENT_IDENTITY}"

agent = project.agents.get(agent_name="my-agent")
agent_identity = agent.instance_identity["principal_id"]
print(f"Agent identity principal ID: {agent_identity}")

Usare l'API REST o il Python SDK per recuperare l'ID principale dell'identità dell'agente.

Assegnare un ruolo al progetto Foundry , ad esempio per consentire all'agente di usare le risorse del progetto:

az role assignment create \
    --assignee-object-id "$AGENT_IDENTITY" \
    --assignee-principal-type ServicePrincipal \
    --role "Azure AI Developer" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/projects/<project-name>"

Assegnare un ruolo a un account di archiviazione (ad esempio, per consentire all'agente di leggere e scrivere blob):

az role assignment create \
    --assignee-object-id "$AGENT_IDENTITY" \
    --assignee-principal-type ServicePrincipal \
    --role "Storage Blob Data Contributor" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"

Le assegnazioni di ruolo sono un'operazione Azure Resource Manager. Usare i comandi interfaccia della riga di comando di Azure visualizzati nella scheda REST con il valore agent_identity del passaggio precedente oppure usare Azure Gestione autorizzazioni SDK per creare assegnazioni di ruolo a livello di codice.

Usare il interfaccia della riga di comando di Azure direttamente per creare assegnazioni di ruolo. Recuperare l'ID del principale di identità dell'agente usando l'API REST o l'SDK di Python, quindi eseguire az role assignment create come illustrato nella scheda REST.

Elencare i ruoli assegnati all'identità dell'agente nel progetto Foundry:

az role assignment list \
    --assignee "$AGENT_IDENTITY" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/projects/<project-name>" \
    --output table

Elencare i ruoli assegnati all'identità dell'agente in un account di archiviazione:

az role assignment list \
    --assignee "$AGENT_IDENTITY" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>" \
    --output table

Usare i comandi interfaccia della riga di comando di Azure visualizzati nella scheda REST per verificare le assegnazioni di ruolo.

Usare direttamente il interfaccia della riga di comando di Azure per verificare le assegnazioni di ruolo, come illustrato nella scheda REST.