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.
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.
Feld | Typ | Beschreibung |
---|---|---|
uid * | Zeichenfolge | Eine interne eindeutige ID für die Workflow-Aktion. |
type * | Zeichenfolge | Der Typ der Komponente, die in diesem Fall workflow-action sein sollte. |
actionUrl * | Zeichenfolge | Die 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 * | Zeichenfolge | Die Kategorie der Toolfunktionalität. Kann einer der folgenden sein:
GENERATE : generiert Inhalte, Zusammenfassungen, Analysen oder Vorschläge auf der Grundlage der bereitgestellten Eingaben. |
llmDescription * | Zeichenfolge | Eine Beschreibung, die dem LLM hilft zu verstehen, was das Tool leistet. |
isPublished | BoolescherWert | Bestimmt, ob die Definition in Accounts sichtbar ist, die Ihre App installiert haben. Standardmäßig ist dies auf false festgelegt. |
supportedClients * | Array | Ein 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:
|
inputFields | Array | Die 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.name | Zeichenfolge | Der Name oder Schlüssel des Eingabefelds. |
typeDefinition.type | Zeichenfolge | Der Werttyp, der für das Eingabefeld gelten soll. |
typeDefinition.fieldType | Zeichenfolge | Der Feldtyp, der den Benutzern angezeigt wird, die den Workflow erstellen. |
typeDefinition.options | Array | Dieses 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. |
inputFieldDependencies | Array | Eine 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> * | Zeichenfolge | Gebietsschemaschlüssel, der der Gebietsschemadefinition zugeordnet ist. Er muss mindestens ein englisches Label (en ) umfassen und seine Definition gleichzeitig klar bestimmt sein. |
labels.<locale>.inputFieldDescriptions | Objekt | Ein 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>.inputFieldOptionLabels | Objekt | Ein 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>.outputFieldLabels | Objekt | Ein Objekt, das die Definitionen von outputFields den entsprechenden Label zuordnet, die im Workflows-Tool angezeigt werden. |
labels.<locale>.actionName * | Zeichenfolge | Der Name der Aktion, wie im Bereich Aktion auswählen im Workflows-Editor angezeigt. |
labels.<locale>.appDisplayName * | Zeichenfolge | Der 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>.actionCardContent | Zeichenfolge | Eine zusammengefasste Beschreibung, die auf der Karte der Aktion angezeigt wird. |
labels.<locale>.executionRules | Objekt | Ein Objekt, das die Definitionen von Ihren executionRules Nachrichten zuordnet, die im Rahmen der Ausführung im Workflow-Verlauf angezeigt werden. |
objectTypes | Array | Die 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. |
outputFields | Array | Die 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. |
executionRules | Objekt | Eine 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.
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 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.
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')"
- 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.
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.