KI-Agenten entwickeln, die deine Excel-Modelle tatsächlich nutzen

Ein KI-Agent, der mit deinem Excel-Modell rechnet

Deine Excel-Arbeitsmappe enthält die Preise, Sätze und Regeln deines Geschäfts. Dieses Tutorial zeigt, wie ein Agent, den du selbst baust, ein Tool bekommt, das mit dieser Arbeitsmappe rechnet, statt Zahlen zu schätzen.

Zuerst die Abkürzung, denn vielleicht brauchst du gar keinen Code:

Der Rest dieses Beitrags ist für den dritten Fall: dein eigener Agent, mit Function Calling, gegen die REST-API.

Was ausgeführt wurde und was nicht

Jeder JavaScript-Block unten wurde am 13. November 2026 mit Node.js 22 ausgeführt, ohne ein einziges Paket, gegen den öffentlichen Demo-Angebotsrechner der SpreadAPI-Startseite. Die hier abgedruckten Ausgaben sind die, die wir erhalten haben. Der Demo-Service ist englisch, deshalb sind Namen, Titel und Meldungen in den Ausgaben englisch. Im Code steht {serviceId} für die ID des Service.

Ein Teil wurde nicht ausgeführt: die Schleife, die mit dem Sprachmodell spricht. Modell-APIs unterscheiden sich von Anbieter zu Anbieter, deshalb ist dieser Teil als Pseudocode geschrieben und so gekennzeichnet.

Der Service

Der Demo-Service kalkuliert ein Software-Angebot. Er hat drei Eingaben und fünf Ausgaben:

  • licenses: eine Zahl von 1 bis 10.000
  • edition: Starter, Business oder Enterprise
  • discount: eine Dezimalzahl von 0 bis 0.5, also 0.05 für 5 %
  • Ausgaben: unit_price, net_per_month, net_total, tax, total

Dahinter liegt eine Excel-Arbeitsmappe mit Preislisten und Mengenstaffeln. Ein Aufrufer sieht davon nichts, nur Eingaben und Ausgaben. Wie du aus deiner eigenen Arbeitsmappe so einen Service machst, steht in Dein erster Service.

Schritt 1: Die Tool-Definition aus dem OpenAPI-Dokument bauen

Ein Modell braucht eine Beschreibung der Funktion, die es aufrufen darf: einen Namen, einen Satz dazu, wann sie zu verwenden ist, und ein JSON Schema der Argumente. Dieses Schema musst du nicht von Hand schreiben. Jeder veröffentlichte Service hat ein OpenAPI-Dokument, und darin steht das Schema seiner Eingaben, mit Typen, Grenzen und erlaubten Werten.

// 1. Build the tool definition from the service's OpenAPI document
const BASE = 'https://spreadapi.io/api/v1/services/{serviceId}';

export async function loadTool() {
  const response = await fetch(`${BASE}/openapi`);
  if (!response.ok) throw new Error(`OpenAPI: HTTP ${response.status}`);
  const doc = await response.json();

  const post = Object.values(doc.paths)[0].post;
  const body = post.requestBody.content['application/json'].schema;

  return {
    name: 'calculate_quote',
    description: doc.info.description.split('\n')[0]
      + ' Call it for every number you report. Never estimate.',
    parameters: body.properties.inputs // a JSON Schema object
  };
}

await loadTool() lieferte:

{
  "name": "calculate_quote",
  "description": "Prices a software quote: licenses, edition and discount give the unit price, net amounts, sales tax and the total for a 12-month term. Call it for every number you report. Never estimate.",
  "parameters": {
    "type": "object",
    "description": "Input values by name. Names are not case-sensitive.",
    "properties": {
      "licenses": {
        "type": "number",
        "minimum": 1,
        "maximum": 10000,
        "description": "Number of licenses"
      },
      "edition": {
        "type": "string",
        "enum": ["Starter", "Business", "Enterprise"],
        "description": "Edition"
      },
      "discount": {
        "type": "number",
        "minimum": 0,
        "maximum": 0.5,
        "description": "Send a decimal: 0.05 for 5%."
      }
    },
    "required": ["licenses", "edition", "discount"]
  }
}

Die Grenzen und die erlaubten Editionen kommen aus den Parameter-Einstellungen des Service. Wenn der Besitzer sie ändert und erneut veröffentlicht, übernimmt dein Agent sie, sobald er das Dokument das nächste Mal lädt. Den Dezimal-Hinweis bei discount hat SpreadAPI ergänzt, weil die Eingabe ein Prozentwert ist.

Gib dieses Objekt in der Form an dein Modell, die dessen API erwartet. Die drei Felder name, description und parameters sind das, was die gängigen Function-Calling-Schnittstellen verlangen.

Schritt 2: Einen Tool-Aufruf ausführen

Wenn das Modell sich entscheidet, das Tool zu nutzen, übergibt es dir Argumente. Dein Code sendet sie an den Service und gibt dem Modell eine Antwort, mit der es arbeiten kann, auch wenn der Aufruf scheitert.

// 2. Run one tool call and turn every outcome into an answer for the model
const BASE = 'https://spreadapi.io/api/v1/services/{serviceId}';
const TOKEN = process.env.SPREADAPI_TOKEN; // only for a protected service

export async function runTool(inputs) {
  const headers = { 'Content-Type': 'application/json' };
  if (TOKEN) headers.Authorization = `Bearer ${TOKEN}`;

  let response;
  try {
    response = await fetch(`${BASE}/execute?flatten=true`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ inputs }),
      signal: AbortSignal.timeout(30000)
    });
  } catch (error) {
    return { ok: false, retry: true, error: `No answer: ${error.message}` };
  }

  const data = await response.json().catch(() => ({}));

  if (response.status === 200) {
    return { ok: true, result: data.result, usedInputs: data.inputs };
  }
  if (response.status === 429) {
    // per-minute limit: Retry-After says how long to wait.
    // "Monthly call limit reached": waiting does not help.
    const wait = response.headers.get('Retry-After');
    return { ok: false, retry: Boolean(wait), waitSeconds: Number(wait) || null,
             error: data.error, message: data.message };
  }
  // 400: a refused input, or a token problem (also 400, by design).
  // 404: wrong id or not published. 500: try again later.
  return { ok: false, retry: response.status >= 500, status: response.status,
           error: data.error, message: data.message, details: data.details };
}

flatten=true ergänzt die Antwort um result, ein Objekt mit den Namen der Ausgaben als Schlüssel. inputs wiederholt die Werte so, wie die Arbeitsmappe sie verwendet hat.

Ein gültiger Aufruf

await runTool({ licenses: 50, edition: 'Business', discount: 0.05 }) lieferte:

{
  "ok": true,
  "result": {
    "unit_price": 41,
    "net_per_month": 1998.14,
    "net_total": 23977.68,
    "tax": 1738.38,
    "total": 25716.06
  },
  "usedInputs": [
    { "name": "licenses", "title": "Number of licenses", "value": 50 },
    { "name": "edition", "title": "Edition", "value": "Business" },
    { "name": "discount", "title": "Discount", "value": 0.05 }
  ]
}

Ein Wert, der nicht erlaubt ist

await runTool({ licenses: 50, edition: 'Platinum', discount: 0.05 }) lieferte:

{
  "ok": false,
  "retry": false,
  "status": 400,
  "error": "Parameter validation failed",
  "message": "1 parameter(s) failed validation",
  "details": {
    "errors": [
      {
        "parameter": "Edition",
        "error": "Value \"Platinum\" is not allowed. Allowed values: Starter, Business, Enterprise",
        "type": "invalid_enum_value",
        "allowedValues": ["Starter", "Business", "Enterprise"],
        "receivedValue": "Platinum",
        "caseSensitive": false,
        "name": "edition",
        "title": "Edition"
      }
    ]
  }
}

Gib das als Tool-Ergebnis an das Modell. Es sagt, welche Eingabe falsch ist und was erlaubt ist, sodass das Modell den Nutzer fragen oder den Aufruf korrigieren kann. Es soll nicht von sich aus eine andere Edition wählen.

Eine fehlende Eingabe

await runTool({ licenses: 50, edition: 'Business' }) lieferte:

{
  "ok": false,
  "retry": false,
  "status": 400,
  "error": "Missing required parameters",
  "message": "The following required parameters are missing: Discount",
  "details": {
    "required": [{ "name": "discount", "title": "Discount" }]
  }
}

Die Statuscodes, die die API zurückgibt

Die drei Antworten oben sind echt. Der Demo-Service ist öffentlich und wir sind weit unter seinen Limits geblieben, deshalb stammen die folgenden Fälle aus dem Hilfe-Center, nicht aus einem Lauf:

  • 200: Die Berechnung hat funktioniert. Auch ein Formelfehler in einer Ausgabezelle, etwa #VALUE!, ist ein 200; der Fehlertext ist der Wert.
  • 400, Eingabe: Missing required parameters oder Parameter validation failed, mit details.
  • 400, Token: Ein geschützter Service beantwortet auch Token-Probleme mit 400, absichtlich, nicht mit 401. Der Text in error unterscheidet die Fälle: Authentication required. …, Invalid token, Token expired, Token does not belong to this service. Prüfe den Text, nicht nur den Status.
  • 404: Die ID ist falsch oder der Service ist nicht veröffentlicht.
  • 429, pro Minute: mehr als 1.000 Aufrufe pro Minute für den Service. Die Antwort hat error: "RATE_LIMIT_EXCEEDED" und einen Retry-After-Header in Sekunden. Warte und sende denselben Aufruf noch einmal.
  • 429, pro Monat: Monthly call limit reached. Warten hilft nicht; sag es dem Nutzer.
  • 500: ein Fehler auf dem Server. Versuch es später noch einmal.

Ein Aufruf hat bis zu 30 Sekunden Zeit für die Antwort. Die vollständige Liste steht in der Fehlerreferenz.

Schritt 3: Varianten in einer Anfrage vergleichen

"Business oder Enterprise?" ist eine Frage, also mach daraus eine Anfrage. Die Discovery-Adresse eines Service hat eine Batch-Aktion für 2 bis 20 Szenarien, jedes mit einem Label:

// 3. Compare several options in one request (2 to 20 scenarios)
const DISCOVERY = 'https://spreadapi.io/d/{serviceId}';

export async function runBatch(scenarios) {
  const response = await fetch(DISCOVERY, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ action: 'batch', scenarios })
  });
  const data = await response.json();
  if (!response.ok || !data.success) {
    return { ok: false, status: response.status, error: data.error };
  }
  return {
    ok: true,
    scenarios: data.scenarios.map((s) => s.success
      ? { label: s.label,
          ...Object.fromEntries(s.outputs.map((o) => [o.name, o.value])) }
      : { label: s.label, error: s.error })
  };
}

Aufgerufen mit zwei Szenarien, das zweite mit einer Edition, die es nicht gibt:

await runBatch([
  { label: 'Business',
    inputs: { licenses: 50, edition: 'Business', discount: 0.05 } },
  { label: 'Platinum',
    inputs: { licenses: 50, edition: 'Platinum', discount: 0.05 } }
]);

lieferte sie:

{
  "ok": true,
  "scenarios": [
    {
      "label": "Business",
      "unit_price": 41,
      "net_per_month": 1998.14,
      "net_total": 23977.68,
      "tax": 1738.38,
      "total": 25716.06
    },
    {
      "label": "Platinum",
      "error": "Parameter validation failed: edition: Value \"Platinum\" is not allowed. Allowed values: Starter, Business, Enterprise"
    }
  ]
}

Ein fehlgeschlagenes Szenario hält die anderen nicht auf. Jedes berechnete Szenario zählt als ein Aufruf des Service. Mit zwei echten Editionen lieferte derselbe Aufruf eine Gesamtsumme von 25716.06 für Business und 47041.52 für Enterprise.

Dieselbe Adresse, mit GET geöffnet, beschreibt den Service als JSON: Eingaben, Ausgaben, ein Aufruf, der so funktioniert, wie er dasteht, und eine Liste von Anweisungen für eine KI. Siehe Die Discovery-Adresse.

Schritt 4: Die Schleife um das Modell

Dieser Teil ist Pseudocode. Er wurde nicht ausgeführt, weil er von der Modell-API abhängt, die du verwendest.

PSEUDOCODE, not run

tool     = loadTool()
messages = [system prompt, user question]

repeat:
    answer = model.respond(messages, tools = [tool])

    if answer contains no tool call:
        return answer.text

    for each tool call in answer:
        outcome = runTool(call.arguments)
        if outcome.retry and outcome.waitSeconds:
            wait outcome.waitSeconds, then runTool again, once
        append to messages: tool result = outcome as JSON

    stop after a fixed number of rounds, for example 5

Drei Punkte entscheiden, ob das gut funktioniert:

  • Immer etwas zurückgeben. Auch ein gescheiterter Aufruf geht als Tool-Ergebnis an das Modell zurück. Dann kann das Modell dem Nutzer sagen, was erlaubt ist.
  • Die Runden begrenzen. Ein Modell, das immer wieder mit demselben falschen Wert aufruft, soll an deine Grenze stoßen, nicht an die Aufrufe deines Monats.
  • Nicht wiederholen, was nicht gelingen kann. Eine abgelehnte Eingabe und das Monatslimit werden durch Wiederholen nicht besser.

Was du dem Modell sagst

Das Discovery-Dokument des Demo-Service enthält Anweisungen, die für eine KI geschrieben sind. Diese drei sind wörtlich daraus übernommen (im Original englisch) und ein guter Anfang für deinen System-Prompt:

  • "Every result is calculated by the owner's spreadsheet. Call the service for each number you report instead of working it out or estimating it yourself."
  • "A call only calculates; it changes nothing and can be repeated."
  • "If the user asks for a value an input does not allow, tell them what is allowed instead of picking another value for them."

Ergänze, was nur du weißt: wer die Nutzer sind, in welcher Währung die Zahlen sind und wann das Tool nicht verwendet werden soll.

Was in der Praxis schiefgeht

  • Prozentwerte. Der Service erwartet 0.05 für 5 %. Ein Modell, das 5 sendet, wird hier wegen des Maximums von 0.5 abgelehnt. Bei einer Eingabe ohne Maximum würde mit 500 % gerechnet. Setze Grenzen für deine Eingaben. Siehe Eingabeprüfung.
  • Rundung in der Antwort. Die API gibt die rohe Zahl der Zelle zurück. Lass deinen Code sie formatieren, oder sag dem Modell, wie.
  • Das Token. Ein Token gehört auf deinen Server, in eine Umgebungsvariable. Es gehört nicht in einen Prompt und nicht in Code, der im Browser läuft. Siehe Tokens und Zugriff.
  • Gleiche Fragen. SpreadAPI speichert das Ergebnis gleicher Eingaben bis zu 15 Minuten. Auch ein gespeichertes Ergebnis zählt als Aufruf.
  • Änderungen an der Arbeitsmappe. Aufrufer bekommen die veröffentlichte Version, bis der Besitzer erneut veröffentlicht. Lade das OpenAPI-Dokument beim Start deines Agenten, nicht einmalig beim Build.
  • Was ein Service nicht ist. VBA-Makros laufen nicht, und eine Eingabe ist ein einzelner Wert, keine Liste.

Checkliste vor dem Livegang

  • Die Tool-Definition wird aus dem OpenAPI-Dokument des veröffentlichten Service gebaut
  • Jede Eingabe hat sinnvolle Grenzen oder erlaubte Werte
  • Gescheiterte Aufrufe gehen als Tool-Ergebnis an das Modell zurück
  • 429 ist behandelt: Retry-After abwarten, das Monatslimit nicht wiederholen
  • Die Zahl der Tool-Runden pro Frage ist begrenzt
  • Das Token, falls es eines gibt, liegt auf dem Server
  • Du hast einige Antworten des Agenten mit der Arbeitsmappe verglichen

Nächste Schritte