Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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
- Um projeto de agente hospedado inicializado. Para criar um, consulte Inicializar um projeto de agente.
- As extensões do azd Foundry foram instaladas. Para obter as etapas de instalação, consulte Instalar as extensões do Azd Foundry.
- Uma sessão autenticada da CLI do Desenvolvedor do Azure. Execute
azd auth loginse necessário. - Para invocação remota, um agente hospedado implantado. Para implantar um, consulte Implantar um agente hospedado.
- Para invocação local, é necessário ter um agente local em execução. Para iniciar um, consulte Executar um agente hospedado localmente com a CLI do Desenvolvedor do Azure.
- Para enviar uma identidade de usuário final delegada remotamente, a permissão
Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/actionno agente. Essa permissão requer uma função personalizada; consulte Delegar a identidade do usuário final.
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 showouazd ai agent endpoint show. Uma URL de gerenciamento de versões que termina em/versions/3não é um ponto de extremidade de invocação.--agent-endpointignora o ambiente azd e a resoluçãoazure.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 runem 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-filecom 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.
Enviar um arquivo:
azd ai agent invoke -f request.jsonOu 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"--versionnão pode ser combinado com--localou--session-idporque 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 0para 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-123por um identificador estável para o usuário final autenticado. Inclua--user-identityem 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:eInvocation: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
- Isolar sessões de agentes hospedados por usuário para garantir isolamento individual por usuário em agentes multilocatários.
- Execute um agente hospedado localmente com a CLI do desenvolvedor do Azure para iniciar seu agente para desenvolvimento local.
- Monitore os logs de agente hospedados com a CLI do desenvolvedor do Azure para inspecionar o comportamento do agente implantado.