Criar um agente de prompt com Microsoft Foundry Toolkit para Visual Studio Code

Use o Construtor de Agentes no Microsoft Foundry Toolkit para Visual Studio Code para configurar o modelo, as instruções e as ferramentas de um agente de prompt. Teste o agente no playground, salve as alterações como versões e gere o código do cliente para chamá-lo a partir de um aplicativo.

Este artigo começa com os agentes de prompt salvos na Foundry. O Construtor de Agentes também dá suporte a prompts armazenados localmente, que têm diferentes opções de armazenamento, ferramenta e avaliação. Para obter alternativas baseadas em código, consulte Criar um agente.

Pré-requisitos

• Instale Microsoft Foundry Toolkit para Visual Studio Code.
• Selecione um projeto do Foundry. Você precisa de permissão para criar agentes e usar os modelos e ferramentas do projeto. Consulte o controle de acesso baseado em funções do Foundry.
• Uma implantação de modelo nesse projeto. Consulte Configurar recursos do Foundry.

O desenvolvimento de prompt local não requer um projeto de Foundry, a menos que você use recursos do Foundry.

Criar um agente de prompt

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

1. Na exibição Foundry Toolkit, selecione Developer Tools>>.

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

3. Em Informações Básicas, insira um nome de Agente. Inicie e encerre o nome com uma letra ou número. Você pode usar hifens entre eles.

4. Selecione um modelo hospedado pela Foundry no Modelo. Use Procurar modelos se precisar adicionar um modelo.

5. Em Instruções, descreva a tarefa, o comportamento necessário e a resposta esperada. Por exemplo, peça ao agente para resumir um problema de software identificando o problema relatado, as etapas de reprodução e o comportamento esperado. Diga-lhe para pedir as informações que faltam em vez de inventar detalhes.

6. Selecione Salvar na Fundiária.

7. Na guia Playground , insira uma solicitação e selecione Enviar mensagem. Faça uma pergunta de acompanhamento para testar a conversa.

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

   

Se as Ferramentas do Desenvolvedor estiverem usando Agrupar por recurso, Criar agente estará em Ferramentas de Desenvolvedor do Agente em vez de Compilação. Outro ponto de entrada é Meus Recursos>Agentes>Agente de Prompt>Adicionar Agente de Prompt. Selecione um agente existente nessa lista para editá-lo.

Escolher onde salvar

As ações de salvamento disponíveis dependem do modelo e das ferramentas selecionados.

Configuration	Salvar destino
Modelo hospedado no Foundry sem ferramentas.	Salvar no Foundry, com Salvar localmente disponível no menu de salvamento.
Modelo hospedado no Foundry com ferramentas do Foundry.	Salvar no Foundry.
Um modelo de outro provedor ou uma configuração com ferramentas locais.	Salvar localmente.

Os selos Microsoft Foundry e Local mostram onde o agente está armazenado. Um prompt armazenado localmente ainda pode chamar um modelo de nuvem. O armazenamento local não significa que a inferência seja executada em seu computador.

Salvar rascunhos e versões

O Construtor de Agentes separa os rascunhos de recuperação local das versões salvas do agente.

Ação	Result
Edite a configuração.	O Construtor de Agentes armazena um rascunho local de recuperação. Essa ação não cria uma versão do Foundry.
Execute um novo agente ainda não salvo.	O Construtor de Agentes valida o nome e o modelo do agente e o salva antes da primeira execução. Ele prefere o Foundry quando a configuração dá suporte a esse destino.
Selecione Salvar no Foundry depois de editar um agente salvo do Foundry.	O Construtor de Agentes salva 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. Salve alterações importantes explicitamente antes de alternar agentes ou versões.

Você pode testar alterações não salvas em um agente do Foundry existente. Essa execução usa a configuração editada em vez de uma referência a uma versão salva do agente. Salve antes de usar conversas vinculadas à versão, rastreamento ou código de cliente gerado.

Importante

Salvar no Foundry salva uma versão do agente. Não disponibiliza uma aplicação de agente com um endpoint estável da aplicação. Para essa operação separada, consulte Publicar um aplicativo de agente.

Selecionar uma versão do agente

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

A versão selecionada determina o histórico de conversas mostrado no Construtor de Agentes e a versão referenciada pelo código do cliente gerado. Para obter detalhes do controle de versão do serviço, consulte Salvar alterações como versões.

Adicionar ferramentas a um agente do Foundry

As ferramentas conectam o agente a informações e ações fora do modelo. As ferramentas disponíveis dependem do modelo, das permissões e dos recursos do projeto. Use o Catálogo de Ferramentas para configurar conexões compartilhadas e autenticação e anexá-las no Construtor de Agentes.

1. Abra um agente Foundry salvo na guia Playground.
2. Na Ferramenta, selecione +>Adicionar ferramentas.
3. Em Selecionar uma ferramenta, escolha uma conexão em Configuradas ou use Catálogo para encontrar uma ferramenta.
4. Conclua a configuração necessária e selecione Adicionar Ferramenta.
5. Selecione Salvar na Fundiária.
6. Envie uma solicitação que exija a ferramenta e examine suas entradas e resultados. Se o agente solicitar aprovação, selecione Aprovar ou Negar para essa chamada.

Para examinar as configurações de aprovação de chamada de ferramenta para uma ferramenta MCP, abra suas opções e selecione Configurar. Você pode exigir aprovação, aprovar todas as ferramentas automaticamente ou aprovar ferramentas específicas automaticamente. Examine a opção antes de salvar.

As configurações de aprovação não concedem acesso ao serviço subjacente. Para obter permissões de serviço, consulte os conceitos de identidade do Agente.

Usar uma caixa de ferramentas (versão prévia)

Um conjunto de ferramentas agrupa ferramentas reutilizáveis em um endpoint MCP gerenciado. Habilidades e busca de ferramentas estão em versão preliminar.

Note

A integração da caixa de ferramentas em agentes de prompt está em versão prévia e desativada por padrão. Nas configurações do Visual Studio Code, habilite windowsaistudio.enableToolboxInPromptAgent para mostrar os controles de anexação da caixa de ferramentas.

Um agente usa ou um conjunto de ferramentas ou ferramentas individuais do Foundry. Anexar uma caixa de ferramentas substitui suas ferramentas individuais. Com uma caixa de ferramentas anexada, Adicionar ferramentas adiciona ferramentas dentro dessa caixa de ferramentas.

As edições da caixa de ferramentas são preparadas até você salvar o agente, quando elas criam uma nova versão da caixa de ferramentas. Caixas de ferramentas são recursos compartilhados; examine as alterações da caixa de ferramentas e do agente antes de salvar.

1. Abra um agente do Foundry salvo.

2. Na Ferramenta, selecione +>Procurar caixas de ferramentas.

3. Selecione uma caixa de ferramentas e examine sua versão, ferramentas e habilidades.

4. Selecione Adicionar.

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

6. Selecione Salvar no Foundry e teste uma solicitação que usa suas ferramentas.

   

Você também pode selecionar Adicionar ao Agente de Prompt na lista de recursos da Caixa de ferramentas. Para criar a caixa de ferramentas e conexões compartilhadas, consulte Catálogo de Ferramentas.

Gerenciar uma caixa de ferramentas anexada

Use o menu Mais opções do cartão de ferramentas e salve o agente depois de fazer alterações.

Ação	Effect
Configure	Altere as configurações de aprovação de chamada de ferramenta para esse agente.
Mudar versão	Selecione outra versão da caixa de ferramentas anexada.
Replace	Escolha uma caixa de ferramentas diferente.
Remove	Desanexe a caixa de ferramentas deste agente.
Recusar	Mantenha suas ferramentas como ferramentas de agente individuais. O agente não tem mais acesso aos recursos do toolbox, à busca de ferramentas nem ao controle de versão e à reutilização em conjunto.

Conectar outro agente com A2A (versão prévia)

As conexões agente a agente (A2A) permitem que um agente de prompts invoque um agente compatível com A2A como ferramenta. Você pode anexar um diretamente ou usando uma caixa de ferramentas. O anexo direto não requer a configuração de aceitação da caixa de ferramentas.

1. Abra um agente do Foundry salvo.

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

3. Em Conectar um agente A2A, escolha a aba apropriada.

   Tecla Tab	O que fornecer
   Configurado	Selecione uma conexão A2A existente. Essa guia é exibida quando existem conexões configuradas.
   Catálogo	Selecione um agente no catálogo de contas do Foundry. Conclua as etapas de cartão do agente e autenticação quando solicitado.
   Personalizado	Insira um nome, um endpoint HTTPS válido e o caminho do agent-card. Selecione Autenticar ao recuperar o cartão do agente , se necessário.

4. Conclua a caixa de diálogo para conectar ou adicionar o agente.

5. Selecione Salvar no Foundry e, em seguida, teste uma solicitação que exija a conexão.

   

Para configurar ponto de extremidade, cartões de agente, opções de identidade e permissões, consulte Habilitar um ponto de extremidade A2A.

Revisar conversas e trocar de agente

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

Para um agente salvo no Foundry, selecione Conversas para revisar o histórico da versão selecionada. Selecione uma conversa para inspecionar suas mensagens e detalhes de resposta. O histórico de abertura não retoma essa conversa no playground.

Use o seletor de agente na parte superior do Construtor de Agentes para alternar entre os prompts locais e os agentes de prompt do Foundry. Verifique o indicador de armazenamento e a versão após trocar. A aba Conversas está disponível para agentes do Foundry salvos, não para prompts locais.

Gerar e aprimorar instruções

Use Gerar para elaborar instruções de uma descrição de tarefa ou melhorar para revisar as instruções existentes. Quando o campo está vazio, Inspire-me pode fornecer uma ideia inicial.

1. Selecione um modelo que dê suporte à geração de instruções.
2. Em Instruções, selecione Gerar se o campo estiver vazio ou Melhorar se ele contiver instruções.
3. Descreva a tarefa ou a alteração. Para um agente do Foundry existente, as sugestões de melhoria são opcionais.
4. Selecione Gerar ou Melhorar na caixa de diálogo.
5. Examine as instruções revisadas e teste as solicitações representativas.
6. Selecione Salvar no Foundry para salvar a configuração.

Para os agentes do Foundry salvos, essas ações usam o Foundry Prompt Optimizer. Se a API de otimização não der suporte ao modelo, o Kit de Ferramentas retornará à geração de prompt padrão quando houver suporte. Selecionar um modelo do Foundry em um novo rascunho, por si só, não faz com que o rascunho se torne um agente do Foundry salvo.

Avaliar um agente de prompts do Foundry

Salve a configuração que você deseja avaliar e selecione Avaliação.

• Selecione Código de avaliação do Scaffold para gerar um projeto local de avaliação em Python. Siga as instruções geradas para configurá-la e executá-la.
• Selecione o link Foundry para configurar a avaliação guiada.

Examine a configuração de avaliação gerada antes de executá-la. A estrutura identifica o agente pelo nome; não presuma que ela o vincule à versão que você selecionou no Construtor de Agentes.

Essa guia difere da exibição do conjunto de dados do prompt local. Para obter diretrizes de avaliação de serviço, consulte Avaliar seus agentes.

Gerar código do cliente

Depois de salvar um agente do Foundry, use o menu Exibir Código para chamá-lo de um aplicativo.

Ação	Saída
Exibir código	Um projeto Python que chama o agente existente. Escolha uma pasta e siga suas instruções README.md para dependências, configuração e autenticação.
Exibir trechos de código	Um snippet de Python em um editor que chama o agente existente.

Ambas as saídas fazem referência à versão salva selecionada. Salve suas edições antes de gerar código se o aplicativo precisar da configuração revisada.

O código do cliente não converte um agente de prompt em um agente hospedado. Para usar o SDK diretamente, consulte o guia de início rápido do prompt-agent.

Trabalhar com prompts locais

Escolha o armazenamento local para usar um modelo de outro provedor ou testar ferramentas locais. Selecione um modelo, insira instruções e selecione Salvar no Local. Com um modelo de Foundry, use o menu salvar quando o armazenamento local estiver disponível.

Use Salvar no Local para manter as alterações locais. Os salvamentos locais não criam versões do Foundry nem registros do histórico da conversa no Foundry.

Conectar ferramentas locais

Para um prompt local, selecione Ferramenta>+> para escolher um servidor e suas ferramentas. Para obter requisitos de configuração e runtime, consulte Conectar um servidor MCP local.

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

1. Selecione Ferramenta>+>.
2. Escolha por exemplo ou carregue o esquema existente.
3. Forneça o esquema, o nome e a descrição e adicione a ferramenta.
4. Insira uma resposta simulada no cartão de ferramentas.
5. Execute o prompt e inspecione como o modelo usa a resposta.

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

Configurar saída estruturada

Para um prompt local com um modelo que dá suporte à saída estruturada:

1. Abra Configurações ao lado do seletor de modelo.
2. Em Saída da Estrutura, selecione json_schema.
3. Em Selecionar Esquema JSON, escolha Usar Exemplo ou Carregar Arquivo.
4. Examine o esquema e selecione Selecionar.
5. Salve o prompt local e execute uma solicitação para inspecionar sua saída.

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

Avaliar prompts locais com variáveis de conjunto de dados

Para um prompt local salvo, a guia Avaliação fornece avaliação baseada em conjunto de dados. Use variáveis nas instruções para executar o mesmo prompt com valores de conjunto de dados diferentes.

Por exemplo, Summarize the issue for {{audience}}. usa uma coluna de conjunto de dados chamada audience. Forneça um valor para cada caso de teste. O executor de lote local substitui esse valor quando executa o prompt.

O playground do Construtor de Agentes não tem um painel de variáveis separado. Para importação de conjunto de dados, avaliadores e comparação de resultados, consulte Avaliar modelos, prompts e agentes.

Gerar código para um prompt local

Selecione Exibir Código para gerar o código de integração de modelos. As opções de SDK, autenticação e idioma disponíveis dependem do provedor e do modelo. Essas opções diferem do projeto do cliente do agente Foundry e das ações de trecho de código.

Conteúdo relacionado

Use estes guias para desenvolver e publicar seu agente:

• Criar um agente com Microsoft Foundry Toolkit
• Ciclo de vida de desenvolvimento do agente
• Publicar um aplicativo de agente