Gerir agentes alojados

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

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

• Azure Developer CLI versão 1.23.0 ou posterior.

• A extensão para agentes do Foundry:

  azd ext install azure.ai.agents
  

Configurar variáveis

Os exemplos de APIs 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 mais recente do software agente, o seu estado e a definição.

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

A informação de versão está incluída 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']}")

A informação de versão está incluída 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 responses por invocations se o seu agente usa o protocolo Invocations, ou inclua ambos para expor ambos os protocolos. Para detalhes sobre a seleção de protocolos, veja Implementar 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}")

Substitui responses por invocations se o teu agente usa o protocolo Invocations, ou passa ambos para expor ambos os protocolos.

Novas versões são criadas automaticamente quando executa azd deploy com código ou configuração atualizado.

Consulta o estado 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")

Atualmente não é suportado como comando autónomo. Utilize a API REST ou SDK.

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

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

Atualmente não é suportado como comando autónomo. Utilize a API REST ou SDK.

Transmita os registos de uma sessão específica de um agente

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 endpoint do logstream devolve Servidor-Envio de Eventos (SSE) com estruturas event: log. Cada trama contém uma carga útil JSON com timestamp, stream (stdout, stderr, ou status), e campos message.

Tempo de espera

• Duração máxima da ligação: 30 minutos
• Tempo limite de inatividade: 2 minutos

A visualização de registos de contentores não é atualmente suportada através do SDK Python. Use a API REST ou a CLI do Azure Developer.

Monitorize um agente em execução com informações de estado e registo em tempo real:

azd ai agent monitor

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

O encaminhamento dos endpoints é configurado através da aplicação de patches ao objeto agente. Uso 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 para ["invocations"] ou ["responses", "invocations"] para corresponder aos protocolos que o seu agente expõe.

Para dividir o tráfego entre duas versões (por exemplo, 90/10 para um lançamento canário):

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 encaminhamento do endpoint é configurado automaticamente durante azd deploy. Para personalizar a distribuição do tráfego, utilize a API ou SDK REST.

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 SDK do Python para recuperar o ID da identidade principal do agente.

Atribuir um papel ao projeto Foundry (por exemplo, para permitir que o agente utilize os recursos do 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 a 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ções são uma operação do Azure Resource Manager. Use os comandos CLI do Azure mostrados no separador REST com o valor agent_identity do passo anterior, ou use o SDK Azure Authorization Management para criar atribuições de funções programáticamente.

Use diretamente a CLI do Azure para criar atribuições de funções. Recupere o ID principal da identidade do agente usando a API REST ou Python SDK, depois execute az role assignment create como mostrado no separador 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 numa 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 no separador REST para verificar atribuições de funções.

Use diretamente a CLI do Azure para verificar as atribuições de funções como mostrado no separador REST.