Usar o recurso Microsoft Foundry em agentes de código

O Microsoft Foundry Skill fornece orientações reutilizáveis para agentes de código em fluxos de trabalho de agentes do Foundry. Use-o para ajudar a padronizar a implantação, a avaliação, a otimização de prompts, a curadoria de conjuntos de dados a partir de rastros e a resolução de problemas em ambientes de desenvolvimento com suporte a agentes.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Se você não tiver uma, crie uma conta gratuita do Azure.

  • Um host de agente de codificação, como GitHub Copilot em Visual Studio Code, Copilot CLI ou Claude Code.

  • Node.js 18 ou posterior em seu PATH. O plug-in usa npx para iniciar servidores MCP em hosts compatíveis.

  • Git, para que o host possa baixar o plugin e o conteúdo da skill.

  • CLI do Azure instalado e autenticado:

    az login

  • Azure Developer CLI instalado e autenticado caso pretenda usar fluxos de trabalho de implantação azd:

    azd auth login

  • Um projeto do Microsoft Foundry se você quiser que o agente inspecione ou modifique recursos com escopo de projeto. Para obter as etapas de instalação, consulte Criar um projeto.

O que a habilidade Foundry oferece

A habilidade microsoft-foundry é uma meta-habilidade para trabalhar no Foundry. Isso ajuda um agente de programação a escolher o fluxo de trabalho adequado do Foundry, carregar a sub-habilidade correspondente, inspecionar as ferramentas MCP do Foundry disponíveis e manter consistente o contexto de implantação e avaliação ao longo dos turnos.

Use-o quando quiser que o agente ajude com essas áreas de funcionalidade:

Área de capacidade O que a habilidade ajuda o agente a fazer
Configuração inicial do Foundry Crie ou conecte-se a um projeto do Foundry, provisione um recurso do Foundry, escolha a configuração pública ou isolada de rede e prepare o workspace para o desenvolvimento do agente.
Acesso e capacidade Verifique as atribuições de RBAC, identidades gerenciadas, principais de serviço, cotas, disponibilidade do modelo, capacidade regional e pré-requisitos de implantação.
Implementação de modelo Implante modelos com predefinições rápidas ou configurações personalizadas, como versão, SKU, capacidade e configuração de IA responsável.
Personalização de modelo Faça o ajuste fino de modelos com ajuste fino supervisionado, otimização de preferência direta ou fluxos de trabalho de ajuste fino por reforço.
Criação de agentes Crie aplicativos de agente hospedados que usam Microsoft Agent Framework, LangGraph ou estruturas personalizadas em Python ou C#.
Implantação do agente Conteinerize um agente, compile e envie imagens por push para Registro de Contêiner do Azure, crie ou atualize implantações de agente hospedado e reimplante após alterações de código.
Invocação e teste Envie mensagens de turno único ou de vários turnos para agentes implantados, agentes de prompt de teste e agentes hospedados de teste que usam protocolos baseados em HTTP ou WebSocket.
Avaliação e otimização Execute avaliações em lote, configure a avaliação contínua, compare versões, otimize prompts, aprimore as instruções do agente e prepare trabalhos do Otimizador de Agente.
Trabalho com rastreamento e conjuntos de dados Consultar rastreamentos, analisar latência ou falhas, correlacionar resultados de avaliação com respostas e organizar conjuntos de dados de avaliação a partir de rastreamentos de produção.
Troubleshooting Inspecione os logs do agente hospedado, consulte a telemetria, diagnostique falhas de implantação ou de tempo de execução e planeje um ciclo de reparar e reimplantar.

A competência instalada inclui subcompetências especializadas para essas áreas. Normalmente, você não precisa nomear a sub-habilidade diretamente. Peça o resultado desejado e o agente de codificação usa as instruções de habilidade para rotear a tarefa.

Installation

A extensão Foundry Toolkit para VS Code vem com a Skill do Foundry. Para instalar a extensão, consulte Trabalhar com a extensão Microsoft Foundry para Visual Studio Code.

Após a instalação, recarregue o Visual Studio Code se solicitado. Abra Copilot Chat, alterne para o modo de agente e confirme se as habilidades de Foundry estão disponíveis. Quando solicitado, entre com a conta de Azure que tenha acesso ao projeto do Foundry.

Para obter mais informações sobre a instalação do MCP no Visual Studio Code, consulte Get iniciado com o servidor MCP Azure e Get iniciado com o Servidor MCP do Foundry.

Se o host já tiver a configuração do servidor MCP e você precisar apenas do conteúdo da habilidade, instale diretamente a habilidade microsoft-foundry:

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

O caminho apenas de habilidade faz o download das orientações de fluxo de trabalho do Foundry. Use o Azure Skills Plugin quando quiser que a habilidade, a configuração do Azure MCP Server e a configuração do Foundry MCP Server sejam instaladas juntas.

Verificar a configuração

Após a instalação, experimente estas verificações do agente de codificação:

  • Pergunte ao What AI models are available in Microsoft Foundry? A resposta deve usar as ferramentas do Foundry em vez de um resumo genérico.
  • Consulte List my Azure resource groups. A resposta deve usar as ferramentas MCP do Azure após você se autenticar.
  • Em um projeto do agente do Foundry, pergunte Use the Microsoft Foundry Skill to review this agent for deployment readiness. A resposta deve identificar verificações de fluxo de trabalho, como configuração, acesso ao projeto, implantação de modelo, dados de avaliação e validação de implantação.

Se uma verificação falhar, recarregue o host, confirme o plug-in instalado com êxito e verifique se ele az login usa a assinatura que contém os recursos do Foundry.

Usar a habilidade em um projeto

Abra a pasta que contém o código do agente do Foundry. Solicite o resultado desejado e inclua o projeto de destino, o ambiente, a pasta do agente ou o nome da implantação se você já o souber.

Use esses padrões de prompt para invocar os recursos da habilidade:

Goal Prompt de exemplo Fluxo de trabalho típico
Configurar o Foundry para um novo agente Use the Microsoft Foundry Skill to create a public Foundry project, deploy a model, and scaffold a hosted agent. Configuração do projeto, implantação de modelo, criação de agente, implantação e invocação.
Configurar um ambiente privado Use the Microsoft Foundry Skill to plan a network-isolated Foundry deployment for this project. Planejamento de rede privada, seleção de modelo, verificações de implantação e validação.
Implantar um agente hospedado existente Use the Microsoft Foundry Skill to prepare this hosted agent for deployment to my dev environment. Resolução do contexto do espaço de trabalho, compilação de contêiner, envio para o ACR, implantação em agente hospedado e teste de fumaça.
Reimplantar após alterações de código Use the Microsoft Foundry Skill to redeploy this agent and verify it still responds correctly. Atualização sobre a implantação, invocação e acompanhamento da avaliação.
Teste um agente Use the Microsoft Foundry Skill to invoke this agent with a short multi-turn test conversation. Busca, invocação e revisão das respostas do agente.
Avaliar a qualidade Use the Microsoft Foundry Skill to create an evaluation plan for this agent from eval.yaml. Configuração do pacote de avaliação, verificações de conjunto de dados e avaliador, avaliação em lote e resumo de resultados.
Otimizar instruções Use the Microsoft Foundry Skill to improve the agent instructions based on recent evaluation results. Análise avaliativa, otimização de prompts, avaliação de candidatos e avaliação de acompanhamento.
Criar um conjunto de dados de avaliação Use the Microsoft Foundry Skill to create an evaluation dataset from the last seven days of production traces. Rastreamento de consultas, curadoria de conjuntos de dados, controle de versões e rastreamento de linhagem.
Solucionar uma falha Use the Microsoft Foundry Skill to troubleshoot why this hosted agent deployment is failing. Verificação da invocação, logs, telemetria, análise de causa raiz, plano de reparo, nova implantação e reteste.
Verificar o acesso ou a capacidade Use the Microsoft Foundry Skill to check RBAC and quota blockers before I deploy this model. Revisão de atribuição de função, consulta de cota, planejamento de capacidade e etapas de remediação.
Ajuste um modelo Use the Microsoft Foundry Skill to plan a supervised fine-tuning workflow for this training dataset. Preparação do conjunto de dados, configuração de treinamento, revisão de ponto de verificação, implantação de modelo e avaliação.

Antes de aprovar alterações ou comandos, examine o plano, os arquivos gerados e Azure recursos que o agente propõe criar ou modificar. Para tarefas de implantação, ajuste fino e provisionamento, confirme atribuições de função e recursos de custo antes que o agente execute comandos.

Usar as habilidades do Kit de Ferramentas do Foundry no VS Code

Foundry Toolkit for Visual Studio Code também disponibiliza habilidades específicas do Foundry no VS Code. Essas habilidades, como vscode-microsoft-foundry e foundrytk-quick-start, se concentram na experiência de desenvolvimento do VS Code: integração ao Foundry Toolkit, exploração de modelos, criação de agentes, seleção de um modelo, implantação de um agente, avaliação de desempenho e gerenciamento de caixas de ferramentas. Eles são diferentes da habilidade central microsoft-foundry, que fornece a base de conhecimento mais abrangente e detalhes concretos do fluxo de trabalho para gerenciamento de recursos do Foundry, RBAC, cotas, implantação de modelos, implantação de agentes hospedados, avaliação, rastreamento e solução de problemas. Instale o Foundry Toolkit para VS Code para disponibilizar essas habilidades fornecidas por extensão em sua experiência de agente do VS Code.

Como funciona a habilidade

Quando um agente de codificação usa a habilidade Microsoft Foundry, ele segue alguns padrões comuns:

  1. Ele começa com a descoberta do MCP do Foundry para saber quais ferramentas e parâmetros do Foundry estão disponíveis em seu ambiente.
  2. Ele carrega a sub-habilidade que corresponde ao fluxo de trabalho, como criação, implantação, invocação, avaliação, rastreamento, solução de problemas, RBAC, cota ou implantação de modelo.
  3. Ele resolve o contexto de projeto e agente do seu workspace antes de propor alterações ou comandos.
  4. Ele prefere ferramentas estruturadas do Foundry e Azure MCP quando elas estão disponíveis.
  5. Ele solicita valores ausentes somente quando eles não podem ser resolvidos a partir do seu prompt, dos arquivos do espaço de trabalho ou do contexto autenticado do Azure.

A habilidade dá suporte a dois tipos de agente comuns:

Tipo de agente Caso de uso
Agente de prompt Um agente baseado em LLM que usa uma implantação de modelo e uma configuração de prompt.
Agente hospedado Um agente baseado em contêiner que executa código personalizado no Serviço do Foundry Agent.

Para fluxos de trabalho de agentes hospedados, a habilidade também pode funcionar com agentes que usam os protocolos responses, invocations ou invocations_ws. Use invocations_ws para cenários WebSocket em tempo real ou duplex, como agentes de voz ou interações de streaming.

Arquivos do espaço de trabalho que a habilidade usa

O recurso procura o contexto do projeto e do agente do Foundry nos arquivos comuns do espaço de trabalho. Mantenha esses arquivos atualizados para que o agente de codificação possa fazer recomendações específicas e repetíveis.

Arquivo ou pasta Como a habilidade usa isso
azure.yaml Localiza azd serviços, pastas de projeto do agente, configurações de host de implantação e associações de ambiente.
.azure/<environment>/.env Resolve valores autenticados de ambiente azd, como assinatura, grupo de recursos, ponto de extremidade do projeto, nome do agente, registro e cadeia de conexão do Application Insights.
.foundry/agent-metadata.yaml Armazena o estado da sobreposição específico do Foundry, como referências à suíte de avaliação, referências a conjuntos de dados, caminhos de cache local, resumos de resultados e substituições não azd.
.foundry/agent-metadata.<env>.yaml Armazena o estado de sobreposição específico do ambiente para um destino, como produção ou CI.
agent.yaml Fornece a configuração do agente local para criar, implantar, invocar e avaliar fluxos de trabalho.
eval.yaml Define a intenção da avaliação local, incluindo arquivo do conjunto de dados, nomes dos avaliadores, limiar de aprovação, número de amostras, retrospectiva de rastreamento e instruções de geração.

Para fluxos de trabalho de implantação e avaliação, prefira .foundry/agent-metadata.yaml para estado de overlay não sigiloso. Não armazene segredos em .foundry arquivos. Se azd já fornecer um valor de implantação, como um endpoint do projeto ou registro, permita que o agente de codificação use o valor de azd em vez de duplicá-lo nos metadados.

Troubleshooting

Questão Resolução
O host não encontra a habilidade. Confirme o plug-in instalado com êxito e recarregue ou reinicie o host para que ele reindexe o conteúdo do plug-in.
As ferramentas MCP não aparecem. Confirme se Node.js está instalado, npx funciona e as entradas do servidor MCP do Azure e do Foundry foram adicionadas ao host.
Azure solicitações falham com erros de autenticação. Execute az login novamente. Para fluxos de trabalho azd, execute também azd auth login.
O agente usa a assinatura errada. Defina a assinatura de Azure pretendida em CLI do Azure antes de tentar novamente o prompt.
As operações do projeto Foundry falham. Confirme se sua conta tem acesso ao projeto Foundry e as funções RBAC Azure necessárias.

Conteúdo relacionado

  • Last updated on