Agents API

Die Agents API ermöglicht es externen Anwendungen, Skripten und Diensten, mit CompanyGPT-Agenten programmatisch zu kommunizieren. CompanyGPT stellt zwei OpenAI-kompatible Schnittstellen bereit.

Übersicht

Die Agents API bietet zwei Schnittstellen:

• OpenAI-kompatible Chat Completions — POST /api/agents/v1/chat/completions
• Open Responses API — POST /api/agents/v1/responses

Beide Schnittstellen werden per API-Key authentifiziert und unterstützen Streaming-Antworten. Sie lassen sich damit nahtlos in bestehende Workflows integrieren, die bereits das OpenAI SDK oder ähnliche Bibliotheken verwenden.

Voraussetzungen

Um die Agents API nutzen zu können, müssen folgende Voraussetzungen erfüllt sein:

1. API-Zugriff — Ihre Rolle benötigt das Recht Remote-Agenten (Nutzen). Es ist standardmäßig für alle Nutzer aktiv; Administratoren können es in companyADMIN unter Zugriff → Rollen → Rolle öffnen → Reiter companyGPT entziehen. Das Recht allein reicht nicht: Per API erreichbar ist ein Agent nur für seinen Eigentümer oder wenn er ausdrücklich für den API-Zugriff mit Ihnen geteilt ist. Sonst antwortet die API mit 403 und der Meldung No remote access to agent: <Agenten-ID>.
2. API-Key generieren — Mit diesem Recht erstellen Sie in CompanyGPT unter Einstellungen → Datenschutz & Sicherheit → API-Schlüssel für Agenten → Verwalten über API-Schlüssel erstellen einen Schlüssel. Dabei vergeben Sie einen Namen und wählen unter Ablaufdatum, wie lange der Schlüssel gilt: 7 Tage, 30 Tage (voreingestellt), 90 Tage, 1 Jahr oder Nie. Kopieren Sie den Schlüssel sofort, er wird später nicht mehr angezeigt.
3. Agenten-ID ermitteln — Jeder Agent hat eine eindeutige ID (z. B. agent_ulS_lcjGw...), die Sie als model-Parameter verwenden.

Tipp

Die Agenten-ID finden Sie in der URL, wenn Sie einen Agenten in CompanyGPT öffnen, oder über den Endpunkt GET /api/agents/v1/models, der die Agenten, auf die Sie per API zugreifen dürfen, als Modelle auflistet.

Vorsicht

Agenten, die MCP-Server mit OAuth-Authentifizierung verwenden, funktionieren möglicherweise nicht über die API. OAuth-Flows erfordern eine interaktive Browser-Sitzung, die per API nicht durchgeführt werden kann.

Authentifizierung

Alle Anfragen an die Agents API müssen mit einem Bearer-Token authentifiziert werden:

Authorization: Bearer sk-ihr-api-key

API-Keys werden in der CompanyGPT-Oberfläche generiert und haben das Format sk-....

Endpunkte

Chat Completions (OpenAI-kompatibel)

POST /api/agents/v1/chat/completions

Kompatibel mit dem OpenAI Chat Completions Format. Der model-Parameter entspricht der Agenten-ID.

JavaScript (OpenAI SDK)

import { OpenAI } from "openai";

const client = new OpenAI({
    baseURL: "https://<COMPANYGPT URL>/api/agents/v1",
    apiKey: "sk-ihr-api-key",
});

const stream = await client.chat.completions.create({
    model: "agent_ulS_lcjGw...", // Agenten-ID
    messages: [
        {
            role: "user",
            content: "Was kannst du für mich tun?",
        },
    ],
    stream: true,
});

let contentBuffer = "";
const toolCalls = new Map();

for await (const event of stream) {
    const delta = event.choices?.[0]?.delta;
    if (!delta) continue;

    // Textinhalt streamen
    if (delta.content) {
        contentBuffer += delta.content;
        process.stdout.write(delta.content);
    }

    // Tool-Aufrufe verarbeiten
    if (delta.tool_calls) {
        for (const toolCall of delta.tool_calls) {
            const toolId = toolCall.index || 0;
            if (!toolCalls.has(toolId)) {
                toolCalls.set(toolId, {
                    id: toolCall.id,
                    name: toolCall.function?.name || "",
                    arguments: "",
                });
            }
            if (toolCall.function?.arguments) {
                toolCalls.get(toolId).arguments += toolCall.function.arguments;
            }
        }
    }
}

console.log(`\nFertig. Tool-Aufrufe: ${toolCalls.size}`);

curl

curl -X POST https://<COMPANYGPT URL>/api/agents/v1/chat/completions \
  -H "Authorization: Bearer sk-ihr-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent_ulS_lcjGwTAG2Ly3zTcgz",
    "messages": [
      {"role": "user", "content": "Was kannst du für mich tun?"}
    ],
    "stream": true
  }'

Open Responses API

POST /api/agents/v1/responses

Die Open Responses API folgt dem Open Responses Standard – einem offenen Inferenz-Standard, der für agentische Workflows entwickelt wurde und nativ Tool-Nutzung, strukturierte Ausgaben und Streaming unterstützt. Dies ist die primäre Schnittstelle für die Zukunft.

JavaScript (OpenAI SDK)

import { OpenAI } from "openai";

const client = new OpenAI({
    baseURL: "https://<COMPANYGPT URL>/api/agents/v1",
    apiKey: "sk-ihr-api-key",
});

const stream = await client.responses.create({
    model: "agent_ulS_lcjGwTAG2Ly3zTcgz", // Agenten-ID
    input: [
        {
            role: "user",
            content: "Was kannst du für mich tun?",
        },
    ],
    stream: true,
});

for await (const event of stream) {
    console.log(event);
}

curl

curl -X POST https://<COMPANYGPT URL>/api/agents/v1/responses \
  -H "Authorization: Bearer sk-ihr-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent_ulS_lcjGwTAG2Ly3zTcgz",
    "input": "Was kannst du für mich tun?"
  }'

Eigene Funktionen (Client-Function-Tools)

In der Open Responses API können Sie dem Agenten zusätzlich eigene Funktionen mitgeben, die Ihre Anwendung selbst ausführt. Dazu übergeben Sie im Feld tools Einträge vom Typ function mit Name, Beschreibung und Parametern im JSON-Schema-Format. Der Funktionsname darf nur Buchstaben, Ziffern, _ und - enthalten.

Ruft das Modell eine solche Funktion auf, wird sie nicht in CompanyGPT ausgeführt. Stattdessen endet der Durchlauf, und die Antwort enthält den Aufruf als Element vom Typ function_call. Das gilt nur, wenn Ihre Funktion der einzige Tool-Aufruf ihres Durchlaufs ist: Ruft das Modell sie zusammen mit einem Werkzeug auf, das CompanyGPT selbst ausführt (Server-Tool), wird der Aufruf nicht an Ihre Anwendung übergeben. Ihre Anwendung führt die Funktion aus und setzt die Unterhaltung mit einer neuen Anfrage fort. Darin senden Sie im Feld input den bisherigen Verlauf, das erhaltene function_call-Element und Ihr Ergebnis als function_call_output mit derselben call_id:

{
  "model": "agent_ulS_lcjGwTAG2Ly3zTcgz",
  "tools": [
    {
      "type": "function",
      "name": "open_service_page",
      "description": "Öffnet die Serviceseite zu einer Auftragsnummer",
      "parameters": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      }
    }
  ],
  "input": [
    { "role": "user", "content": "Öffne die Serviceseite zu Auftrag 4711." },
    {
      "type": "function_call",
      "call_id": "call_1",
      "name": "open_service_page",
      "arguments": "{\"order_id\": \"4711\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "call_1",
      "output": "Serviceseite geöffnet."
    }
  ]
}

Hinweis

Eine Fortsetzung über previous_response_id funktioniert für eigene Funktionen nicht. Senden Sie das function_call- und das function_call_output-Element immer gemeinsam im Feld input der nächsten Anfrage.

Verfügbare Agenten abrufen

GET /api/agents/v1/models

Gibt als Modell-Liste nur die Agenten zurück, auf die Sie per API zugreifen dürfen.

JavaScript (OpenAI SDK)

import { OpenAI } from "openai";

const client = new OpenAI({
    baseURL: "https://<COMPANYGPT URL>/api/agents/v1",
    apiKey: "sk-ihr-api-key",
});

const models = await client.models.list();
console.log(models);

curl

curl https://<COMPANYGPT URL>/api/agents/v1/models \
  -H "Authorization: Bearer sk-ihr-api-key"

Token-Verbrauch

Alle Anfragen an die Agents API werden gegen das Token-Guthaben des Benutzers verrechnet (sofern Token-Spending konfiguriert ist). Sowohl Eingabe- als auch Ausgabe-Tokens werden gezählt, inklusive Cache-Tokens bei unterstützten Anbietern (OpenAI, Anthropic).

Budgets im AI Gateway

In Umgebungen, in denen CompanyGPT die KI-Modelle über das AI Gateway anspricht, gelten für Anfragen über die Agents API zusätzlich die Budgets des Gateways. Ist ein Budget aufgebraucht, lehnt das Gateway die Modellanfrage ab; Anfragen an den Agenten schlagen dann fehl, bis wieder Budget verfügbar ist. Wie der Fehler bei Ihrer Anwendung ankommt, hängt vom Modus ab:

• Ohne Streaming erhalten Sie den Status 402 mit der Meldung des Gateways.
• Mit Streaming über Chat Completions lautet der Status 200; der Fehler steht als „Error: …“ im letzten Chunk.
• Mit Streaming über die Open Responses API endet der Stream nur mit [DONE], ohne Fehlermeldung.

Hat Ihr Unternehmen für aufgebrauchte Budgets ein Ersatzmodell eingerichtet, kommt kein 402; das Gateway beantwortet die Anfrage dann mit diesem Modell.

Verwandte Dokumentation

• Agenten — Agenten in CompanyGPT erstellen und konfigurieren
• MCP Server — MCP-Server-Integrationen
• AI Gateway API — Direkter Zugriff auf die KI-Modelle über das AI Gateway