Best Practices für die Entwicklung von KI-Agenten in Jitterbit Harmony

Einleitung

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 sichern Skalierbarkeit, Wartbarkeit und Konsistenz aller von Ihnen entwickelten KI-Agenten.

Hinweis

Zu Lernzwecken können Sie auf die reaktiven, kontextbezogenen oder Salesforce Q&A-Agenten oder den GitHub-Agent mit MCP verweisen, die über Jitterbit Marketplace bereitgestellt werden und diese Best Practices umsetzen.

Kerkomponentenarchitektur 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 in der Abbildung unten mit Beispielen dargestellt sind:

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

① Haupteingang

Ein einzelner Haupteingabe-Workflow verarbeitet eingehende API-Anfragen, Authentifizierung und Routing zur KI-Logik. Er kann von Slack, Microsoft Teams, einer benutzerdefinierten Benutzeroberfläche, einem benutzerdefinierten API-Endpunkt usw. ausgelöst werden.

Namenskonvention: Main Entry - [Handler-Name]
Beispiel: Main Entry - Slack API Request Handler

② KI-Logik

Ein einzelner KI-Logik-Workflow dient als zentrales Gehirn des Agenten. Er verarbeitet Kontextabruf, LLM-Aufrufe (OpenAI, Amazon Bedrock usw.) und Routing zu spezifischen Tools. Dies ist die zentrale Orchestrierungsebene, die für Reasoning, Prompt-Erstellung, Routing zum richtigen Tool und Rückgabe formatierter Antworten verantwortlich ist.

Namenskonvention: Main - [Agent-Name] Logic
Beispiel: Main - AI Agent Tools Logic

③ Tools (Optional)

Sie können mehrere unabhängige Module haben, die atomare Datenvorgänge ausführen. Diese Workflows encapsulieren eine spezifische Geschäftsfunktion oder Datenquelleninteraktion. Sie sollten zustandslos und wiederverwendbar sein.

Namenskonvention: Tool - [Aktion]
Beispiele:
- Tool - Customer Order Details
- Tool - Get Account Details
- Tool - Retrieve Case History

④ Utilities (Optional)

Sie können mehrere gemeinsame Hilfsprozesse haben. Dies sind unterstützende oder übergreifende Operationen. Beispielsweise Blob-Uploads, Fehlerlogging oder Datenspeicher-Schreibvorgänge.

Namenskonvention: Utility - [Aktion]
Beispiele:
- Utility - Upload Customer Order Forms to Azure
- Utility - Upload to Azure Blob
- Utility - Format JSON

Workflow-Design und Entkopplung

Um sicherzustellen, dass Ihr Agent wartbar und skalierbar ist, müssen Sie eine strikte Separation of Concerns durchsetzen.

Entkoppeln Sie Tools von der Hauptlogik

Jeder Tool-Workflow (wie Tool - Get Accounts) muss eigenständig und unabhängig aufgerufen werden können. Er sollte keine Annahmen über UI- oder KI-Orchestrierungs-Kontext treffen.

Sichern Sie UI-Unabhängigkeit

Der Workflow Main - Agent Logic darf nicht von einer bestimmten Benutzeroberfläche wie Slack, Microsoft Teams oder einer generischen API abhängen. Der Haupteingabe-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: 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

Zentralisieren Sie Konfigurationswerte mit Projektvariablen

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

LLM-Integration

Betten Sie keine direkten API-Aufrufe an LLMs in Ihre Hauptorcheststrierungslogik ein. Erstellen Sie stattdessen eine LLM-Abstraktionsschicht und konstruieren Sie Prompts dynamisch.

Erstellen Sie eine LLM-Abstraktionsschicht

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

Eingaben dynamisch konstruieren

Eingaben dynamisch, aber in einer kontrollierten Struktur konstruieren:

Kontext einbeziehen (abgerufene Daten, Abfrageabsicht).
System- und Benutzerrollen klar nutzen, wenn die LLM-API diese unterstützt.
Temperatur und Token-Limits über die Projektvariablenkonfiguration beibehalten.

Sitzungs- und Kontextdaten verwalten

Transiente Sitzungs- und Benutzer-Frage-Antwort-Kontextdaten in einem Datenspeicher speichern. Jitterbit bietet zu diesem Zweck einen einsatzbereiten cloudnativen Datenspeicher: Jitterbit Cloud Datastore.

Generische Utilities für Wiederverwendbarkeit erstellen

Generische Utilities erstellen, wenn diese für mehrere Workflows relevant sind, damit sie über Workflows hinweg wiederverwendet werden können. Zum Beispiel:

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

Häufige Fehler vermeiden

Darauf achten, diese häufigen Fehler nicht zu implementieren:

Konfiguration hart codieren statt Projektvariablen zu nutzen.
UI-Formatierungslogik (Slack, Teams) in KI-Kernworkflows einbetten.
Monolithische Workflows erstellen, die mehrere unabhängige Prozesse verarbeiten.

KI-Agent-Projekt dokumentieren

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

Architekturdiagramm (mit Endpunkten, Hauptworkflows, Tools, Datenspeicher).
Liste der Quell- und Consumer-Endpunkte.
Liste der erstellten Azure-Blob-Container und Datenspeichertabellen.
Liste der benutzerdefinierten APIs des API Manager und deren Zweck.