Saltar al contenido

Mejores prácticas para construir agentes de IA en Jitterbit Harmony

Introducción

Este documento describe la arquitectura recomendada, convenciones y mejores prácticas para desarrollar agentes de IA en Jitterbit Harmony usando Jitterbit Studio. Estas directrices garantizan escalabilidad, mantenibilidad y consistencia en todos los agentes de IA que construyas.

Consejo

Para fines de aprendizaje, consulta los agentes Reactivos, Contextuales o de Preguntas y Respuestas sobre Salesforce o Agente de GitHub con MCP disponibles a través de Jitterbit Marketplace para ver una implementación de estas mejores prácticas.

Arquitectura de componentes principales y convenciones de nomenclatura

Un agente de IA bien diseñado consta de flujos de trabajo modulares y desacoplados con límites claros entre la lógica, el procesamiento de datos y las integraciones externas.

Tu arquitectura y convenciones de nomenclatura (críticas para la legibilidad y la depuración) deben basarse en estos cuatro componentes principales, que se muestran con ejemplos en el diagrama a continuación:

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

① Entrada Principal

Un único flujo de trabajo de entrada principal maneja las solicitudes de API entrantes, la autenticación y el enrutamiento a la lógica de IA. Puede ser activado por Slack, Microsoft Teams, una interfaz personalizada, un punto de conexión de API personalizado, etc.

  • Convención de nomenclatura: Main Entry - [Nombre del Manejador]
  • Ejemplo: Main Entry - Slack API Request Handler

② Lógica de IA

Un único flujo de trabajo de lógica de IA sirve como el cerebro central del agente. Maneja la recuperación de contexto, las llamadas al LLM (OpenAI, Amazon Bedrock, etc.) y el enrutamiento a herramientas específicas. Esta es la capa central de orquestación responsable del razonamiento, la construcción de indicaciones, el enrutamiento a las herramientas correctas y la devolución de respuestas formateadas.

  • Convención de nomenclatura: Main - [Nombre del Agente] Logic
  • Ejemplo: Main - AI Agent Tools Logic

③ Herramientas (Opcional)

Puedes tener múltiples módulos independientes que realicen operaciones de datos atómicas. Estos flujos de trabajo encapsulan una función comercial específica o una interacción con una fuente de datos. Deben ser sin estado y reutilizables.

  • Convención de nomenclatura: Tool - [Acción]
  • Ejemplos:
    • Tool - Customer Order Details
    • Tool - Get Account Details
    • Tool - Retrieve Case History

④ Utilidades (Opcional)

Puedes tener múltiples procesos auxiliares compartidos. Estas son operaciones de apoyo o transversales. Por ejemplo, cargas de blob, registro de errores o escrituras en almacén de datos.

  • Convención de nomenclatura: Utility - [Acción]
  • Ejemplos:
    • Utility - Upload Customer Order Forms to Azure
    • Utility - Upload to Azure Blob
    • Utility - Format JSON

Diseño y desacoplamiento de flujos de trabajo

Para garantizar que tu agente sea mantenible y escalable, debes aplicar una separación estricta de responsabilidades.

Desacopla las herramientas de la lógica principal

Cada flujo de trabajo de herramienta (como Tool - Get Accounts) debe ser independiente y poder invocarse de forma aislada. No debe asumir ningún contexto de interfaz de usuario u orquestación de IA.

Garantiza la independencia de la interfaz de usuario

El flujo de trabajo Main - Agent Logic no debe depender de ninguna interfaz de usuario específica como Slack, Microsoft Teams o una API genérica. El flujo de trabajo de entrada principal (gestor de Slack, gestor genérico, etc.) solo debe traducir las solicitudes entrantes en un formato de carga útil interna común para las llamadas al LLM. El siguiente diagrama muestra esta arquitectura en capas:

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

Centraliza los valores de configuración con variables de proyecto

Define configuraciones específicas del entorno (claves de API, puntos de conexión, etc.) como variables de proyecto, no como valores codificados.

Integración de LLM

No incrustes llamadas de API directas a LLM dentro de tu lógica de orquestación principal. En su lugar, crea una capa de abstracción de LLM y construye indicaciones de forma dinámica.

Crea una capa de abstracción de LLM

Crea un flujo de trabajo de utilidad dedicado para invocar el LLM (como Utility - Call Azure OpenAI). Esto hace que cambiar a otro proveedor de LLM como Amazon Bedrock o Anthropic Claude sea trivial.

Construir mensajes dinámicamente

Construye mensajes dinámicamente pero en una estructura controlada:

  • Incluye contexto (datos recuperados, intención de la consulta).
  • Utiliza roles de sistema y usuario de manera clara cuando la API del LLM lo permite.
  • Mantén los límites de temperatura y tokens mediante la configuración de variables del proyecto.

Gestionar datos de sesión y contexto

Almacena el contexto transitorio de sesión y las preguntas y respuestas del usuario en un almacén de datos. Jitterbit proporciona un almacén de datos nativo de la nube listo para usar: Jitterbit Cloud Datastore.

Construir utilidades genéricas para reutilización

Construye utilidades genéricas si son comunes a múltiples flujos de trabajo para que se puedan reutilizar en diferentes flujos de trabajo. Por ejemplo:

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

Evitar errores comunes

Ten cuidado de no implementar estos errores comunes:

  • Codificar la configuración en lugar de utilizar variables del proyecto.

  • Incrustar lógica de formato de interfaz de usuario (Slack, Teams) en flujos de trabajo de IA principales.

  • Crear flujos de trabajo monolíticos que manejen múltiples procesos no relacionados.

Documentar el proyecto del agente de IA

Cada proyecto de agente de IA debe incluir la siguiente documentación para ayudar a nuevos desarrolladores y para el mantenimiento futuro:

  • Diagrama de arquitectura (mostrando endpoints, flujos de trabajo principales, herramientas, almacén de datos).

  • Lista de endpoints de origen y consumidor.

  • Lista de contenedores de Azure Blob y tablas de almacén de datos creadas.

  • Lista de API personalizadas de API Manager y su propósito.