Skip to content
innFactory AI DokumentationCompanyGPT Documentation

Agents API

The Agents API allows external applications, scripts, and services to communicate with CompanyGPT agents programmatically. CompanyGPT is based on LibreChat and exposes two API-compatible interfaces.

Overview

Section titled “Overview”

The Agents API provides two interfaces:

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

Both interfaces are authenticated via API keys and support streaming responses, making it easy to integrate CompanyGPT agents into existing workflows that already use the OpenAI SDK or similar tooling.

Prerequisites

Section titled “Prerequisites”

To use the Agents API, the following prerequisites must be met:

  1. API access — Your role needs the Remote agents permission (Use). It is enabled for all users by default; administrators can revoke it in companyADMIN under Access → Roles → open a role → companyGPT tab. The permission alone is not enough: an agent can only be reached via the API by its owner or if it has been explicitly shared with you for API access. Otherwise, the API responds with 403 and the message No remote access to agent: <agent-id>.
  2. Generate an API key — With this permission, create a key in CompanyGPT under Settings → Data & Privacy → Agent API keys → Manage via Create API Key. You enter a name and choose under Expiration how long the key is valid: 7 days, 30 days (preselected), 90 days, 1 year, or Never. Copy the key right away; it will not be shown again.
  3. Find your agent ID — Each agent has a unique ID (e.g. agent_ulS_lcjGw...) that you use as the model parameter.

Authentication

Section titled “Authentication”

All requests to the Agents API must be authenticated with a Bearer token:

Authorization: Bearer sk-your-api-key

API keys are generated in the CompanyGPT interface and follow the format sk-....

Endpoints

Section titled “Endpoints”

Chat Completions (OpenAI-compatible)

Section titled “Chat Completions (OpenAI-compatible)”
POST /api/agents/v1/chat/completions

Compatible with the OpenAI Chat Completions format. The model parameter corresponds to the agent ID.

import { OpenAI } from "openai";


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


const stream = await client.chat.completions.create({
    model: "agent_ulS_lcjGw...", // Agent ID
    messages: [
        {
            role: "user",
            content: "What can you help me with?",
        },
    ],
    stream: true,
});


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


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


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


    // Handle tool calls
    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(`\nDone. Tool calls: ${toolCalls.size}`);

Open Responses API

Section titled “Open Responses API”
POST /api/agents/v1/responses

The Open Responses API follows the Open Responses standard — an open inference standard designed for agentic workflows with native support for tool use, structured outputs, and streaming. This is the primary interface going forward.

import { OpenAI } from "openai";


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


const stream = await client.responses.create({
    model: "agent_ulS_lcjGwTAG2Ly3zTcgz", // Agent ID
    input: [
        {
            role: "user",
            content: "What can you help me with?",
        },
    ],
    stream: true,
});


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

Your own functions (client function tools)

Section titled “Your own functions (client function tools)”

In the Open Responses API, you can also give the agent your own functions that your application executes itself. To do this, pass entries of type function with name, description, and parameters in JSON Schema format in the tools field. The function name may only contain letters, digits, _, and -.

If the model calls such a function, it is not executed in CompanyGPT. Instead, the run ends and the response contains the call as an item of type function_call. This only applies if your function is the only tool call of its run: if the model calls it together with a tool that CompanyGPT executes itself (server tool), the call is not handed over to your application. Your application executes the function and continues the conversation with a new request. In it, you send the previous history, the received function_call item, and your result as function_call_output with the same call_id in the input field:

{
  "model": "agent_ulS_lcjGwTAG2Ly3zTcgz",
  "tools": [
    {
      "type": "function",
      "name": "open_service_page",
      "description": "Opens the service page for an order number",
      "parameters": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"]
      }
    }
  ],
  "input": [
    { "role": "user", "content": "Open the service page for order 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": "Service page opened."
    }
  ]
}

List Available Agents

Section titled “List Available Agents”
GET /api/agents/v1/models

Returns, as a list of models, only the agents you may access via the API.

import { OpenAI } from "openai";


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


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

Token Usage

Section titled “Token Usage”

All Agents API requests are counted against the user’s token balance (when token spending is configured). Both input and output tokens are tracked, including cache tokens for providers that support them (OpenAI, Anthropic).

Budgets in the AI Gateway

Section titled “Budgets in the AI Gateway”

In environments where CompanyGPT accesses the AI models via the AI Gateway, the gateway’s budgets also apply to requests via the Agents API. If a budget is used up, the gateway rejects the model request; requests to the agent then fail until budget is available again. How the error reaches your application depends on the mode:

  • Without streaming, you receive status 402 with the gateway’s message.
  • With streaming via Chat Completions, the status is 200; the error appears as “Error: …” in the last chunk.
  • With streaming via the Open Responses API, the stream only ends with [DONE], without an error message.

If your organization has set up a fallback model for used-up budgets, there is no 402; the gateway then answers the request with this model.

Section titled “Related Documentation”
  • Agents — Creating and configuring agents in CompanyGPT
  • MCP Servers — MCP server integrations
  • AI Gateway API — Direct access to the AI models via the AI Gateway