- Hinzufügen einer Workflow-Aktionskomponente zu einer App durch Berücksichtigen eines
workflow-actions-Verzeichnisses im Projekt zusammen mit einer*-hsmeta.json-Konfigurationsdatei für das Tool. Jedes Tool und jede Workflow-Aktion, die Sie erstellen, sollte über eine eigene*-hsmeta.json-Konfigurationsdatei verfügen. - Konfigurieren der Aktion, damit diese in KI-Agents über das
supportedClients-Feld verfügbar ist.
Projekteinrichtung
Um Tools zu erstellen, muss in Ihrerhsproject.json-Datei die platformVersion auf 2025.2 festgelegt sein. Diese Version wird in allen Schnellstart-Vorlagen automatisch bestimmt. Für Projekte mit älteren Versionen ist es allerdings erforderlich, die Aktualisierung manuell vorzunehmen.
Beachten Sie bitte, dass beim Upgrade eines Projekts auf die Version 2025.2 die neuen *-hsmeta.json-Konfigurationsdateistandards für die App-Konfiguration und Funktionen einzuhalten sind.
Agent-Tools und benutzerdefinierte Workflow-Aktionen sind beide im workflow-actions-Verzeichnis der App enthalten.
Definition des Agent-Tools
Die Konfigurationsdatei Ihrer Tools muss imworkflow-actions-Verzeichnis abgelegt werden, um zu funktionieren. Die Konfigurationsoptionen für Agent-Tools sind die gleichen wie für benutzerdefinierte Workflow-Aktionen, mit der zusätzlichen Anforderung, dass das supportedClients-Feld den AGENTS-Client enthalten muss.
Mit * markierte Felder sind Pflichtfelder.
Bewährte Methoden
Berücksichtigen Sie beim Erstellen von Agent-Tools die folgende Checkliste mit bewährten Methoden:- Beginnen Sie mit optionalen Feldern und setzen Sie sie dieser nur dann auf erforderlich, wenn sie stabil sind.
- Felder sollen sowohl für Menschen als auch für KI gekennzeichnet und beschrieben werden.
- Testen Sie zunächst mit weniger Agent-Anweisungen, um zu verstehen, wie die KI ein Tool interpretiert.
- Achten Sie darauf, dass die Tools fokussiert sind und denken Sie an die Anzahl der Felder.
- Verwenden Sie Feldbeschreibungen, um die Kreativität Ihres Agent zu steuern.
Mit optionalen Feldern entwickeln
Legen Sie Aktionsfelder (inputFields) während der aktiven Entwicklung nicht als „erforderlich“ fest. Sobald ein Feld als erforderlich festgelegt und das Projekt hochgeladen wird, können Sie das Feld nicht mehr entfernen oder aktualisieren. Sie sollten ein Feld nur dann als erforderlich bestimmen, wenn Sie sich über die Details des Feldes, z. B. name und type, sicher sind. Die Änderung erforderlicher Felder würde nämlich alle aktiven Workflows, die die Aktion enthalten, unterbrechen.
Für menschliches und KI-Verständnis konzipiert
Die Verwendung und der Nutzen vonactionName, inputFields und labels sollte sowohl für Menschen als auch für den Agent klar verständlich sein. Insbesondere diese Felder werden vom Agent verwendet, um zu verstehen, wann die Aktion aufgerufen werden soll und wie Daten an das Tool zu übermitteln sind. Denken Sie bei der Entwicklung Ihrer Tools daran, dass LLMs möglicherweise explizitere Beschreibungen benötigen als menschliche Nutzende. Während beispielsweise ein Mensch ein Feld mit der Bezeichnung Date intuitiv versteht, könnte ein LLM Event start date (YYYY-MM-DD) bevorzugen.
Idealerweise sollten Tools so konzipiert sein, dass Agents keine zusätzlichen Anweisungen benötigen, um sie zu benutzen. Es gibt jedoch Fälle, in denen Feldangaben allein für den Agent möglicherweise nicht ausreichen. Möglicherweise versteht der Agent nicht die geplante Operationsfolge für die Ausführungen von Tools, die von anderen Tool-Outputs abhängig sind (z. B. ist ein „E-Mail senden“-Tool eventuell davon abhängig, dass ein „Kontaktinformationen abrufen“-Tool ausgeführt wurde).
Während Sie ein Tool erstellen, sollten Sie es im Agent testen, ohne die Anweisungen des Agent zu ergänzen, um so besser zu verstehen, wie das Tool interpretiert wird. Durch Tests können Sie feststellen, ob die Reasoning Engine von sich aus korrekt funktioniert oder ob sie zusätzliche Anweisungen benötigt.
Die Anzahl der Eingabefelder beachten
Agents können in jedem Tool eine große Anzahl von Eingabefeldern verarbeiten (maximal 26 eindeutige Eingaben). Je mehr Eingabefelder es jedoch in einem Tool gibt, desto übersichtlicher müssen Sie bei dem Zuweisen vonactionName-, inputField- und label-Werten sein. Tools sind am effektivsten und zuverlässigsten, wenn sie für bestimmte Aufgaben mit einem spezifischen Parameterset entwickelt wurden. Überlegen Sie bei komplexen Vorgängen, ob es effektiver ist, mehrere einfachere Tools statt ein einzelnes Tool mit einer übermäßigen Anzahl an Inputs zu erstellen.
Kreativität und Improvisation von Agents kontrollieren
In manchen Szenarien möchten Sie vielleicht, dass ein Agent kreativ ist und improvisiert. Es kann jedoch Szenarien geben, in denen dies unerwünscht ist. Experimentieren Sie mit den Anweisungen, die Sie dem LLM in Ihren Eingabefeldnamen, Labels und Beschreibungen geben. Wenn ein strikteres Vorgehen erforderlich ist, formulieren Sie dies für den Agent entsprechend, um Ihre Erwartungen klar und deutlich zu formulieren. Ein Beispiel: Sie übertragen einem Agent die Aufgabe, einen Blogbeitrag zu erstellen. Dabei ist eines der Felder der Titel des Blogbeitrags. Je nach der von Ihnen gewünschten Improvisationsfreiheit können Sie das Feld mit einem großzügigen oder restriktiveren Label ausstatten:- Großzügig:
"Blog title" - Restriktiv:
"Blog title (must include the product name 'HubSpot CRM')"
- Großzügig:
"Social post content" - Regulär:
"Social post content (keep under 280 characters)" - Einschränkend:
"Social post content (must mention our Q4 sale, include #HubSpot, and stay under 280 characters)"
Herkunft von Agent-Tool-Anfragen verifizieren
Wenn ein Agent ein Tool für eine Anfrage nutzt, stellt er einePOST-Anfrage an die actionUrl des Tools. Dieser Schritt wird authentifiziert durch die Validierung des mit der Anfrage gesendete X-HubSpot-Signature-Headers. Dabei handelt es sich um das gleiche System, das HubSpot zur Validierung von Webhook-Anfragen verwendet.