Administración de agentes hospedados

• CLI de Azure versión 2.80 o posterior, autenticado con az login.

• SDK de Python: azure-ai-projects>=2.1.0 y azure-identity.

• Azure CLI para desarrolladores versión 1.23.0 o posterior.

• La extensión de Agentes Foundry:

  azd ext install azure.ai.agents
  

Configurar variables

En los ejemplos de la API REST de este artículo se utiliza az rest para llamar directamente a los endpoints del servicio Foundry Agent. Establezca las siguientes variables antes de ejecutar los comandos:

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 respuesta incluye la versión, el estado y la definición más recientes del 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']}")

La información de versión se incluye en la salida de 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']}")

La información de versión se incluye en la salida de 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"}
            ]
        }
    }'

Reemplaza responses con invocations si tu agente usa el protocolo Invocaciones, o incluye ambos para exponer ambos protocolos. Para obtener más información sobre la selección de protocolos, consulte Implementación de un agente hospedado.

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}")

Reemplaza responses con invocations si tu agente utiliza el protocolo Invocaciones, o pasa ambos para exponer ambos protocolos.

Las nuevas versiones se crean automáticamente cuando se ejecuta azd deploy con código o configuración actualizados.

Sondee el estado de la versión después de la creación:

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

Actualmente no se admite como un comando independiente. Use la API REST o el SDK.

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

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

Actualmente no se admite como un comando independiente. Use la API REST o el SDK.

Transmisión de registros desde una sesión de agente específica:

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"

El punto de conexión de logstream devuelve Eventos Enviados por el Servidor (SSE) con marcos event: log. Cada fotograma contiene una carga útil JSON con los campos timestamp, stream (stdout, stderr o status) y message.

Tiempos de espera:

• Duración máxima de la conexión: 30 minutos
• Tiempo de espera de inactividad: 2 minutos

La visualización de registros de contenedor no se admite actualmente a través del SDK de Python. Use la API REST o Azure CLI para desarrolladores.

Supervise un agente en ejecución con información de registro y estado en tiempo real:

azd ai agent monitor

Este comando lee el nombre del agente y la versión desde la entrada de servicio en la configuración de tu proyecto.

El enrutamiento de los endpoints se configura mediante la aplicación de parches al objeto del agente. Usa 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"]
        }
    }'

Configúrelo protocols en ["invocations"] o ["responses", "invocations"] para que coincida con los protocolos que expone el agente.

Para dividir el tráfico entre dos versiones (por ejemplo, 90/10 para un despliegue canario):

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,
)

El enrutamiento de puntos de conexión se configura automáticamente durante azd deploy. Para personalizar la distribución del tráfico, use la API REST o el SDK.

Use el --query parámetro para extraer directamente instance_identity.principal_id de los detalles del agente:

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}")

Utilice la API REST o el SDK de Python para obtener el ID de entidad de identidad del agente.

Asigne un rol en el proyecto Foundry (por ejemplo, para permitir que el agente use recursos del proyecto):

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

Asigne un rol en una cuenta de almacenamiento (por ejemplo, para permitir que el agente lea y escriba blobs):

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

Las asignaciones de roles son una operación de Azure Resource Manager. Use los comandos CLI de Azure que se muestran en la pestaña REST con el valor de agent_identity del paso anterior o use el SDK de Azure Administración de autorización para crear asignaciones de roles mediante programación.

Use el CLI de Azure directamente para crear asignaciones de roles. Recupere el identificador principal de identidad del agente mediante la API REST o Python SDK y, a continuación, ejecute az role assignment create como se indica en la pestaña REST.

Enumere los roles asignados a la identidad del agente en el proyecto 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

Enumere los roles asignados a la identidad del agente en una cuenta de almacenamiento:

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

Use los comandos CLI de Azure que se muestran en la pestaña REST para comprobar las asignaciones de roles.

Use el CLI de Azure directamente para comprobar las asignaciones de roles como se muestra en la pestaña REST.