Invocar um agente hospedado com o Azure Developer CLI

Use azd ai agent invoke para enviar mensagens ao seu agente, seja a versão implementada no Microsoft Foundry ou uma instância a correr localmente. Aprendes a escolher um agente, usar endpoints diretos, gerir sessões, enviar ficheiros, fixar versões e inspecionar respostas brutas.

Pré-requisitos

Invocar o agente destacado

  • Envie um prompt ao agente destacado:

    azd ai agent invoke "What is Microsoft Foundry?"

Invocar um agente específico

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

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

Invocar um endpoint específico implementado

Quando quiseres invocar um agente implementado específico sem depender do ambiente ativo azd ou azure.yaml, usa --agent-endpoint para apontar diretamente para o URL do agente implementado. Este padrão é útil a partir de um script fora do projeto, de um agente de programação, ou quando testas uma versão específica do agente.

  • Passe o endpoint do agente implementado:

    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, pelo que não precisa de estar dentro de um diretório de projeto do azd para o utilizar.

Invoque localmente

  • Invocar um agente local:

    azd ai agent invoke --local "Hello!"

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

Invocar numa porta local personalizada

  • Se o seu agente estiver a correr numa porta não predefinida, passe --port:

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

Escolha um protocolo

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

  • responses -- envia um pedido padrão da API de Respostas OpenAI com {"input": "your message"}. O histórico de conversas é gerido automaticamente.
  • invocations -- envia a carga útil que o código do seu agente espera. Use --input-file (-f) com um ficheiro JSON que corresponda ao esquema que o seu handler define.

Para os invocations agentes, verifique o README da amostra ou inspecione o ponto de entrada do manipulador para compreender a carga útil esperada.

  • Se o seu agente implementar múltiplos protocolos, passe --protocol (-p) para escolher:

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

Gerir sessões

As sessões são persistidas por agente. Quando invoca um agente, azd guarda o 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 guardada e comece de novo:

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

Use um ID de sessão específico

  • Passe um ID de sessão existente:

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

Enviar um ficheiro como entrada

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

  1. Envie um ficheiro:

    azd ai agent invoke -f request.json

  2. Ou enviar um ficheiro a um agente específico:

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

Invocar uma versão implementada

Quando um agente tem múltiplas versões implementadas, fixe uma específica com --version. azd cria ou reutiliza uma sessão associada a essa versão, para que cada versão mantenha o seu próprio estado da conversa.

  • Fixe uma versão:

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

    --version Não podem ser combinadas com --local ou --session-id porque as sessões estão ligadas a uma versão quando são criadas.

Defina um timeout personalizado

  • Indique 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). Utilize --timeout 0 para não definir limite de tempo.

Chaves de isolamento de passagem

Os agentes configurados com isolamento baseado em cabeçalhos do Foundry exigem chaves por utilizador ou por chat em cada pedido. Passa-os com --user-isolation-key e --chat-isolation-key.

  • Transmita as chaves de isolamento com o pedido:

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

Para o padrão completo, incluindo como sessões, ficheiros e comandos de monitorização usam as mesmas bandeiras, veja Passar chaves de isolamento para um agente hospedado.

Inspecionar a resposta HTTP bruta

Quando precisar de ver exatamente o que o servidor devolveu, incluindo cabeçalhos de resposta como a versão do agente, linha de estado e o corpo não modificado, passe --output raw (-o raw).

  • Solicitar saída bruta:

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

    No modo bruto, linhas de resumo amigáveis como Session: e Invocation: são suprimidas e a resposta HTTP é despejada literalmente. Este modo é útil para depurar o comportamento dos servidores e confirmar qual a versão do agente que tratou da chamada.

Conteúdo relacionado

  • Last updated on