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/endpoint/protocols/openai/responses?api-version=v1" \
       "Summarize today's release notes."
    

    Copie o endpoint de protocolo invocável de azd ai agent show ou azd ai agent endpoint show. Uma URL de gerenciamento de versões que termina em /versions/3 não é um ponto de extremidade de invocação. --agent-endpoint ignora o ambiente azd e a resolução azure.yaml.

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

Quando você omite --protocol, a CLI usa dados completos do endpoint implantado quando disponíveis e, em seguida, a definição do agente. Se ele não conseguir identificar exatamente um protocolo invocável, passe --protocol explicitamente. Reimplante para atualizar os dados do ponto de extremidade salvos por extensões mais antigas.

  • 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.
  • a2a -- invoca um ponto de extremidade Agente-para-Agente implantado. Passe uma mensagem ou use --input-file com uma solicitação JSON-RPC completa. Este protocolo não dá suporte a --local.

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
    

Limitações do agente de voz

azd ai agent invoke não implementa conversas de voz. Quando azure.yaml identifica o serviço selecionado como voice ou prompt-voice, o comando retorna voice agents cannot be invoked with this command e direciona você para o portal do Foundry.

Essa restrição também se aplica a um wrapper de voz que usa conversationEngine para fazer referência a um destino hospedado. Selecionar --protocol responses não contorna a verificação do serviço de voz.

Use o playground para testar um agente de voz, conforme descrito no início rápido do agente de voz.

Gerenciar sessões

A CLI salva seleções de sessão e conversa localmente por agente. Uma sessão preserva o estado da área restrita, como arquivos carregados. Para o protocolo Responses, uma conversa preserva o histórico de mensagens. Reutilizar uma sessão, por si só, não fornece histórico de conversa para o protocolo Invocations.

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"
    

Escolher o histórico de conversas separadamente

Para o protocolo de Respostas, inicie uma nova conversa com --new-conversation ou continue uma conversa conhecida com --conversation-id:

azd ai agent invoke --new-conversation "Start a new topic"
azd ai agent invoke --conversation-id <conversation-id> "Continue this topic"

--new-session também redefine a conversa salva. Para entender a distinção entre o histórico de conversas e o estado do sandbox, consulte Gerenciar sessões de agente hospedado.

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.

Informar a identidade do usuário final

Passe --user-identity para enviar uma solicitação em nome de um usuário final. Para solicitações remotas, azd envia o valor no x-ms-user-identity cabeçalho. O sinalizador funciona com os protocolos Respostas, Invocações e A2A.

A solicitação ainda é autenticada com a credencial de Microsoft Entra do chamador. O cabeçalho identifica o usuário representado; ele não substitui a autenticação nem concede a permissão de delegação listada nos pré-requisitos.

  • Envie uma identidade do usuário final para o agente implantado:

    azd ai agent invoke my-agent \
       --user-identity "user-123" \
       "Hello!"
    

    Substitua user-123 por um identificador estável para o usuário final autenticado. Inclua --user-identity em cada invocação; o sinalizador usa como padrão o vazio. Sem ela, a Foundry usa a própria identidade do chamador.

azd salva IDs de sessão e conversa por agente, não por --user-identity valor. Alterar a identidade não seleciona um estado salvo diferente. Ao alternar os usuários com o protocolo de Respostas, inicie uma nova sessão e uma conversa:

azd ai agent invoke my-agent --protocol responses \
  --user-identity "user-456" \
  --new-session --new-conversation \
  "Start a conversation for this user"

Para retomar o estado de Respostas existente de um usuário, passe --session-id e --conversation-id desse usuário com o mesmo --user-identity. Não reutilize a ID de conversa de outro usuário.

Use --user-identity, não --client-header, para x-ms-user-identity. O sinalizador --client-header aceita apenas x-client-* nomes e rejeita cabeçalhos de identidade.

Para obter requisitos de identificador e comportamento de isolamento, consulte Isolar sessões de agente hospedado por usuário. As versões atuais da extensão de agentes não aceitam sinalizadores anteriores a --user-isolation-key, --chat-isolation-key, ou --isolation-key.

Passar a identidade para um agente local

Com --local, azd envia o mesmo valor de sinalizador que x-agent-user-id em vez de x-ms-user-identity:

azd ai agent invoke my-agent --local \
  --user-identity "user-123" \
  "Hello!"

Use este cabeçalho para testar como o agente local lida com o contexto do usuário. As execuções locais não aplicam as permissões de isolamento ou delegação do Foundry.

Enviar cabeçalhos específicos do aplicativo

Use sinalizadores --client-header "Name: Value" repetíveis para metadados de solicitação, como um ID de correlação ou rótulo de locatário:

azd ai agent invoke \
  --client-header "x-client-request-id: request-123" \
  --client-header "x-client-tenant: contoso" \
  "Hello!"

Somente x-client-* nomes de cabeçalho são aceitos. Os endpoints Responses e Invocations encaminham esses cabeçalhos para o agente. O protocolo A2A não dá suporte a esse sinalizador. Use --user-identity, não --client-header, para identidade delegada.

Executar o trabalho depois que o cliente se desconectar

Para o protocolo Responses, --long-running inicia o trabalho em segundo plano do lado do serviço. O comando permanece anexado até a conclusão, a menos que você também passe --no-wait:

azd ai agent invoke --long-running --no-wait "Run the long task"

O comando retorna depois de receber a ID de resposta atribuída pelo serviço. Inspecione, siga ou solicite o cancelamento desse trabalho:

azd ai agent invocations show --protocol responses
azd ai agent invocations follow --protocol responses
azd ai agent invocations cancel --protocol responses

Esses comandos usam por padrão a ID salva mais recente para o agente selecionado e o protocolo. Passe --id <response-id> para direcionar outra resposta sem alterar essa seleção. Use --agent-name ou --agent-endpoint para escolher um destino e repita --user-identity para solicitações delegadas. Um ponto de extremidade direto identifica o protocolo; não o combine com --protocol ou --agent-name.

Respostas suporta show, follow ecancel. Invocações dão suporte a show e cancel, mas não a follow. O A2A não dá suporte a esses comandos de ciclo de vida. O serviço pode rejeitar operações que um agente individual não implementa.

A execução em segundo plano não habilita a recuperação de falhas nem a reconexão automática. Configurar o comportamento de recuperação do agente separadamente; consulte Recuperar trabalho de execução longa após uma falha.

Inspecionar a latência da plataforma

As solicitações de Respostas e Invocações de agentes hospedados remotamente coletam diagnósticos de latência da plataforma por padrão. Quando o serviço retorna cabeçalhos de tempo, a CLI exibe um resumo. Desative a coleta e o resumo com --debug-latency=false.

Invocações locais, prompt-agent e A2A não coletam latência de plataforma. O uso explícito de --debug-latency=true é rejeitado para essas rotas. Essa configuração é independente do sinalizador global --debug .

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.