Invocar um agente hospedado com a CLI do desenvolvedor do Azure

Use azd ai agent invoke para enviar mensagens ao agente, seja a versão implantada no Microsoft Foundry ou uma instância em execução local. Você aprenderá a escolher um agente, usar endpoints diretos, gerenciar sessões, enviar arquivos, fixar versões e inspecionar respostas brutas.

Pré-requisitos

Chamar o agente implantado

  • Envie um prompt para o agente implantado:

    azd ai agent invoke "What is Microsoft Foundry?"

Invocar um agente específico

  • Se o projeto contiver vários agentes, especifique qual deles invocar:

    azd ai agent invoke my-agent "What is Microsoft Foundry?"

Chamar um endpoint específico implantado

Quando você quiser invocar um agente implantado específico sem depender do ambiente ativo do azd ou azure.yaml, use --agent-endpoint para apontar diretamente para a URL do agente implantado. Esse padrão é útil de um script fora do projeto, de um agente de codificação ou quando você testa uma versão específica do agente.

  • Informe o ponto de extremidade do agente implantado:

    azd ai agent invoke \
   --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
   "Summarize today's release notes."

    --agent-endpoint substitui o ambiente do azd e a resolução de azure.yaml, portanto não é necessário estar dentro de um diretório de projeto azd para utilizá-lo.

Invocar localmente

  • Invoque um agente local:

    azd ai agent invoke --local "Hello!"

    O agente já deve estar em execução com azd ai agent run em outro terminal.

Invocar em uma porta local personalizada

  • Se o agente estiver em execução em uma porta diferente da padrão, passe --port:

    azd ai agent invoke --local --port 9090 "Hello!"

Escolher um protocolo

O protocolo usado para invocação é determinado pelo protocols campo do azure.ai.agent serviço em azure.yaml.

  • responses -- envia uma solicitação de API de Respostas OpenAI padrão com {"input": "your message"}. O histórico de conversas é gerenciado automaticamente.
  • invocations -- envia qualquer payload esperado pelo código do seu agente. Use --input-file (-f) com um arquivo JSON que corresponda ao esquema definido pelo manipulador.

Para agentes invocations, consulte o README do exemplo ou analise o ponto de entrada do manipulador para identificar o payload esperado.

  • Se o agente implementar vários protocolos, passe --protocol (-p) para escolher:

    azd ai agent invoke --protocol invocations -f request.json

Gerenciar sessões

As sessões são mantidas por agente. Quando você invoca um agente, azd salva a ID da sessão localmente para que a próxima invoke continue automaticamente a mesma sessão e mantenha o histórico de conversas entre chamadas.

Iniciar uma nova sessão

  • Descarte a sessão salva e comece novamente:

    azd ai agent invoke --new-session "Start fresh"

Usar uma ID de sessão específica

  • Passe uma ID de sessão existente:

    azd ai agent invoke --session-id my-session-123 "Continue conversation"

Enviar um arquivo como entrada

Para cargas estruturadas ou grandes, especialmente com o invocations protocolo, passe um arquivo JSON.

  1. Enviar um arquivo:

    azd ai agent invoke -f request.json

  2. Ou envie um arquivo para um agente específico:

    azd ai agent invoke my-agent -f request.json

Invocar uma versão implantada

Quando um agente possuir várias versões implantadas, fixe uma versão específica usando --version. azd cria ou reutiliza uma sessão apoiada por essa versão, de modo que cada versão mantém seu próprio estado de conversa.

  • Fixar uma versão:

    azd ai agent invoke --version 3 "Use the v3 prompt"

    --version não pode ser combinado com --local ou --session-id porque as sessões estão associadas a uma versão quando são criadas.

Definir um tempo limite personalizado

  • Defina um tempo limite em segundos:

    azd ai agent invoke --timeout 300 "Process this large dataset"

    O tempo limite padrão é de 1800 segundos (30 minutos). Use --timeout 0 para não definir limite de tempo.

Transmitir chaves de isolamento

Os agentes configurados com isolamento baseado em cabeçalho do Foundry exigem chaves por usuário ou por chat em cada solicitação. Passe-os com --user-isolation-key e --chat-isolation-key.

  • Envie chaves de isolamento com a requisição:

    azd ai agent invoke \
   --user-isolation-key "$USER_KEY" \
   --chat-isolation-key "$CHAT_KEY" \
   "Hello!"

Para obter o padrão completo, incluindo como sessões, arquivos e comandos de monitor usam os mesmos sinalizadores, consulte Passar chaves de isolamento para um agente hospedado.

Inspecionar a resposta HTTP bruta

Quando for necessário visualizar exatamente a resposta retornada pelo servidor, incluindo cabeçalhos de resposta como a versão do agente, a linha de status e o corpo sem alterações, informe --output raw (-o raw).

  • Solicitar saída bruta:

    azd ai agent invoke --output raw "Hello!"

    No modo bruto, linhas de resumo legíveis como Session: e Invocation: são suprimidas, e a resposta HTTP é exibida literalmente. Esse modo é útil para depurar o comportamento do servidor e confirmar qual versão do agente lidou com a chamada.

Conteúdo relacionado

  • Last updated on