Ir para o conteúdo

Boas práticas para criar agentes de IA no Jitterbit Harmony

Introdução

Este documento descreve a arquitetura recomendada, convenções e boas práticas para desenvolver agentes de IA no Jitterbit Harmony usando o Jitterbit Studio. Essas diretrizes garantem escalabilidade, manutenibilidade e consistência em todos os agentes de IA que você criar.

Dica

Para fins de aprendizado, consulte os agentes Reativo, Contextual ou Perguntas e Respostas do Salesforce ou Agente GitHub com MCP fornecidos pelo Jitterbit Marketplace para uma implementação dessas boas práticas.

Arquitetura de componentes principais e convenções de nomenclatura

Um agente de IA bem projetado consiste em fluxos de trabalho modulares e desacoplados com limites claros entre lógica, processamento de dados e integrações externas.

Sua arquitetura e convenções de nomenclatura (críticas para legibilidade e depuração) devem ser baseadas nesses quatro componentes principais, mostrados com exemplos no diagrama abaixo:

--- config: themeVariables: lineColor: '#6b7280' edgeLabelBackground: '#f5f5f5' flowchart: nodeSpacing: 10 rankSpacing: 100 padding: 20 --- flowchart classDef default fill:white, stroke:black, stroke-width:3px, rx:15px, ry:15px subgraph BOUNDARY[ ] direction TB subgraph ME["**① Main Entry**"] E("Main Entry - Slack Handler") end subgraph AIL["      **② AI Logic**"] L("Main - AI Logic") end subgraph UTIL["**④ Utilities** (Optional)"] U1["Utility - Call OpenAI"] U2["Utility - Write to Datastore"] U3["..."] end subgraph TOOLS["**③ Tools** (Optional)"] T1["Tool - Get Accounts"] T2["Tool - Create Case"] T3["..."] end end %% Define the flow E --> L L --> T1 L --> T2 L --> T3 L -- calls --> U1 L -- calls --> U2 %% Style optional components classDef optional fill:#f9f9f9,stroke:#aaa,stroke-dasharray: 5 5 classDef SubgraphStyle fill:white, stroke:black, stroke-width:3px, rx:15px, ry:15px classDef BoundaryStyle fill:white, stroke-width:0px, rx:15px, ry:15px class T1,T2,T3,U1,U2,U3 optional class ME,AIL,TOOLS,UTIL SubgraphStyle class BOUNDARY BoundaryStyle

① Ponto de Entrada Principal

Um único fluxo de trabalho de ponto de entrada principal trata solicitações de API recebidas, autenticação e roteamento para a lógica de IA. Pode ser acionado por Slack, Microsoft Teams, uma interface personalizada, um endpoint de API personalizado, etc.

  • Convenção de nomenclatura: Main Entry - [Nome do Manipulador]
  • Exemplo: Main Entry - Slack API Request Handler

② Lógica de IA

Um único fluxo de trabalho de lógica de IA atua como o cérebro central do agente. Trata da recuperação de contexto, chamadas ao LLM (OpenAI, Amazon Bedrock, etc.) e roteamento para ferramentas específicas. Esta é a camada de orquestração central responsável pelo raciocínio, construção de prompts, roteamento para as ferramentas corretas e devolução de respostas formatadas.

  • Convenção de nomenclatura: Main - Lógica [Nome do Agente]
  • Exemplo: Main - Lógica Ferramentas Agente de IA

③ Ferramentas (Opcional)

Você pode ter vários módulos independentes que executam operações de dados atômicas. Esses fluxos de trabalho encapsulam uma função de negócio específica ou interação de fonte de dados. Devem ser sem estado e reutilizáveis.

  • Convenção de nomenclatura: Tool - [Ação]
  • Exemplos:
    • Tool - Detalhes de Pedido do Cliente
    • Tool - Obter Detalhes da Conta
    • Tool - Recuperar Histórico de Casos

④ Utilitários (Opcional)

Você pode ter vários processos auxiliares compartilhados. Estas são operações de suporte ou entre vários domínios. Por exemplo, uploads de blob, registro de erros ou gravações em datastore.

  • Convenção de nomenclatura: Utility - [Ação]
  • Exemplos:
    • Utility - Fazer Upload de Formulários de Pedido do Cliente para Azure
    • Utility - Fazer Upload para Azure Blob
    • Utility - Formatar JSON

Design de fluxo de trabalho e desacoplamento

Para garantir que seu agente seja mantível e escalável, você deve impor uma separação rigorosa de responsabilidades.

Desacople ferramentas da lógica principal

Cada fluxo de trabalho de ferramenta (como Tool - Get Accounts) deve ser autossuficiente e chamável de forma independente. Não deve assumir nenhum contexto de interface ou orquestração de IA.

Garanta independência da interface

O fluxo de trabalho Main - Agent Logic não deve depender de nenhuma interface de usuário específica, como Slack, Microsoft Teams ou uma API genérica. O fluxo de trabalho do ponto de entrada principal (manipulador do Slack, manipulador genérico, etc.) deve apenas traduzir solicitações recebidas em um formato de carga comum interno para chamadas ao LLM. O diagrama a seguir mostra essa arquitetura em camadas:

--- config: themeVariables: lineColor: '#6b7280' edgeLabelBackground: '#f5f5f5' flowchart: nodeSpacing: 10 rankSpacing: 100 padding: 20 --- graph classDef default fill:white, stroke:black, stroke-width:3px, rx:15px, ry:15px subgraph BOUNDARY[ ] direction TB UI["User interface (Slack/API)"] --> Main["Main entry workflow"] Main --> Orchestration["AI orchestration logic"] Orchestration --> Tools["Tool workflows"] end classDef BoundaryStyle fill:white, stroke-width:0px, rx:15px, ry:15px class BOUNDARY BoundaryStyle

Centralize valores de configuração com variáveis de projeto

Defina configurações específicas do ambiente (chaves de API, endpoints, etc.) como variáveis de projeto, não valores codificados.

Integração com LLM

Não incorpore chamadas de API diretas para LLMs em sua lógica de orquestração principal. Em vez disso, crie uma camada de abstração de LLM e construa prompts dinamicamente.

Crie uma camada de abstração de LLM

Crie um fluxo de trabalho utilitário dedicado para invocar o LLM (como Utility - Call Azure OpenAI). Isso torna trivial mudar para outro provedor de LLM, como Amazon Bedrock ou Anthropic Claude.

Construir prompts dinamicamente

Construa prompts dinamicamente, mas em uma estrutura controlada:

  • Inclua contexto (dados recuperados, intenção da consulta).
  • Use claramente as funções de sistema e usuário quando suportado pela API do LLM.
  • Mantenha limites de temperatura e tokens por meio da configuração de variáveis de projeto.

Gerenciar dados de sessão e contexto

Armazene o contexto transitório de sessão e pergunta-resposta do usuário em um datastore. A Jitterbit fornece um datastore nativo de nuvem pronto para este propósito: Jitterbit Cloud Datastore.

Criar utilitários genéricos para reutilização

Crie utilitários genéricos se comuns a múltiplos workflows para que possam ser reutilizados entre workflows. Por exemplo:

  • Utility - Upload to Azure Blob
  • Utility - Write to Datastore
  • Utility - Parse Slack Payload
  • Utility - Call OpenAI

Evitar armadilhas comuns

Tome cuidado para não implementar estes erros comuns:

  • Codificar configurações em vez de usar variáveis de projeto.

  • Incorporar lógica de formatação de UI (Slack, Teams) em workflows principais de IA.

  • Criar workflows monolíticos que lidem com múltiplos processos não relacionados.

Documentar seu projeto de agente de IA

Cada projeto de agente de IA deve incluir a seguinte documentação para ajudar novos desenvolvedores e para manutenção futura:

  • Diagrama de arquitetura (mostrando endpoints, workflows principais, ferramentas, datastore).

  • Lista de endpoints de origem e consumidor.

  • Lista de contêineres de Blob do Azure e tabelas de datastore criadas.

  • Lista de APIs personalizadas do API Manager e sua finalidade.