Gerenciar agentes hospedados

• CLI do Azure versão 2.80 ou posterior, autenticada com az login.

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

• Azure CLI do Desenvolvedor versão 1.23.0 ou posterior.

• A extensão de agentes do Foundry:

  azd ext install azure.ai.agents
  

Configurar variáveis

Os exemplos da API REST neste artigo usam az rest para chamar diretamente os endpoints do Foundry Agent Service. Defina as seguintes variáveis antes de executar os 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}"

A resposta inclui a versão, o status e a definição mais recentes do 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']}")

As informações de versão são incluídas na saída 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']}")

As informações de versão são incluídas na saída 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"}
            ]
        }
    }'

Substitua o responses por um invocations se o agente usar o protocolo Invocations, ou inclua os dois para expor os dois protocolos. Para obter detalhes sobre a seleção de protocolo, consulte Implantar um 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}")

Substitua o responses por um invocations se o agente usar o protocolo Invocations, ou passe os dois para expor os dois protocolos.

As novas versões são criadas automaticamente quando você executa azd deploy com o código ou a configuração atualizados.

Sonde o status da versão após a criação:

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

Não há suporte no momento como um comando autônomo. Use a API REST ou o SDK.

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

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

Não há suporte no momento como um comando autônomo. Use a API REST ou o SDK.

Transmitir logs de uma sessão 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"

O ponto de extremidade logstream retorna Eventos Enviados pelo Servidor (SSE) com quadros event: log. Cada quadro contém um conteúdo JSON com os campos `timestamp`, `stream` (`stdout`, `stderr` ou `status`) e `message`.

Tempos limite:

• Duração máxima da conexão: 30 minutos
• Tempo limite ocioso: 2 minutos

No momento, não há suporte para a exibição de logs de contêiner por meio do SDK do Python. Use a API REST ou a CLI do Desenvolvedor Azure.

Monitore o status e as informações de log de um agente em execução em tempo real.

azd ai agent monitor

Esse comando lê o nome do agente e a versão da entrada de serviço azd na configuração do projeto.

O roteamento do endpoint é configurado por meio da modificação do objeto do agente. Use PATCH /agents/{agent_name} com 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"]
        }
    }'

Defina protocols como ["invocations"] ou ["responses", "invocations"] para corresponder aos protocolos expostos pelo agente.

Para dividir o tráfego entre duas versões (por exemplo, 90/10 para uma implantação canária):

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

O roteamento de endpoint é configurado automaticamente durante azd deploy. Para personalizar a distribuição de tráfego, use a API REST ou o SDK.

Use o --query parâmetro para extrair diretamente instance_identity.principal_id dos detalhes do 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}")

Use a API REST ou o Python SDK para recuperar a ID da identidade principal do agente.

Atribua uma função no projeto Foundry (por exemplo, para permitir que o agente use recursos de projeto):

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

Atribuir uma função em uma conta de armazenamento (por exemplo, para permitir que o agente leia e escreva 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>"

As atribuições de função são uma operação do Azure Resource Manager. Use os comandos CLI do Azure mostrados na guia REST com o valor agent_identity da etapa anterior ou use o SDK Azure Authorization Management para criar atribuições de função programaticamente.

Use o CLI do Azure diretamente para criar atribuições de função. Recupere a ID principal da identidade do agente usando a API REST ou o SDK do Python, e execute az role assignment create como mostrado na guia REST.

Liste as funções atribuídas à identidade do agente no projeto 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

Liste as funções atribuídas à identidade do agente em uma conta de armazenamento:

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

Use os comandos CLI do Azure mostrados na guia REST para verificar as atribuições de função.

Use o CLI do Azure diretamente para verificar as atribuições de função, conforme mostrado na guia REST.