Novo Ciclo de Vida de Metadados e Desenvolvimento do Agentforce: Guia Completo para DevOps com Agent Script no Spring ’26

O Agentforce Builder GA transforma a forma como desenvolvedores criam, testam e fazem deploy de agentes de IA no Salesforce. Entenda as mudanças nos metadados, o fluxo de trabalho com Agent Script e como estruturar pipelines CI/CD confiáveis.

A chegada do Agentforce Builder GA na Spring ’26 marca um ponto de inflexão para desenvolvedores Salesforce. Se você já trabalhou com a versão anterior do construtor de agentes, sabe que cada modificação em um subagente compartilhado poderia desencadear efeitos colaterais imprevisíveis em outros agentes dependentes. Esse cenário de “ondulações globais” tornava os deploys arriscados e as revisões de código exaustivas.

Com a nova arquitetura baseada em Agent Script e metadados bundleizados, a Salesforce reestruturou completamente o ciclo de vida de desenvolvimento de agentes. O resultado é um ambiente onde você pode iterar com segurança, revisar código de forma legível e implantar com confiabilidade — sem medo de quebrar seu agente de produção.

Este guia técnico explora todas as mudanças, oferece exemplos práticos e mostra como tirar o máximo proveito da nova arquitetura em seus projetos.

Por que os Metadados do Agentforce Mudaram

O Problema do Acoplamento Global

Na versão anterior do Agentforce Builder, os ativos de agentes eram globais por padrão. Quando você modificava um subagente utilizado por múltiplos agentes, a alteração se propagava instantaneamente para todos eles. Isso criava três problemas principais:

Primeiro, a impossibilidade de testar mudanças de forma isolada. Se você precisava ajustar a lógica de um subagente para um caso de uso específico, acabava afetando todos os outros agentes que dependiam dele.

Segundo, revisões de código difíceis. Comparar alterações significava analisar múltiplos arquivos XML espalhados por diferentes tipos de metadados, tornando o processo de code review lento e propenso a erros.

Terceiro, deploys frágeis. A falta de isolamento significava que um deployment mal-sucedido em um ambiente de teste poderia falhar em produção devido a dependências não documentadas.

A Solução: Ativos Locais e Bundleização

A Salesforce introduziu os Local Assets (Ativos Locais) para resolver esse problema. Um ativo local é uma cópia clonada de um ativo global, ancorada especificamente a uma versão de agente. Uma vez local, você pode editá-lo sem impactar nenhum outro agente que use o ativo original.

Mas os Local Assets precisavam de suporte adequado nos metadados para funcionar em pipelines CI/CD. Anteriormente, os metadados de agentes estavam distribuídos entre múltiplos tipos, o que dificultava a mobilidade entre ambientes.

A solução foi a bundleização — reestruturação dos metadados para que todos os assets dependentes de uma versão de agente residam em uma única estrutura de diretórios centralizada.

O Novo Fluxo de Trabalho do Agentforce Builder

A Separação entre Intenção e Execução

O Agentforce Builder introduz uma separação clara entre sua intenção (o que você quer que o agente faça) e a execução (os metadados ativos que o motor utiliza). Entender essa distinção é fundamental para dominar o novo fluxo de trabalho.

1. Escrever e Construir

Você escreve seu agente usando a interface do Agentforce Builder ou diretamente por meio de um Agent Script. Este script, legível por humanos, é salvo como um único arquivo .agent dentro de um novo tipo de metadado chamado AiAuthoringBundle. Nesta fase, seu trabalho é um rascunho.

# Exemplo de Agent Script (simplificado)
agent: AtendimentoCliente
description: Agente para suporte ao cliente

instructions:
- Responda perguntas sobre pedidos
- Transfira para humano se não souber
- Mantenha tom profissional

subagents:
- name: ConsultaEstoque
description: Verifica disponibilidade de produtos
- name: ProcessaDevolucao
description: Inicia processo de devolução

2. Iterar e Visualizar

Você testa seu rascunho usando os modos de visualização disponíveis. O Simulation Mode é particularmente útil, pois isola seus testes dos dados reais da organização, permitindo experimentar sem riscos.

3. Publicar

Quando está satisfeito com o rascunho, você faz o commit da versão. Este é o momento crucial: é apenas durante o commit que a plataforma traduz seu script .agent nos metadados ativos de Bot e GenAiPlannerBundle que realmente executam seu agente.

Estrutura de Diretórios dos Novos Metadados

AiAuthoringBundles

O diretório AiAuthoringBundles contém todos os artefatos de design-time do agente. Ele suporta múltiplos subdiretórios versionados (por exemplo, AgenteVendas_1, AgenteVendas_2), cada um com seu próprio arquivo .agent e descritor .bundle-meta.xml.

AiAuthoringBundles/
└── AtendimentoCliente_1/
├── AtendimentoCliente.agent
└── AtendimentoCliente.bundle-meta.xml
└── AtendimentoCliente_2/
├── AtendimentoCliente.agent
└── AtendimentoCliente.bundle-meta.xml

Dentro de cada versão:

• Arquivo .agent: Contém a configuração do agente escrita em Agent Script — nome, label, descrição, instruções de sistema, definições de subagentes, instruções de raciocínio, variáveis, condicionais e referências de ferramentas/ações.
• Descritor .bundle-meta.xml: Declara o bundleType (por exemplo, AGENT) e a versão-alvo do agente que aponta.

Bot e BotVersion

O metadado Bot contém informações comuns a todas as versões do agente, como o tipo de agente e configurações úteis como o registro de dados privados. Ele também mantém variáveis de contexto de nível de agente, distintas das variáveis de conversação que vivem dentro de cada BotVersion.

Cada BotVersion inclui:

• Variáveis de conversação
• Mensagem de boas-vindas
• Mensagem de transferência de conversa

GenAiPlannerBundle

O GenAiPlannerBundle contém todos os dados relevantes para cada versão publicada de um agente. Dentro de cada versão, você encontra:

GenAiPlannerBundle/
└── AtendimentoCliente_1/
├── AtendimentoCliente.genAiPlannerBundle
├── agentGraph.json
├── agentScript (codificado)
└── plannerActions/
└── localActions/
└── ConsultaEstoque/
├── input/
│ └── schema.json
└── output/
└── schema.json

• .genAiPlannerBundle: O arquivo principal de metadados com a configuração de runtime do agente — subagentes, instruções, ações e lógica de orquestração.
• agentGraph: JSON codificando todas as transições e condições entre subagentes.
• agentScript: Cópia codificada do Agent Script da versão, mantida para detectar dessincronia entre o script e os metadados publicados.
• plannerActions: Ações de nível de agente (não vinculadas a subagentes específicos).
• localActions: Ações vinculadas a subagentes, aninhadas sob suas pastas.

Exemplo Prático: XML do GenAiPlannerBundle

Veja como o XML reflete os subagentes e ações localizadas:

Agente de atendimento ao cliente v2

ConsultaEstoque_16jxx0000001234


ConsultaEstoque_16jxx0000001234
Consulta disponibilidade no estoque Topic Consulta de Estoque

Você é um agente de consulta de estoque.
1


EstoqueService_179xx0000001234


EstoqueService_179xx0000001234
EstoqueService
apex:EstoqueServiceEstoqueService_Global

AiCopilot__ReAct

Cada bloco “ define a configuração completa de um subagente: seu nome API único, descrição, tipo de plugin, instruções ordenadas e todas as ações locais disponíveis.

Cada bloco “ define o nome da ação, target de invocação, tipo e, opcionalmente, uma referência source ao ativo global do qual foi clonado.

Manifesto package.xml para Spring ’26

Para recuperar e fazer deploy de agentes construídos com o novo Agentforce Builder, certifique-se de que seu package.xml inclua os novos tipos de bundle:

*
GenAiFunction


*
Bot


*
GenAiPlannerBundle


*
GenAiPlugin


*
AiAuthoringBundle

66.0

Nota: Este manifesto usa a versão de API 66.0, necessária para suportar GenAiPlannerBundle e os novos tipos de metadados de agentes.

Estratégias de CI/CD com Agent Script

Abordagem 1: Apenas AiAuthoringBundle (Simples)

Para pipelines mais simples, você pode manter apenas o AiAuthoringBundle no controle de fonte:

# Deploy do rascunho
sf project deploy start --metadata AiAuthoringBundle --target-org my-org

# Commit para gerar metadados de runtime
sf agent publish authoring-bundle --api-name MyAuthoringBundle --target-org my-org

# Ativar a versão
sf agent activate --api-name MyAuthoringBundle --version 2 --target-org my-org

Abordagem 2: Pipeline Completo (Automatizado)

Para equipes que desejam um pipeline totalmente automatizado sem etapas manuais:

# Deploy simultâneo de AiAuthoringBundle e GenAiPlannerBundle
sf project deploy start --metadata AiAuthoringBundle,GenAiPlannerBundle --target-org my-org

Quando você faz deploy de ambos simultaneamente, o sistema reconhece o script junto com seus metadados pré-realizados e pula a etapa de commit manual. Seu agente fica ativo imediatamente após o deployment.

Dicas Práticas para Desenvolvedores

Use Arquivos de Script Legíveis para Code Reviews

No modelo anterior, revisar mudanças em agentes significava comparar múltiplos arquivos XML complexos em pull requests. Agora, você pode comparar os arquivos .agent legíveis, que são muito mais fáceis de entender.

# Diferença entre versões de um agente
git diff HEAD~1 -- "*.agent"

# Resultado legível:
# - subagent: ConsultaEstoque
# - description: Consulta produtos no estoque
# + description: Consulta disponibilidade em tempo real no estoque

Estruture Seu Repositório

force-app/
├── main/
│ ├── default/
│ │ ├── aiAuthoringBundles/
│ │ │ └── MeuAgente/
│ │ │ ├── MeuAgente.agent
│ │ │ └── MeuAgente.bundle-meta.xml
│ │ ├── bots/
│ │ │ └── MeuAgente/
│ │ ├── genAiPlannerBundles/
│ │ │ └── MeuAgente/
│ │ └── genAiFunctions/
│ │ └── MeuAgente/
└── scripts/
└── deploy-agents.sh

Automação com Scripts

#!/bin/bash
# deploy-agents.sh

TARGET_ORG=$1

echo "Fazendo deploy dos agentes..."
sf project deploy start \
--metadata AiAuthoringBundle,GenAiPlannerBundle \
--target-org $TARGET_ORG

echo "Verificando status do deploy..."
sf project deploy report --target-org $TARGET_ORG

echo "Deploy concluído!"

Comparação: Antes vs Depois

Impacto para Empresas e Desenvolvedores

Para Arquitetos de Soluções

A nova arquitetura permite uma separação clara de responsabilidades entre equipes. Analistas de negócios podem escrever Agent Scripts enquanto desenvolvedores focam na lógica Apex e integrações, tudo versionado de forma independente.

Para DevOps Engineers

Os bundles facilitam a criação de pipelines automatizados. A capacidade de fazer deploy de AiAuthoringBundle e GenAiPlannerBundle simultaneamente elimina etapas manuais e reduz o risco de erros humanos.

Para Desenvolvedores

A legibilidade do Agent Script transforma a experiência de code review. Em vez de decifrar XML aninhado, você lê um arquivo que parece pseudo-código, tornando a revisão mais rápida e eficaz.

Para Gestores de TI

O versionamento nativo oferece rastreabilidade completa de quem alterou o quê e quando, essencial para auditorias e conformidade em ambientes regulados.

Considerações Finais

O novo ciclo de vida de metadados do Agentforce representa muito mais do que uma atualização técnica é uma mudança de paradigma na forma como construímos e entregamos agentes de IA no ecossistema Salesforce.

A combinação de Agent Script legível, Local Assets para isolamento e bundles versionados cria uma fundação sólida para práticas DevOps maduras. Desenvolvedores que adotarem essas práticas desde o início terão uma vantagem competitiva significativa na construção de soluções agentes de produção.

Se você ainda não começou a explorar o novo Agentforce Builder, a Salesforce oferece recursos gratuitos para acelerar sua aprendizagem:

Módulo Trailhead: Create an Agent Using Pro Code Tools

Playlist Agent Script Decoded no YouTube

Documentação: GenAiPlannerBundle Metadata