NeuSo funktioniert es
FirstSales
Startseite/Tutorials/FirstSales mit Gemini verwenden
Entwickler & CLI

FirstSales mit Gemini verwenden

Verbinden Sie Gemini mit FirstSales über die REST-API mit eng begrenzten Funktionstools — lesen vor schreiben, Berechtigungen pro Tool und sichere, überprüfbare Änderungen.

8 Min. Lesezeit·Experte·6 Schritte
  1. 1

    Zwei Wege, Gemini anzubinden

    Wenn Ihre Gemini-Umgebung (z. B. die Gemini CLI mit Shell-Zugriff) npm ausführen kann, installieren Sie @firstsales.io/cli und stellen Sie sie als Tool bereit — sie übernimmt Auth, JSON und Idempotenz. Läuft Gemini nur über eine API, rufen Sie die FirstSales Developer API per HTTPS aus Ihren Funktions-/Tool-Implementierungen auf. In der Dokumentation wird Gemini standardmäßig zu den API-first-Agenten gezählt.

  2. 2

    Den Schlüssel außerhalb des Modells speichern

    Erstellen Sie einen Developer-API-Schlüssel unter Settings → API und bewahren Sie ihn serverseitig in Ihrer App-Konfiguration als FIRSTSALES_API_KEY auf. Gemini sollte ein Tool/eine Funktion aufrufen, das den Schlüssel serverseitig liest — das Modell selbst darf den rohen Schlüssel nie sehen oder ausgeben.

    FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io
  3. 3

    Enge Tools definieren, keine rohe HTTP-Fluchttür

    Geben Sie Gemini eine kleine Menge zweckgebundener Funktionen — whoami, list_contacts, create_contact, campaign_analytics — jede davon einem einzigen öffentlichen Endpunkt zugeordnet. So bleibt das Modell auf der unterstützten Oberfläche, statt beliebige URLs konstruieren zu können.

    # what each tool calls under the hood
GET  /api/v1/whoami
GET  /api/v1/organizations/{org}/workspaces/{ws}/contacts
POST /api/v1/organizations/{org}/workspaces/{ws}/contacts     # Idempotency-Key
GET  /api/v1/organizations/{org}/workspaces/{ws}/campaigns/{id}/analytics
  4. 4

    Identität beim ersten Tool-Aufruf verifizieren

    Lassen Sie den Agenten vor jedem Schreibvorgang whoami aufrufen, damit er Org- und Workspace-Kontext bestätigt:

    curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  5. 5

    Aus dem Create-Tool idempotent schreiben

    Ihr create_contact-Tool sollte immer einen Idempotency-Key mitschicken, damit ein wiederholter Funktionsaufruf nicht doppelt schreibt:

    curl -X POST \
  https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-lead-2026-01" \
  -d '{"email":"lead@acme.com","first_name":"Sam"}'
  6. 6

    Fehler behandeln und auf der öffentlichen Oberfläche bleiben

    Behandeln Sie in jedem Tool 401 (falscher/widerrufener Schlüssel), 422 (Validierung — das betroffene Feld ausgeben) und 429 (drosseln, dann erneut versuchen). Bei unsupported_operation geben Sie die Einschränkung an das Modell zurück und stoppen — lassen Sie Gemini niemals die App scrapen oder private Routen, Callbacks, Pixel oder Cron-Endpunkte ansprechen.

Profi-Tipps

Hart erarbeitete Abkürzungen, damit die Aufwärmung auf Kurs bleibt.

1

Endpunkte als enge Tools verpacken

Geben Sie Gemini keine generische 'beliebige URL aufrufen'-Funktion. Zweckgebundene Tools (create_contact, campaign_analytics) halten das Modell auf der öffentlichen Oberfläche und machen seine Aktionen auditierbar.

2

Das Modell fasst den Schlüssel nie an

Lesen Sie FIRSTSALES_API_KEY serverseitig innerhalb des Tools. Kann der Schlüssel im Kontext oder in der Ausgabe des Modells erscheinen, kann er in Logs landen.

3

whoami als ersten Funktionsaufruf

Machen Sie die Identitätsprüfung zum Eröffnungsschritt, damit Gemini Org/Workspace immer vor dem Schreiben bestätigt.

4

Shell vorhanden? Die CLI ist weniger Code

Hat die Gemini CLI Shell- und npm-Zugriff, schlägt ein Aufruf der firstsales-CLI das manuelle Bauen von HTTP-Tools — Auth, JSON, Idempotenz und Lösch-Bestätigung gibt es gratis dazu.

Häufig gestellte Fragen

Nutzt Gemini die CLI oder die API?

Standardmäßig die Developer API, als Funktionen/Tools verpackt. Hat Ihre Gemini-Umgebung Shell-Zugriff mit npm, ist die CLI eine aufwandsärmere Alternative, die Auth und Idempotenz für Sie übernimmt.

Wie halte ich den Schlüssel vom Modell fern?

Speichern Sie FIRSTSALES_API_KEY in der serverseitigen Konfiguration und lesen Sie ihn innerhalb der Tool-Implementierung. Das Modell ruft das Tool auf; es sieht oder gibt den rohen Schlüssel nie aus.

Wie sollte ich die Tools strukturieren?

Als enge, einzweckige Funktionen — eine pro öffentlichem Endpunkt (whoami, Kontakt auflisten/erstellen, Kampagnen-Analytics). Vermeiden Sie ein generisches 'beliebige URL abrufen'-Tool, das dem Modell erlaubt, die unterstützte Oberfläche zu verlassen.

Wie vermeide ich doppelte Schreibvorgänge?

Fügen Sie innerhalb Ihres Create-Tools einen Idempotency-Key-Header hinzu. Ein wiederholter Funktionsaufruf mit demselben Schlüssel liefert das ursprüngliche Ergebnis zurück, statt ein Duplikat zu erstellen.

Was ist tabu?

App-interne Routen, Anbieter-Callbacks, Tracking-Pixel, Abmelde-Handler, interne Cron-Endpunkte und das Scrapen der Oberfläche. Bleiben Sie auf der öffentlichen /api/v1; stoppen Sie bei unsupported_operation.

Bereit, das in die Praxis umzusetzen?

Starten Sie Ihre FirstSales-Testphase und richten Sie in wenigen Minuten ein aufgewärmtes, authentifiziertes Postfach ein.

Für 1 $ starten
Alle Tutorials