Ir para o conteúdo

Melhores práticas para construir agentes de IA no Jitterbit Harmony

Introdução

Este documento descreve a arquitetura recomendada, convenções e melhores 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ê construir.

Dica

Para fins de aprendizado, consulte os agentes de Q&A reativos, contextuais ou do Salesforce ou o Agente do GitHub com MCP fornecidos através do Jitterbit Marketplace para uma implementação dessas melhores 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: 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

① Entrada Principal

Um único fluxo de trabalho de entrada principal lida com solicitações de API recebidas, autenticação e roteamento para a lógica de IA. Ele pode ser acionado pelo Slack, Microsoft Teams, uma interface de usuário personalizada, um endpoint de API personalizado, etc.

  • Convenção de nomenclatura: Entrada Principal - [Nome do Manipulador]
  • Exemplo: Entrada Principal - Manipulador de Solicitações da API do Slack

② Lógica de IA

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

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

③ Ferramentas (Opcional)

Você pode ter múltiplos módulos independentes que realizam operações atômicas de dados. Esses fluxos de trabalho encapsulam uma função de negócios específica ou interação com uma fonte de dados. Eles devem ser sem estado e reutilizáveis.

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

④ Utilitários (Opcional)

Você pode ter múltiplos processos auxiliares compartilhados. Essas são operações de suporte ou transversais. Por exemplo, uploads de blobs, 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 o Azure
    • Utility - Fazer Upload para Blob do Azure
    • Utility - Formatar JSON

Design de fluxo de trabalho e desacoplamento

Para garantir que seu agente seja sustentável e escalável, você deve impor uma separação rigorosa de preocupações.

Desacoplar ferramentas da lógica principal

Cada fluxo de trabalho de ferramenta (como Tool - Obter Contas) deve ser autônomo e chamável de forma independente. Não deve assumir nenhum contexto de orquestração de UI ou IA.

Garantir independência da UI

O fluxo de trabalho Main - Lógica do Agente 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 de entrada principal (manipulador do Slack, manipulador genérico, etc.) deve apenas traduzir as solicitações recebidas em um formato de carga útil interno comum para chamadas de LLM. O diagrama a seguir mostra essa arquitetura em camadas:

--- config: 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

Centralizar 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, e não como valores codificados.

Integração com LLM

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

Criar uma camada de abstração de LLM

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

Construa prompts dinamicamente

Construa prompts dinamicamente, mas em uma estrutura controlada:

  • Inclua contexto (dados recuperados, intenção da consulta).
  • Use claramente os papéis de sistema e usuário quando suportados pela API LLM.
  • Mantenha a temperatura e os limites de tokens por meio da configuração de variáveis do projeto.

Gerencie dados de sessão e contexto

Armazene dados transitórios de sessão e contexto de perguntas e respostas do usuário em um datastore. O Jitterbit fornece um datastore nativo em nuvem pronto para uso para esse propósito: Jitterbit Cloud Datastore.

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

Crie utilitários genéricos se forem comuns a vários fluxos de trabalho, para que possam ser reutilizados em diferentes fluxos. Por exemplo:

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

Evite armadilhas comuns

Tenha cuidado para não implementar esses erros comuns:

  • Codificação rígida de configuração em vez de usar variáveis de projeto.

  • Embutir lógica de formatação de UI (Slack, Teams) em fluxos de trabalho principais de IA.

  • Criar fluxos de trabalho monolíticos que lidam com múltiplos processos não relacionados.

Documente 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, principais fluxos de trabalho, ferramentas, datastore).

  • Lista de endpoints de origem e consumidores.

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

  • Lista de APIs personalizadas do API Manager e seu propósito.