CodeAct

O CodeAct permite que um agente resolva uma tarefa escrevendo código e executando-a por meio de uma execute_code ferramenta. Em vez de solicitar que o modelo emita uma chamada de ferramenta de cada vez, o CodeAct fornece um local em área restrita para combinar fluxo de controle, transformação de dados e orquestração de ferramentas dentro de uma única etapa de execução.

No Agent Framework, CodeAct é exposto por meio de pacotes específicos de back-end em vez de um único tipo de núcleo interno. Um conector pode adicionar a ferramenta execute_code injetar orientações de tempo de execução e, opcionalmente, expor ferramentas de propriedade do provedor que podem ser chamadas de dentro do sandbox.

Por que CodeAct

Os agentes de IA modernos geralmente não são limitados pela qualidade do modelo, mas pela sobrecarga de orquestração. Quando um agente encadeia muitas chamadas de ferramentas pequenas, cada etapa geralmente requer uma nova iteração do modelo, o que aumenta a latência e o uso de tokens.

O CodeAct simplifica esse ciclo modelo -> ferramenta -> modelo. Em vez de solicitar que o modelo escolha uma ferramenta de cada vez, o Agent Framework pode expor uma única execute_code ferramenta e permitir que o modelo expresse o plano completo como um programa curto. As ferramentas permanecem as mesmas, o modelo permanece o mesmo e a principal mudança é que o plano é executado uma única vez dentro de um sandbox, em vez de ser distribuído por várias iterações de chamadas de ferramentas.

Para cargas de trabalho com muitas ferramentas, isso pode reduzir significativamente a latência de ponta a ponta e o uso de tokens, mantendo o plano compacto e auditável em um único bloco de código. Consulte a integração do Hyperlight CodeAct para uma comparação lado a lado das conexões.

Quando CodeAct é uma boa opção

Use CodeAct quando uma tarefa se beneficiar de:

  • Combinando múltiplas chamadas de ferramentas com loops, ramificações, filtragem ou agregação
  • transformando resultados da ferramenta antes de retornar uma resposta final
  • gerando saídas estruturadas ou artefatos maiores como parte de uma execução
  • mantendo algumas ferramentas disponíveis somente dentro de um ambiente de execução controlada
  • Agrupar muitas consultas pequenas e encadeáveis ou cálculos leves em uma etapa de processamento

Mantenha a chamada direta de ferramentas quando:

  • a tarefa precisar apenas de uma ou duas chamadas de ferramentas, portanto, houver pouca sobrecarga de orquestração a ser removida
  • cada chamada tem efeitos colaterais que devem permanecer visíveis de forma individual para o modelo e o usuário
  • você precisar de solicitações de aprovação por chamada em vez de uma decisão de aprovação para toda a execução de execute_code run

Como o CodeAct se encaixa no Agent Framework

Um conector CodeAct normalmente faz quatro coisas para uma execução:

  1. Adiciona uma ferramenta execute_code à superfície de ferramentas voltada para o modelo.
  2. Fornece instruções para o tempo de execução do sandbox configurado.
  3. Opcionalmente, expõe ferramentas de propriedade do provedor por meio de call_tool(...).
  4. Aplica limites de funcionalidade, como acesso ao sistema de arquivos ou listas de permissões de rede de saída.

Como o conector possui a configuração de runtime, os detalhes exatos da instalação dependem do back-end escolhido.

Limitações atuais

CodeAct é ideal para fluxos de trabalho que exigem muitas ferramentas, mas há algumas restrições atuais a serem mantidas em mente.

  • Atualmente, o conector documentado do Agent Framework é Hyperlight CodeAct, disponível para Python e .NET (em prévia).
  • As aprovações atualmente se aplicam à chamada execute_code como um todo. Se você precisar que operações individuais sejam aprovadas uma a uma, mantenha essas operações como ferramentas de agente diretas em vez de depender de call_tool(...).
  • As ferramentas acessadas por meio de call_tool(...) ainda são executadas no processo host. Use ferramentas de host específicas e revisadas para E/S sensíveis em vez de ampliar o acesso ao sandbox desnecessariamente.
  • CodeAct funciona melhor quando a sobrecarga de orquestração domina. Para tarefas pequenas com apenas uma ou duas chamadas de ferramenta, a abstração adicionada pode não trazer muitos benefícios.
  • Os nomes das ferramentas, os metadados dos parâmetros e os formatos de retorno são mais importantes aqui porque o modelo está escrevendo código com base nesse contrato, em vez de escolher uma chamada de ferramenta direta por vez.

Introdução

Para .NET, o conector documentado hoje é Hyperlight CodeAct, enviado como o pacote Microsoft.Agents.AI.Hyperlight.

O pacote fornece:

  • HyperlightCodeActProvider — um AIContextProvider que injeta execute_code e orientações do CodeAct para cada execução
  • HyperlightExecuteCodeFunction — um AIFunction independente para conexão estática/manual quando a configuração do sandbox é fixa
  • ferramentas gerenciadas pelo provedor que permanecem disponíveis dentro do sandbox por meio de call_tool(...)
  • integração de CodeActApprovalMode e ApprovalRequiredAIFunction para aprovação
  • configuração opcional do sistema de arquivos (FileMounts, HostInputDirectory) e da rede de saída (AllowedDomains) para o runtime do ambiente isolado

Importante

O pacote .NET está em versão prévia e depende do Hyperlight.HyperlightSandbox.Api NuGet, que ainda não foi publicado no nuget.org. Consulte Hyperlight CodeAct para obter as restrições de instalação atuais e os requisitos da plataforma.

Consulte o CodeAct do Hyperlight para obter instalação, exemplos e diretrizes específicas do runtime.

Introdução

Para Python, o conector documentado hoje é o CodeAct do Hyperlight.

O pacote do Hyperlight fornece:

  • HyperlightCodeActProvider para execuções baseadas em provedor de contexto
  • HyperlightExecuteCodeTool quando você deseja conectar execute_code diretamente
  • ferramentas gerenciadas pelo provedor que permanecem disponíveis dentro do sandbox por meio de call_tool(...)
  • configuração opcional de sistema de arquivos e rede de saída para o sandbox runtime

Consulte o CodeAct do Hyperlight para instalação, exemplos, diretrizes específicas do runtime, como quando usar print(...) e /output/e as limitações específicas do Hyperlight atuais.

Note

O suporte para Go a este recurso estará disponível em breve. Consulte o repositório Agent Framework Go para obter o status mais recente.

Próximas Etapas 

Segurança do agente

Conteúdo relacionado

  • Last updated on