Zum Hauptinhalt springen
HubSpot Agents sind KI-gestützte Assistenten, mit denen Nutzende chatten können, um Aufgaben zu erledigen. Jeder Agent umfasst eine Reihe von Aktionen, sogenannte Tools, die er gemäß den Anweisungen des Benutzers einsetzt. Als Entwickler können Sie benutzerdefinierte Agent-Tools erstellen, um bestimmte, klar definierte Aufgaben je nach beabsichtigtem Anwendungsfall des Agents auszuführen. Tools sind eigentlich benutzerdefinierte Workflow-Aktionen, die so konfiguriert werden, dass sie im Agentenkontext verfügbar sind. Die Tools können über mehrere Agents hinweg verwendet und so konfiguriert werden, dass sie sowohl in Agents als auch in Workflows funktionieren. Im Wesentlichen umfasst die Erstellung eines Agent-Tools:
  • 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.
Bei der Entwicklung Ihrer Tools sollten Sie auch eine Reihe von Best Practices beachten, um eine höhere Leistungsqualität zu gewährleisten.

Projekteinrichtung

Um Tools zu erstellen, muss in Ihrer hsproject.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 im workflow-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.
In den folgenden Abschnitten erfahren Sie mehr über die einzelnen Best Practices.
Hinweis:Einige der folgenden Anleitungen enthalten zwar Informationen zum Testen von Agent-Tools, diese Testfunktionen befinden sich jedoch noch in der Entwicklung. Die Dokumentation der Agent-Tools wird aktualisiert, sobald Testmethoden zur Verfügung stehen.

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 von actionName, 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 von actionName-, 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.
Hinweis:Es ist möglich, dass HubSpot die Anzahl der Inputs in Zukunft beschränkt, basierend auf dem Feedback zur Qualität der Agents, die große Input-Mengen verarbeiten.

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')"
Hier ein weiteres Beispiel von möglichen Eingabefeld-Labels für Content von Social-Media-Beiträgen:
  • 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 eine POST-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.
Hinweis:Sie sollten keine Eingabefelder für Geheimnisse oder API-Schlüssel erstellen, da dies unsicher ist und nicht dem beabsichtigten Authentifizierungsmuster entspricht, insbesondere weil das LLM das Geheimnis/den API-Schlüssel in den Anweisungen erhalten oder von einem anderen Tool erhalten müsste.
Zuletzt geändert am 10. Februar 2026