Agent Integration

Integrate agents into your applications, websites, widgets, and backend services using Chocolate Factory’s public HTTP APIs.

Integration Endpoint

All agent invocations go through the unified /run endpoint (POST /api/agents/{agentId}/run). The stream field in the request body selects the response mode:

Use "stream": true when you are building a real chat experience. It is the right choice for chat widgets, copilots, multi-turn conversations, and anything that should stream the response as it is generated.

Use "stream": false (the default) when you want a single result back, like a normal API call. It is better for forms, content generation, prompt-template execution, backend jobs, and one-off actions where you send some variables, optionally one plain message, then wait for one JSON response with text, usage, and finishReason.

Both modes invoke the same agent configuration, including its model, system prompt, tools, and knowledge sources.

Mode	Best for
`"stream": true`	Conversation UI, streaming, back-and-forth
`"stream": false` (default)	One request in, one JSON answer out

Run Endpoint → request format, conversation modes, AI SDK integration, streaming and JSON examples.

The previous /chat and /execute endpoints are deprecated. They remain available as backward-compatible wrappers around /run — see the Run Endpoint migration guide.

Get Your Integration Details

Before calling the APIs, open the agent’s configuration page and scroll to the Integrations section. This is where you find the values needed to connect your application.

Integrations Tab

From this section you can copy:

Agent ID → the unique identifier used in the API path (/api/agents/{agentId}/...).
Run API URL → the full endpoint for both streaming and single-shot JSON requests.

Authentication

For machine-to-machine access without a signed-in user, authenticate with an agent API key or an organization API key.

Key type	Header	Scope	Best for
Agent API key	`x-agent-key`	Single agent	Chat widgets, copilots, and integrations tied to one agent
Organization API key	`cf-api-key`	All agents in the organization	Backend services, automation platforms, and multi-agent workflows
Bearer token	`Authorization`	Signed-in user session	Applications where the user is already authenticated in Chocolate Factory

Create an Agent API Key

Use an agent API key when your integration calls a specific agent and you want credentials scoped to that agent only.

Open the agent’s configuration page.
Scroll to Integrations → Agent API Keys.
Enter a descriptive Key Name (for example, Frontend SDK Key or Production Widget).
Click Add Key.
Copy the generated key immediately (save the key since it is only shown once).

Pass the key in the x-agent-key request header on every API call.


x-agent-key: agk_xxxxxxxxxxxxxxxxxxxxxxxxx

Use an Organization API Key

Alternatively, use an organization API key from Organization Settings. Organization keys can authenticate requests to any agent that belongs to the same organization.

See API Key Provisioning for full details on creating, using, and revoking organization API keys.


cf-api-key: cf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

See API Key Provisioning for full details on creating, using, and revoking organization API keys.

API keys are sensitive credentials. Store them securely and never expose them in source code repositories, client-side applications, or public documentation. Use environment variables or a secrets manager.