Crie um agente de prompts com o Microsoft Foundry Toolkit para Visual Studio Code

Use o Agent Builder no Microsoft Foundry Toolkit para Visual Studio Code para configurar o modelo, instruções e ferramentas de um agente de prompt. Testa o agente no playground, guarda as alterações como versões e gera código cliente para o chamar a partir de uma aplicação.

Este artigo começa com agentes de prompts guardados no Foundry. O Agent Builder também suporta prompts armazenados localmente, que têm diferentes opções de armazenamento, ferramentas e avaliação. Para alternativas baseadas em código, veja Criar um agente.

Pré-requisitos

• Instale o Microsoft Foundry Toolkit para Visual Studio Code.
• Selecione um projeto Foundry. Precisas de permissão para criar agentes e usar os modelos e ferramentas do projeto. Veja Controlo de acesso baseado em funções da Foundry.
• Um modelo de implementação nesse projeto. Consulte Configurar recursos do Foundry.

O desenvolvimento local de prompts não requer um projeto do Foundry, a menos que utilize recursos do Foundry.

Crie um agente de prompts

Comece com um modelo e instruções, depois guarde e teste o agente antes de adicionar ferramentas.

1. Na vista Foundry Toolkit, selecione Ferramentas de Programador>Compilar>Criar Agente.

2. Selecione Criar um agente para abrir o Construtor de Agentes.

3. Em Informações Básicas, insira o nome de um Agente. Começa e termina o nome com uma letra ou número. Podes usar hífens entre eles.

4. Selecione um modelo hospedado no Foundry em Modelo. Utiliza Explorar modelos se precisares de adicionar um modelo.

5. Nas Instruções, descreva a tarefa, o comportamento exigido e a resposta esperada. Por exemplo, peça ao agente que resuma um problema de software identificando o problema reportado, os passos de reprodução e o comportamento esperado. Diz-lhe para pedir informações em falta em vez de inventar detalhes.

6. Selecione Guardar na Foundry.

7. No separador Playground , introduza um pedido e selecione Enviar mensagem. Faça uma pergunta de seguimento para testar a conversa.

8. Veja se a resposta segue as suas instruções. Refinar as instruções, guardar e repetir conforme necessário.

   

Se o Developer Tools usar Agrupar por Recurso, o Create Agent fica em Agent Dev Tools em vez de Build. Outro ponto de acesso é My Resources>Agents>Prompt Agent>Add Prompt Agent. Selecione um agente existente nessa lista para o editar.

Escolha onde guardar

As ações de gravação disponíveis dependem do modelo e das ferramentas selecionadas.

Configuration	Guardar destino
Modelo alojado na fundição sem ferramentas.	Guardar no Foundry, com Guardar localmente disponível no menu Guardar.
Modelo alojado na Foundry com ferramentas da Foundry.	Guardar para a Foundry.
Um modelo de outro fornecedor, ou uma configuração com ferramentas locais.	Guardar para local.

Os emblemas Microsoft Foundry e Local indicam onde o agente está armazenado. Um pedido armazenado localmente pode ainda assim invocar um modelo na cloud. O armazenamento local não significa que a inferência corra na tua máquina.

Guardar rascunhos e versões

O Agent Builder separa os rascunhos de recuperação locais das versões guardadas do agente.

Action	Result
Editar a configuração.	O Agent Builder armazena um rascunho local de recuperação. Esta ação não cria uma versão do Foundry.
Gerir um novo agente, não salvo.	O Agent Builder valida o nome e o modelo do agente e guarda-o antes da primeira execução. Prefere o Foundry quando a configuração suporta esse destino.
Selecione Guardar no Foundry depois de editar um agente Foundry guardado.	O Agent Builder guarda a configuração como uma nova versão no projeto.

Se o Agent Builder encontrar um rascunho de recuperação, escolha Restaurar Rascunho ou Descartar. Guarda as alterações importantes explicitamente antes de mudares de agente ou versão.

Pode testar alterações não guardadas num agente Foundry existente. Essa execução usa a configuração editada em vez de uma referência guardada na versão do agente. Guarde antes de recorrer a conversas associadas a versões, rastreio ou código de cliente gerado.

Importante

Guardar no Foundry guarda uma versão do agente. Não publica uma aplicação agente com um endpoint de aplicação estável. Para essa operação separada, veja Publicar uma aplicação agente.

Selecione uma versão de agente

Use o seletor de versões ao lado do nome do agente para carregar uma versão guardada. As versões do agente Foundry são imutáveis. Para manter as edições feitas numa versão anterior, selecione Guardar na Foundry para criar uma nova versão.

A versão selecionada determina o histórico de conversas mostrado no Agent Builder e a versão referenciada pelo código do cliente gerado. Para detalhes sobre a versão do serviço, veja Guardar alterações como versões.

Adicionar ferramentas a um agente da Foundry

As ferramentas ligam o agente à informação e ações fora do modelo. As ferramentas disponíveis dependem do modelo, das suas permissões e dos recursos do seu projeto. Use o Catálogo de Ferramentas para configurar ligações partilhadas e autenticação, depois anexe-as no Construtor de Agentes.

1. Abrir um agente Foundry guardado no separador Playground.
2. Na Ferramenta, selecione +>Adicionar ferramentas.
3. Em Selecionar uma ferramenta, escolha uma ligação em Configured, ou use Catálogo para encontrar uma ferramenta.
4. Complete a configuração necessária e depois selecione Adicionar Ferramenta.
5. Selecione Guardar na Foundry.
6. Envie um pedido que exija a ferramenta e reveja as suas entradas e resultados. Se o agente solicitar aprovação, selecione Aprovar ou Negar para essa chamada.

Para rever as definições de aprovação de chamadas de ferramenta para uma ferramenta MCP, abra as suas opções e selecione Configurar. Pode exigir aprovação, aprovar todas as ferramentas automaticamente, ou aprovar ferramentas específicas automaticamente. Revise a escolha antes de poupar.

As definições de aprovação não concedem acesso ao serviço subjacente. Para permissões de serviço, veja conceitos de identidade de agente.

Utilize uma caixa de ferramentas (pré-visualização)

Uma caixa de ferramentas agrupa ferramentas reutilizáveis atrás de um endpoint MCP gerido. A pesquisa de competências e ferramentas são funcionalidades de pré-visualização.

Note

A integração do toolbox nos agentes de prompts está em pré-visualização e desligada por defeito. Nas definições do Visual Studio Code, ative windowsaistudio.enableToolboxInPromptAgent para mostrar os controlos de anexo da caixa de ferramentas.

Um agente utiliza uma caixa de ferramentas ou ferramentas individuais da Foundry. Anexar uma caixa de ferramentas substitui as suas ferramentas individuais. Com uma caixa de ferramentas anexada, adicionar ferramentas adiciona ferramentas dentro dessa caixa.

As edições na caixa de ferramentas são faseadas até guardares o agente, altura em que criam uma nova versão da caixa de ferramentas. As caixas de ferramentas são recursos partilhados; revise tanto as alterações da caixa de ferramentas como do agente antes de guardar.

1. Abrir um agente Foundry guardado.

2. Na ferramenta, selecione +>Explorar caixas de ferramentas.

3. Selecione uma caixa de ferramentas e reveja a sua versão, ferramentas e competências.

4. Selecione Adicionar.

5. Expanda o cartão da caixa de ferramentas para inspecionar o seu conteúdo e rever as definições de aprovação.

6. Seleciona Guardar no Foundry e depois testa um pedido que use as suas ferramentas.

   

Também pode selecionar Adicionar ao Prompt Agent na lista de recursos da Toolbox. Para criação de caixas de ferramentas e ligações partilhadas, consulte Catálogo de Ferramentas.

Gerir uma caixa de ferramentas anexa

Utiliza o menu Mais opções do cartão da caixa de ferramentas e, em seguida, guarda o agente depois de fazeres alterações.

Action	Effect
Configure	Mudar as definições de aprovação de chamadas de ferramentas para este agente.
Versão para Switch	Selecione outra versão da caixa de ferramentas anexada.
Replace	Escolhe uma caixa de ferramentas diferente.
Remove	Separe a caixa de ferramentas do agente.
Recusar	Mantém as suas ferramentas como ferramentas individuais para agentes. O agente já não tem acesso às competências da caixa de ferramentas, à pesquisa de ferramentas nem ao controlo de versões e reutilização, considerados em conjunto.

Ligue outro agente utilizando A2A (pré-visualização)

As ligações entre agentes (A2A) permitem que um agente que emite o prompt invoque um agente compatível com A2A como ferramenta. Pode anexar um diretamente ou através de uma barra de ferramentas. A ligação direta não requer a opção de opt-in da caixa de ferramentas.

1. Abrir um agente Foundry guardado.

2. Na Ferramenta, selecione +>Adicionar agente (A2A).

3. Em Ligar um agente A2A, escolha o separador adequado.

   Tab	O que fornecer
   Configurado	Selecione uma ligação A2A existente. Este separador aparece quando existem ligações configuradas.
   Catálogo	Selecione um agente do catálogo de contas do Foundry. Conclua os passos do cartão do agente e da autenticação quando lhe for solicitado.
   Personalizado	Introduza um nome, um endpoint HTTPS válido e o caminho agent-card. Selecione Autenticar ao retirar o cartão de agente , se necessário.

4. Completa o diálogo para ligar ou adicionar o agente.

5. Seleciona Guardar no Foundry e depois testa um pedido que exija a ligação.

   

Para configuração do endpoint, cartões de agente, opções de identidade e permissões, consulte Ativar um endpoint A2A.

Rever conversas e mudar de agente

O Playground contém a conversa atual do teste. Selecione Apagar todas as mensagens para iniciar uma nova conversa.

Para um agente Foundry guardado, selecione Conversas para rever o histórico da versão selecionada. Selecione uma conversa para inspecionar as suas mensagens e detalhes de resposta. Abrir o histórico não retoma essa conversa no Playground.

Utilize o seletor de agentes na parte superior do Agent Builder para alternar entre prompts locais e agentes de prompt do Foundry. Verifique o distintivo de armazenamento e a versão após a mudança. O separador Conversas está disponível para agentes guardados do Foundry, não para prompts locais.

Gerar e melhorar instruções

Use Ger para redigir instruções a partir de uma descrição de tarefa ou Melhorar para rever instruções existentes. Quando o campo estiver vazio, o Inspire Me pode dar uma ideia inicial.

1. Selecione um modelo que suporte a geração de instruções.
2. Em Instruções, selecione Gerar se o campo estiver vazio, ou Melhorar se contiver instruções.
3. Descreva a tarefa ou a mudança. Para um agente Foundry existente, sugestões de melhoria são opcionais.
4. Selecione Gerar ou Melhorar no diálogo.
5. Revise as instruções revistas e os pedidos do representante de teste.
6. Selecione Guardar no Foundry para guardar a configuração.

Para agentes Foundry guardados, estas ações utilizam o Foundry Prompt Optimizer. Se a API de otimização não for compatível com o modelo, o Toolkit recorre à geração de prompts padrão quando esta for suportada. Selecionar um modelo Foundry num novo rascunho não faz do rascunho um agente Foundry guardado.

Avalie um agente de prompts da Foundry

Guarda a configuração que queres avaliar e depois seleciona Avaliação.

• Selecione Código de Avaliação de Andaimes para gerar um projeto local de avaliação em Python. Siga as instruções geradas para configurar e executar.
• Selecione o link Foundry para configurar a avaliação guiada.

Revise a configuração de avaliação gerada antes de a executar. O andaime identifica o agente pelo nome; não assumas que fixa a versão que selecionaste no Agent Builder.

Este separador difere da vista local do conjunto de dados de prompts. Para orientações sobre avaliação de serviços, consulte Avaliar os seus agentes.

Gerar código de cliente

Depois de guardar um agente Foundry, use o menu Ver Código para o chamar a partir de uma aplicação.

Action	Output
Ver Código	Um projeto Python que chama o agente existente. Escolha uma pasta e, em seguida, siga as instruções em README.md sobre dependências, configuração e autenticação.
Ver fragmentos	Um excerto de Python num editor que chama o agente existente.

Ambas as saídas referenciam a versão guardada selecionada. Guarde as suas edições antes de gerar código, caso a aplicação precise da configuração revista.

O código do cliente não converte um agente de instruções num agente alojado. Para uso direto do SDK, veja o prompt-agent quickstart.

Trabalhe com prompts locais

Escolha armazenamento local para usar um modelo de outro fornecedor ou teste ferramentas locais. Selecione um modelo, introduza instruções e selecione Guardar no local. Com um modelo Foundry, use o menu de gravação quando houver armazenamento local disponível.

Use Guardar para Local para manter as alterações locais. Os saves locais não criam versões do Foundry nem registos de histórico de conversas do Foundry.

Liga ferramentas locais

Para um prompt local, selecione Tool>+>MCP Server para escolher um servidor e as suas ferramentas. Para requisitos de configuração e tempo de execução, consulte Ligar um servidor MCP local.

Para testar um esquema de função sem implementar um serviço externo:

1. Selecione Ferramenta>+>Personalizada.
2. Escolha por exemplo ou carregue o esquema existente.
3. Fornece o esquema, nome e descrição, depois adiciona a ferramenta.
4. Introduza uma resposta simulada no cartão de ferramentas.
5. Executa o prompt e inspeciona como o modelo usa a resposta.

Uma resposta simulada não chama uma API externa. Um servidor MCP configurado pode executar as suas ferramentas.

Configurar a saída estruturada

Para um prompt local com um modelo que suporta saída estruturada:

1. Abrir Definições ao lado do seletor de modelos.
2. Em Estrutura Saída, selecione json_schema.
3. Em Select JSON Schema, escolha Usar Exemplo ou Carregar Ficheiro.
4. Revise o esquema e selecione Selecionar.
5. Guarde o prompt local e execute uma solicitação para inspecionar a sua saída.

Os formatos disponíveis dependem do modelo. Estes passos aplicam-se à execução local de prompts, não ao esquema de resposta de um agente de prompt Foundry guardado.

Avaliar prompts locais com variáveis do conjunto de dados

Para um prompt local guardado, o separador Avaliação permite uma avaliação com base em conjuntos de dados. Use variáveis nas instruções para executar o mesmo prompt com valores de conjunto diferentes.

Por exemplo, Summarize the issue for {{audience}}. utiliza uma coluna de conjunto de dados chamada audience. Fornece um valor para cada caso de teste. O batch runner local substitui esse valor quando executa o prompt.

O playground do Agent Builder não tem um painel separado de Variáveis. Para importação de conjuntos de dados, avaliadores e comparação de resultados, consulte Avaliar modelos, prompts e agentes.

Gerar código para um prompt local

Selecione Código de Visualização para gerar código de integração de modelos. O SDK disponível, a autenticação e as escolhas de linguagem dependem do fornecedor e do modelo. Estas opções diferem do projeto de cliente do agente Foundry e das ações de fragmento de código.

Conteúdo relacionado

Use estes guias para desenvolver e divulgar o seu agente:

• Criar um agente com o Microsoft Foundry Toolkit
• Ciclo de vida do desenvolvimento do agente
• Publicar uma candidatura de agente