Best Practices für den Aufbau von KI-Agenten in Jitterbit Harmony

Einführung

Dieses Dokument beschreibt die empfohlene Architektur, Konventionen und Best Practices für die Entwicklung von KI-Agenten in Jitterbit Harmony mit Jitterbit Studio. Diese Richtlinien gewährleisten Skalierbarkeit, Wartbarkeit und Konsistenz bei allen KI-Agenten, die Sie erstellen.

Hinweis

Zu Lernzwecken verweisen Sie auf die Reaktiven, Kontextuellen oder Salesforce Q&A-Agenten oder GitHub-Agenten mit MCP, die über den Jitterbit Marketplace bereitgestellt werden, um eine Implementierung dieser Best Practices zu sehen.

Architektur der Kernkomponenten und Namenskonventionen

Ein gut gestalteter KI-Agent besteht aus modularen, entkoppelten Workflows mit klaren Grenzen zwischen Logik, Datenverarbeitung und externen Integrationen.

Ihre Architektur und Namenskonventionen (entscheidend für Lesbarkeit und Debugging) sollten auf diesen vier Kernkomponenten basieren, die im folgenden Diagramm mit Beispielen dargestellt sind:

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

① Haupteingang

Ein einzelner Haupteingangs-Workflow verarbeitet eingehende API-Anfragen, Authentifizierung und das Routing zur KI-Logik. Er kann durch Slack, Microsoft Teams, eine benutzerdefinierte UI, einen benutzerdefinierten API-Endpunkt usw. ausgelöst werden.

Namenskonvention: Haupteingang - [Handler-Name]
Beispiel: Haupteingang - Slack API-Anfrage-Handler

② KI-Logik

Ein einzelner KI-Logik-Workflow dient als das zentrale Gehirn des Agenten. Er verarbeitet die Kontextabfrage, LLM-Aufrufe (OpenAI, Amazon Bedrock usw.) und das Routing zu spezifischen Tools. Dies ist die zentrale Orchestrierungsschicht, die für das Denken, das Erstellen von Eingabeaufforderungen, das Routing zu den richtigen Tools und das Zurückgeben formatierter Antworten verantwortlich ist.

Namenskonvention: Haupt - [Agentenname] Logik
Beispiel: Haupt - KI-Agenten-Tools Logik

③ Tools (Optional)

Sie können mehrere unabhängige Module haben, die atomare Datenoperationen durchführen. Diese Workflows kapseln eine spezifische Geschäftsfunktion oder Interaktion mit einer Datenquelle ein. Sie sollten zustandslos und wiederverwendbar sein.

Namenskonvention: Tool - [Aktion]
Beispiele:
- Tool - Kundendaten zu Bestellungen
- Tool - Kontodetails abrufen
- Tool - Fallhistorie abrufen

④ Dienstprogramme (Optional)

Sie können mehrere gemeinsame Hilfsprozesse haben. Diese sind unterstützende oder bereichsübergreifende Operationen. Zum Beispiel Blob-Uploads, Fehlerprotokollierung oder Datenspeicher-Schreibvorgänge.

Namenskonvention: Utility - [Aktion]
Beispiele:
- Utility - Kundenbestellformulare in Azure hochladen
- Utility - In Azure Blob hochladen
- Utility - JSON formatieren

Workflow-Design und Entkopplung

Um sicherzustellen, dass Ihr Agent wartbar und skalierbar ist, müssen Sie eine strikte Trennung der Anliegen durchsetzen.

Werkzeuge von der Hauptlogik entkoppeln

Jeder Tool-Workflow (wie Tool - Konten abrufen) muss eigenständig und unabhängig aufrufbar sein. Er sollte keinen UI- oder AI-Orchestrierungskontext annehmen.

UI-Unabhängigkeit sicherstellen

Der Workflow Main - Agent Logic darf nicht von einer spezifischen Benutzeroberfläche wie Slack, Microsoft Teams oder einer generischen API abhängen. Der Haupt-Einstiegs-Workflow (Slack-Handler, generischer Handler usw.) sollte nur eingehende Anfragen in ein gemeinsames internes Payload-Format für LLM-Aufrufe übersetzen. Das folgende Diagramm zeigt diese geschichtete Architektur:

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

Konfigurationswerte mit Projektvariablen zentralisieren

Definieren Sie umgebungsspezifische Konfigurationen (API-Schlüssel, Endpunkte usw.) als Projektvariablen, nicht als fest codierte Werte.

LLM-Integration

Binden Sie keine direkten API-Aufrufe an LLMs in Ihre Hauptorchestrierungslogik ein. Erstellen Sie stattdessen eine LLM-Abstraktionsschicht und konstruieren Sie Aufforderungen dynamisch.

Erstellen Sie eine LLM-Abstraktionsschicht

Erstellen Sie einen speziellen Utility-Workflow zum Aufrufen des LLM (wie Utility - Azure OpenAI aufrufen). Dies macht den Wechsel zu einem anderen LLM-Anbieter wie Amazon Bedrock oder Anthropic Claude trivial.

Konstruiere Aufforderungen dynamisch

Konstruiere Aufforderungen dynamisch, jedoch in einer kontrollierten Struktur:

Kontext einbeziehen (abgerufene Daten, Abfrageabsicht).
System- und Benutzerrollen klar verwenden, wenn dies von der LLM-API unterstützt wird.
Temperatur- und Tokenlimits über die Konfiguration von Projektvariablen aufrechterhalten.

Verwalte Sitzungs- und Kontextdaten

Speichere vorübergehende Sitzungs- und Benutzerfrage- und Antwortkontexte in einem Datenspeicher. Jitterbit bietet einen sofort einsatzbereiten cloud-nativen Datenspeicher für diesen Zweck: Jitterbit Cloud Datastore.

Baue generische Hilfsprogramme zur Wiederverwendbarkeit

Baue generische Hilfsprogramme, wenn sie in mehreren Workflows häufig vorkommen, damit sie in verschiedenen Workflows wiederverwendet werden können. Zum Beispiel:

Utility - Hochladen in Azure Blob
Utility - Schreiben in Datenspeicher
Utility - Slack Payload analysieren
Utility - OpenAI aufrufen

Vermeide häufige Fallstricke

Achte darauf, diese häufigen Fehler nicht zu implementieren:

Konfiguration hartkodieren, anstatt Projektvariablen zu verwenden.
UI-Formatierungslogik (Slack, Teams) in den Kern-AI-Workflows einbetten.
Monolithische Workflows erstellen, die mehrere nicht verwandte Prozesse behandeln.

Dokumentiere dein AI-Agent-Projekt

Jedes AI-Agent-Projekt sollte die folgende Dokumentation enthalten, um neuen Entwicklern zu helfen und für zukünftige Wartung:

Architekturdiagramm (zeigt Endpunkte, Haupt-Workflows, Werkzeuge, Datenspeicher).
Liste der Quell- und Verbraucherendpunkte.
Liste der erstellten Azure Blob-Container und Datenspeichertabellen.
Liste der benutzerdefinierten APIs des API-Managers und deren Zweck.