Deixe o modelo escrever o fluxo de trabalho.
CodeAct é uma forma de um agente de IA agir escrevendo um programa curto. Esse programa chama apenas as ferramentas que você aprova, combina seus resultados com código comum e retorna uma resposta por meio do tempo de execução ADK-Rust.
cart = call_tool("fetch_cart", args) subtotal = sum(item["price"] * item["qty"] for item in cart["items"]) rate = call_tool("tax_rate", region) total = subtotal * (1 + rate)
Comece aqui
O que é um agente CodeAct?
Um agente CodeAct é um agente de IA que escreve código executable para decidir como várias ferramentas aprovadas devem funcionar juntas. Seu aplicativo executa esse código em um interpretador controlado e permanece responsável por todas as ações externas.
Chamada de ferramenta tradicional
O modelo escolhe uma ação de cada vez.
- 01Pergunte ao modelo qual ferramenta chamar.
- 02Execute essa ferramenta e envie seu resultado de volta ao modelo.
- 03Pergunte ao modelo o que fazer a seguir e repita.
CodeAct
O modelo escreve o procedimento completo.
- 01Peça ao modelo um pequeno programa usando as ferramentas disponíveis.
- 02Execute o programa e faça uma pausa somente quando chegar a uma ferramenta real.
- 03Continue com o resultado da ferramenta até que o programa retorne sua resposta.
Uma analogia simples
A chamada de ferramenta tradicional é como pedir a um colega para pressionar um botão da calculadora, reportar a tela e aguardar a próxima instrução. CodeAct é como dar permissão àquele colega para escrever uma pequena fórmula de planilha: as entradas permitidas permanecem as mesmas, mas o cálculo pode conter variáveis, condições, loops e diversas etapas.
Oito palavras que você verá nesta página
Modelo
O LLM que grava o script.
Agente
O componente que transforma uma meta em ações e resultados.
Ferramenta
Uma função Rust aprovada que atinge dados ou sistemas comerciais.
Roteiro
O pequeno programa escrito para o turno do agente atual.
Tempo de execução
O intérprete que executa e pausa o script.
Observação
Um resultado ou erro retornado ao modelo para outro turno.
Ponto de verificação
Um programa pausado salvo que pode continuar mais tarde.
Resultado final
A resposta digitada retornou ao seu aplicativo.
De onde veio a ideia
CodeAct começou como uma questão de pesquisa sobre a linguagem de ação de um agente.
A maioria dos primeiros agentes usuários de ferramentas representava uma ação como linguagem natural ou um objeto JSON contendo um nome de ferramenta e argumentos. Os pesquisadores Xingyao Wang, Yangyi Chen, Lifan Yuan, Yizhe Zhang, Yunzhu Li, Hao Peng e Heng Ji perguntaram se executable Python seria um formato de ação mais expressivo.
O papel deles, “Ações de código executável geram melhores agentes LLM”, foi lançado em fevereiro de 2024 e apareceu no ICML 2024. Ele evaluated 17 modelos de linguagem em API-Bank e no benchmark M³ToolEval do jornal. Os autores relataram que as ações de código alcançaram taxas de sucesso até 20% maiores do que os formatos de ação de texto e JSON testados.
O jornal também apresentou CodeActInstruct, um conjunto de dados de 7.000 interações multivoltas e modelos CodeActAgent ajustados para o código execute, observe resultados, revise programas com falha e continue a conversa. Estes são resultados de pesquisas sobre as tarefas do artigo; eles não significam que as ações de código sejam automaticamente melhores para cada produto.
Por que eu usaria CodeAct?
CodeAct
CodeAct é atraente quando o agente deve combinar ferramentas com computação. Ele fornece ao modelo uma linguagem familiar para expressar lógica enquanto seu aplicativo mantém os limites da ferramenta e do tempo de execução.
Componha várias ferramentas
Um script pode chamar diversas ferramentas aprovadas e passar um resultado diretamente para a próxima etapa.
Use fluxo de controle real
Loops, condições, variáveis, classificação, filtragem e aritmética são expressos diretamente no código.
Reduza as viagens de ida e volta do modelo
O trabalho que exigiria vários turnos de seleção de ferramentas às vezes pode ser expresso em um script gerado.
Mantenha os dados intermediários locais
O tempo de execução pode filtrar ou agregar grandes resultados de ferramentas antes de decidir o que pertence à transcrição do modelo.
Corrigir erros executáveis
Um erro de sintaxe, uma exceção ou uma declaração com falha pode se tornar uma observação que o modelo usa para revisar o próximo script.
Inspecione a ação
Os desenvolvedores podem ler o programa gerado, chamadas de ferramentas, saídas e pontos de verificação como uma trilha execution.
Compensações
Quando devo evitá-lo?
Uma ação simples
Uma chamada de ferramenta LlmAgent normal é mais fácil quando a solicitação é mapeada de forma clara para uma operação de negócios.
Geração de código fraca
Um modelo que se esforça para escrever código válido pode precisar de mais correções do que chamadas de ferramentas estruturadas.
Sem tempo de execução seguro
O código gerado precisa de um intérprete com acesso explícito e limites de recursos. Nunca passe para eval ou exec irrestrito.
Desenvolvimento completo de software
Use CodingAgent quando o objetivo for editar repositórios, executar comandos shell ou operar um espaço de trabalho de desenvolvimento.
Implementações no ecossistema
O conceito CodeAct agora aparece em vários sistemas de agentes.
Eles compartilham a ideia de código como um formato de ação, mas diferem no suporte à linguagem, na exposição da ferramenta, no sandbox, no estado e na carga de trabalho pretendida.
CodeAct
Pesquisa original
Ações Python, CodeActInstruct, modelos de pesquisa ajustados e um mecanismo execution em contêiner.
Saiba mais ↗OpenHands
Agentes de software
Seu CodeActAgent pode conversar, execute Python e executar comandos shell para trabalho de desenvolvimento de software.
Saiba mais ↗smolagents
Hugging Face
CodeAgent usa ações Python com loops e condições e oferece suporte a vários sandbox executors.
Saiba mais ↗Pydantic AI
Modo de código
Agrupa as ferramentas de um agente em uma interface de código e usa Monty como um tempo de execução Python controlado.
Saiba mais ↗ADK-Rust
Tempo de execução nativo Rust
Adiciona o loop CodeAct a agentes digitados, ferramentas, sessões, eventos, aprovações, retornos de chamada e transferências.
Saiba mais ↗Como ADK-Rust implementa CodeAct
CodeAct funciona dentro do tempo de execução ADK-Rust.
CodeActAgent é um tipo de agente ao lado LlmAgent. Você dá a ele um modelo, um CodeRuntimee ferramentas Rust. Em seguida, você o executa por meio dos mesmos sistemas Runner, sessão, evento, retorno de chamada, autorização e saída usados por outros agentes ADK-Rust.
1. Modelo
Escolha qualquer provedor de modelo ADK-Rust capaz de produzir código confiável.
2. CodeRuntime
Use o tempo de execução Python baseado em Monty ou implemente a característica CodeRuntime independente de linguagem.
3. Ferramentas Rust
Cadastre ferramentas digitadas. O script pode alcançar apenas as ferramentas fornecidas para essa invocação.
4. Runner
Execute o agente com um usuário e uma sessão e, em seguida, consuma eventos ADK-Rust digitados normalmente.
5. Sessão
Persista nos pontos de verificação quando a aprovação ou uma ferramenta de longa execução pausa o programa.
6. Controles
Aplique confirmação, novas tentativas, tempos limite, retornos de chamada, proteções e saídas validadas.
Início de trabalho mais rápido
Execute o exemplo com check-in primeiro.
Ele usa um modelo determinístico, um interpretador Monty Python real, duas ferramentas Rust, uma sessão na memória e o ADK-Rust Runner. Nenhuma chave de API do modelo é necessária.
O adaptador Monty é atualmente uma dependência experimental do Git e requer Rust 1.95+, portanto, o exemplo carrega seu próprio arquivo de conjunto de ferramentas.
git clone https://github.com/zavora-ai/adk-rust.git
cd adk-rust/examples/codeact_monty_agent
# This example selects Rust 1.95 automatically.
cargo run=== ADK-Rust CodeAct × Monty (Python) example ===
[cart_assistant]
{
"lines": 3,
"region": "CA",
"subtotal": 132.0,
"tax_rate": 0.0725,
"total": 141.57,
"user": "u-42"
}
Done.Arquitetura
O script é executado dentro do sistema do agente.
O modelo propõe lógica executable. O CodeRuntime controla como essa lógica avança. ADK-Rust possui todas as ações externas, pontos de verificação duráveis e eventos que o aplicativo vê.
Modelo
Escreve um script usando o briefing de tempo de execução e as ferramentas disponíveis para esta invocação.
CodeRuntime
Executa o script passo a passo e expõe chamadas, conclusão, stdout e erros de script.
Anfitrião ADK-Rust
Executa ferramentas com autorização e contexto, persiste o estado e transmite o resultado final.
Passo a passo do execution com base na fonte
Estudo de caso: precifique um carrinho de compras em um turno CodeAct.
Isso segue o exemplo determinístico CodeAct × Monty no repositório ADK-Rust. Selecione cada limite para ver qual parte do sistema está funcionando e o que fica visível para a próxima parte.
Runner
A solicitação entra em ADK-Rust
O Runner anexa o usuário, a sessão, o contexto de invocação, os retornos de chamada e as ferramentas disponíveis antes do início do agente CodeAct.
Sinal visível
Qual é o total do carrinho u-42, incluindo imposto CA?
Escolha o formato de agente correto
CodeAct tem um trabalho específico.
Use-o quando um modelo puder expressar o trabalho mais claramente como um programa. ADK-Rust também fornece formatos de agentes para uso de ferramentas de conversação e ambientes completos de desenvolvimento de software.
LlmAgent
Escolha e ligue para as ferramentas de forma conversacional.
Melhor para: Perguntas, diálogo, ações comerciais isoladas e transferências naturais.
modelo → ferramenta → modelo
CodeActAgent
Componha ferramentas e lógica em um plano executable.
Melhor para: Análise, transformação de dados, trabalho em lote, cálculos e fluxos condicionais.
modelo → script ↔ ferramentas → resultado
CodingAgent
Trabalhe dentro de um equipamento de desenvolvimento de software.
Melhor para: Edição de repositório, comandos shell, compilações, testes, patches e protocolos de agente de codificação.
agente ↔ espaço de trabalho + shell
Tempo de execução Monty
Dê ao código gerado um limite operacional claro.
O adaptador Python atual do ADK-Rust executa Monty em processo. O host decide o que o script pode ler, escrever, saber e consumir antes do início do execution.
Monty ainda é experimental. Atualmente é uma dependência Git fixada e requer Rust 1.95+. O adaptador permanece em sua própria caixa até que Monty esteja disponível em crates.io.
Caixa de areia padrão
Nenhum acesso ao sistema de arquivos e um ambiente vazio. As operações de rede e de subprocesso não possuem superfície Monty.
Montagens explícitas
Mapeie diretórios de host selecionados para caminhos virtuais e escolha acesso somente leitura ou leitura e gravação para cada um.
Limites de recursos
Defina um limite de tempo e de memória para cada avanço. As continuações serializadas mantêm esses limites quando retomadas.
Um formulário de ferramenta
Os scripts chamam call_tool(nome, argumentos). Argumentos nomeados exatos sobrevivem à serialização e são vinculados centralmente em ADK-Rust.
Ambiente controlado
Exponha apenas os valores ambientais que a tarefa precisa. Os segredos do processo host nunca são herdados automaticamente.
Falhas visíveis
Erros e exceções de sintaxe retornam ao modelo como feedback de script corrigível; falhas de tempo de execução do host interrompem a execução.
execução durável
Um programa pausado pode se tornar um estado de agente durável.
Ferramentas controladas por confirmação e de longa duração podem precisar que a solicitação termine antes que a resposta exista. CodeAct captura o interpretador pausado, sua transcrição e a chamada pendente na sessão para que outra invocação possa continuar a partir da mesma linha de código.
Salvar antes
Persista a continuação antes que uma ferramenta externa possa ser executada.
Resolver
Execute, aprove, rejeite ou aguarde o resultado da ferramenta pendente.
Salvar depois
Persista o valor retornado para que a recuperação não repita uma chamada concluída.
Currículo
Carregue o ponto de verificação e continue o mesmo script a partir do seu limite de chamada.
Responsabilidade do desenvolvedor: uma falha após um efeito colateral externo, mas antes do ponto de verificação salvar após, pode fazer com que a ferramenta seja executada novamente. Forneça às ferramentas não idempotentes uma chave de idempotência ou outra proteção de ação duplicada.
Implementação
Quatro peças definem o agente completo.
Escolha um modelo, forneça um CodeRuntime, registre as ferramentas que o script pode chamar e execute o agente por meio do ADK-Rust Runner normal.
use std::sync::Arc;
use adk_agent::codeact::CodeActAgent;
use adk_codeact_monty::MontyRuntime;
let runtime = MontyRuntime::builder()
.environ_var("CART_USER", "u-42")
.environ_var("TAX_REGION", "CA")
.system_clock(true)
.build();
let agent = CodeActAgent::builder()
.name("cart_assistant")
.model(model)
.runtime(Arc::new(runtime))
.instruction("Price the cart by writing Python.")
.tool(Arc::new(fetch_cart))
.tool(Arc::new(tax_rate))
.output_key("priced_cart")
.build()?;Construir com CodeAct
Transforme uma conversa sobre ferramentas de várias etapas em um programa legível.
Comece com o exemplo determinístico, inspecione cada pausa e retomada e, em seguida, conecte o modelo e as ferramentas que seu produto já utiliza.