Letzte Änderung: 11. September 2025
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.
├──src
   ├── hsproject.json
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── workflow-actions/
     └── agent-tool-action-hsmeta.json
└──

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.
{
  "uid": "agent_tool_action",
  "type": "workflow-action",
  "config": {
    "actionUrl": "https://example.com",
    "toolType": "GET_DATA",
    "llmDescription": "A description that helps the LLM understand what this tool does.",
    "isPublished": false,
    "supportedClients": [
      {
        "client": "AGENTS"
      },
      {
        "client": "WORKFLOWS"
      }
    ],
    "inputFields": [
      {
        "typeDefinition": {
          "name": "message",
          "type": "string",
          "fieldType": "textarea"
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      },
      {
        "typeDefinition": {
          "name": "priority",
          "type": "enumeration",
          "fieldType": "select",
          "options": [
            {
              "value": "high",
              "label": "High Priority"
            },
            {
              "value": "normal",
              "label": "Normal Priority"
            },
            {
              "value": "low",
              "label": "Low Priority"
            }
          ]
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send {{priority}} priority notification",
        "inputFieldLabels": {
          "message": "Notification Message",
          "priority": "Priority Level"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification",
          "priority": "Select the priority level for this notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}

Mit * markierte Felder sind Pflichtfelder.

FeldTypBeschreibung
uid*ZeichenfolgeEine interne eindeutige ID für die Workflow-Aktion.
type*ZeichenfolgeDer Typ der Komponente, die in diesem Fall workflow-action sein sollte.
actionUrl*ZeichenfolgeDie URL, an die das Tool eine POST-Anfrage stellt. Die URL muss ein öffentlich zugänglicher Endpunkt und darf keine serverlose Funktion sein, die im Entwicklerprojekt definiert ist.
toolType*ZeichenfolgeDie Kategorie der Toolfunktionalität. Kann einer der folgenden sein:
  • GET_DATA: Ruft Informationen von HubSpot oder externen Quellen ab.
  • GENERATE: generiert Inhalte, Zusammenfassungen, Analysen oder Vorschläge auf der Grundlage der bereitgestellten Eingaben.
  • TAKE_ACTION: führt CRM-Aktionen aus, z. B. das Erstellen von Notizen oder das Zuweisen von Aufgaben an zuständige Mitarbeiter.
llmDescription*ZeichenfolgeEine Beschreibung, die dem LLM hilft zu verstehen, was das Tool leistet.
isPublishedBoolescherWertBestimmt, ob die Definition in Accounts sichtbar ist, die Ihre App installiert haben. Standardmäßig ist dies auf falsefestgelegt.
supportedClients*ArrayEin Array von Objekten, das die Clients angibt, die von der benutzerdefinierten Workflow-Aktion unterstützt werden. Jedes Objekt im Array sollte einen client-Schlüssel mit einem Zeichenfolgenwert haben, der den Client-Typ angibt. Zu den Werten gehören:
  • WORKFLOWS: aktiviert die Aktion für Workflows.
  • AGENTS: aktiviert die Aktion für Mitarbeiter.
inputFieldsArrayDie Werte für die Eingaben, die der Benutzer ausgefüllt hat. Erfahren Sie mehr über bewährte Verfahren bezüglich der Anzahl von Feldern.
typeDefinition.nameZeichenfolgeDer Name oder Schlüssel des Eingabefelds.
typeDefinition.typeZeichenfolgeDer Werttyp, der für das Eingabefeld gelten soll.
typeDefinition.fieldTypeZeichenfolgeDer Feldtyp, der den Benutzern angezeigt wird, die den Workflow erstellen.
typeDefinition.optionsArrayDieses Feld enthält für Aufzählungstypen eine Liste von Optionen. Jede Option muss über ein value verfügen, das auf den Eingaben des Benutzers basiert, und ein label, das die Option im Workflows-Tool identifiziert.
inputFieldDependenciesArrayEine Liste von Regeln, die die Beziehungen zwischen zwei oder mehr Eingaben basierend auf ihrem dependencyType definieren. Erfahren Sie mehr dazu in diesem Beispiel.
labels.<locale>*ZeichenfolgeGebietsschemaschlüssel, der der Gebietsschemadefinition zugeordnet ist. Er muss mindestens ein englisches Label (en) umfassen und seine Definition gleichzeitig klar bestimmt sein.
labels.<locale>.inputFieldDescriptionsObjektEin Objekt, das die Details für die Eingaben für Ihre Aktion definiert. Im obigen Beispiel enthält dieses Objekt message- und priority-Felder.
labels.<locale>.inputFieldOptionLabelsObjektEin Objekt, das erforderlich ist, wenn Ihr(e) Eingabefeld(er) über Optionen verfügt/en. Bietet eine Zuordnung von Eingabefeldoptionslabeln, die durch den Wert oder das Label der Option geschlüsselt sind.
labels.<locale>.outputFieldLabelsObjektEin Objekt, das die Definitionen von outputFields den entsprechenden Label zuordnet, die im Workflows-Tool angezeigt werden.
labels.<locale>.actionName*ZeichenfolgeDer Name der Aktion, wie im Bereich Aktion auswählen im Workflows-Editor angezeigt.
labels.<locale>.appDisplayName*ZeichenfolgeDer Name des Abschnitts im Bereich Aktion auswählen, in dem alle Aktionen für die App angezeigt werden. Wenn appDisplayName für mehrere Aktionen definiert ist, wird die erstgefundene verwendet.
labels.<locale>.actionCardContentZeichenfolgeEine zusammengefasste Beschreibung, die auf der Karte der Aktion angezeigt wird.
labels.<locale>.executionRulesObjektEin Objekt, das die Definitionen von Ihren executionRules Nachrichten zuordnet, die im Rahmen der Ausführung im Workflow-Verlauf angezeigt werden.
objectTypesArrayDie verfügbaren CRM-Objekttypen, mit denen diese Aktion verwendet werden kann. Ist hier kein Wert vorhanden, ist die Aktion für alle Objekttypen verfügbar.
outputFieldsArrayDie Werte, die die Aktion ausgibt und die bei späteren Aktionen im Agent oder Workflow verwendet werden können. Eine benutzerdefinierte Aktion kann einen Output von 0, 1 oder mehrere Outputs haben.
executionRulesObjektEine Liste der Definitionen, die Sie angeben können, damit dem Benutzer, der den Workflow erstellt, Fehler von Ihrem Dienst angezeigt werden.

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.