Saltar al contenido

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

Introducción

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

Consejo

Para fines de aprendizaje, consulta los agentes de Q&A Reactivos, Contextuales o de Salesforce o el Agente de GitHub con MCP proporcionados a través de Jitterbit Marketplace para una implementación de estas mejores prácticas.

Arquitectura de componentes centrales y convenciones de nomenclatura

Un agente de IA bien diseñado consiste en 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 centrales, mostrados con ejemplos en el diagrama a continuación:

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

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

  • Convención de nomenclatura: Entrada Principal - [Nombre del Manejador]
  • Ejemplo: Entrada Principal - Manejador de Solicitudes API de Slack

② 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 a LLM (OpenAI, Amazon Bedrock, etc.) y el enrutamiento a herramientas específicas. Esta es la capa de orquestación central responsable del razonamiento, la construcción de prompts, el enrutamiento a las herramientas correctas y la devolución de respuestas formateadas.

  • Convención de nomenclatura: Principal - Lógica de [Nombre del Agente]
  • Ejemplo: Principal - Lógica de Herramientas del Agente de IA

③ Herramientas (Opcional)

Puede 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 la interacción con una fuente de datos. Deben ser sin estado y reutilizables.

  • Convención de nombres: Tool - [Acción]
  • Ejemplos:
    • Tool - Detalles del Pedido del Cliente
    • Tool - Obtener Detalles de la Cuenta
    • Tool - Recuperar Historial de Casos

④ Utilidades (Opcional)

Puede tener múltiples procesos auxiliares compartidos. Estas son operaciones de apoyo o transversales. Por ejemplo, cargas de blobs, registro de errores o escrituras en la tienda de datos.

  • Convención de nombres: Utility - [Acción]
  • Ejemplos:
    • Utility - Cargar Formularios de Pedido del Cliente a Azure
    • Utility - Cargar a Blob de Azure
    • Utility - Formatear JSON

Diseño de flujo de trabajo y desacoplamiento

Para asegurar que su agente sea mantenible y escalable, debe imponer una estricta separación de preocupaciones.

Desacoplar herramientas de la lógica principal

Cada flujo de trabajo de herramienta (como Tool - Obtener Cuentas) debe ser independiente y llamable de forma autónoma. No debe asumir ningún contexto de orquestación de UI o IA.

Asegurar independencia de la UI

El flujo de trabajo Main - Lógica del Agente 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 (controlador de Slack, controlador genérico, etc.) solo debe traducir las solicitudes entrantes en un formato de carga útil interno común para las llamadas a LLM. El siguiente diagrama muestra esta arquitectura en capas:

--- 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 configuración con variables de proyecto

Defina configuraciones específicas del entorno (claves API, puntos finales, etc.) como variables de proyecto, no como valores codificados.

Integración de LLM

No incruste llamadas directas a la API de LLM dentro de su lógica de orquestación principal. En su lugar, cree una capa de abstracción de LLM y construya los prompts dinámicamente.

Crear una capa de abstracción de LLM

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

Construir prompts dinámicamente

Construir prompts dinámicamente pero en una estructura controlada:

  • Incluir contexto (datos recuperados, intención de consulta).
  • Usar roles de sistema y usuario claramente cuando lo soporte la API de LLM.
  • Mantener la temperatura y los límites de tokens a través de la configuración de variables del proyecto.

Gestionar datos de sesión y contexto

Almacenar datos de sesión transitorios y contexto de preguntas y respuestas del usuario en un almacén de datos. Jitterbit proporciona un almacén de datos nativo en la nube listo para usar para este propósito: Jitterbit Cloud Datastore.

Construir utilidades genéricas para reutilización

Construir utilidades genéricas si son comunes a múltiples flujos de trabajo para que puedan ser reutilizadas en diferentes flujos. Por ejemplo:

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

Evitar errores comunes

Tener cuidado de no implementar estos errores comunes:

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

  • Incrustar lógica de formato de UI (Slack, Teams) en flujos de trabajo de IA centrales.

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

Documentar tu proyecto de 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 puntos finales, flujos de trabajo principales, herramientas, almacén de datos).

  • Lista de puntos finales de origen y consumidores.

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

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