Skip to Content
TutorialsIntegration PlaybooksChocolate FactoryOverview

Chocolate Factory Integration

Add AI agents to your app

What is Chocolate Factory?

Chocolate Factory is an AI agent platform. You build and configure an agent — its system prompt, model, tools, and guardrails — in the Chocolate Factory Portal, then call it from your app to power chat, generate content, or return structured data.

Perfect for:

  • Customer-facing chat / support widgets
  • AI-generated dashboard summaries and reports
  • Structured data extraction (e.g. feeding a chart)
  • Form autofill, email drafts, generated documents
  • Anything where you want an LLM behind a feature without building the LLM plumbing yourself

This connector only works from your app’s Next.js code — API routes and Client Components. It cannot be used from a DaaS custom service (sandboxed JS, no npm packages).

What You’ll Need

Chocolate Factory, connected

Auto-provisioned automatically, or bring your own key — see Step 1.

An agent

Created by you in the Chocolate Factory Portal. Buildpad can connect your project to Chocolate Factory, but it can’t create or pick an agent for you.

The agent’s ID

Copied from the Portal. You’ll hand this to your coding assistant every time a feature needs it.

A good initial prompt

A concise prompt goes a long way in minimizing iterations to implement the feature.

Step 1: Connect Chocolate Factory

Connect the project

  1. Open your project → Connectors in the sidebar (or check the Chocolate Factory card during project creation).
  2. Click Connect.
  3. Choose a mode:
    • Auto-provision (default) — Buildpad creates a Chocolate Factory project for you at {your org name}/{your project name}/BuildPad and stores the resulting key. The card shows Auto-configuring while this is in flight, then Connected.
    • Bring your own key — paste an existing Chocolate Factory project-scoped API key (starts with cf_). Use this if you already manage a Chocolate Factory project outside Buildpad.
  4. Click Connect.

This stores two things for your project: CHOCOLATE_FACTORY_API_KEY and CHOCOLATE_FACTORY_BASE_URL. The base URL isn’t a field you fill in when connecting — Buildpad sets it to the main Chocolate Factory platform automatically, and the connect form can’t be tricked into overriding it. It’s still just an env var in your own app once pushed, though — if you ever need to point at a different Chocolate Factory instance, you (or your coding assistant) can change CHOCOLATE_FACTORY_BASE_URL like any other env var.

Create your agent

  1. Open the Chocolate Factory Portal (the Platform link on the connector card).
  2. Create — or find — the agent for the feature you’re building. See Agent Configuration for what to set: model, system prompt, and tools.
  3. Copy its Agent ID.

Agent IDs aren’t stored by Buildpad. There’s no list-agents step your coding assistant can do for you — you paste the ID into your prompt every time a feature needs one.

Step 2: Tell the Agent What You Want

Once Chocolate Factory is connected, your coding assistant already knows how to reach it — you don’t need to paste API keys or base URLs into a prompt, just the Agent ID and what you want built.

Example 1: Customer support chat widget

Add a Chocolate Factory chat widget to this app.

Agent ID: a1b2c3d4-5e6f-47a8-xxxx-xxxxxxxxxxxx
(this is my customer support agent)

I want the widget to:
- Appear on every page, bottom-right
- Match my app's brand color
- Start with the message "Hi! How can I help you today?"

Please set this up.

Example 2: AI dashboard summary

Add an AI-generated sales summary card to my dashboard.

Agent ID: c3d4e5f6-7a8b-49c0-xxxx-xxxxxxxxxxxx
(configured to return JSON: { labels: string[], values: number[] })

The card should:
- Fetch the last 30 days of orders from my "orders" collection
- Pass that data to the agent
- Render the result as a bar chart

Please build this.

Example 3: Custom chat page

Build a custom chat page at /support instead of using the pre-built widget.

Agent ID: e5f6a7b8-9c0d-4e1f-xxxx-xxxxxxxxxxxx

I want:
- My own message bubbles, not the default widget styling
- A "thinking…" indicator while the agent is responding
- To show which tools the agent used, if any

Please implement this using the Chocolate Factory SDK's ChatClient directly.

Under the hood: your assistant reads a bundled reference doc that keeps your real API key server-side — chat requests from the browser are proxied through your own app instead of calling Chocolate Factory directly. You don’t need to ask for this; it’s the default.

Step 3: Test the Connection

Start the app

Run pnpm dev and open the page where the feature was added.

Confirm it appears

The widget (or your custom UI) should render — no console errors about a missing agent ID or API key.

Send a test message

Type something and submit. You should get a response.

Check the network tab

The request should hit your own app’s route (e.g. /api/agents/<agentId>/run), not Chocolate Factory’s URL directly. That confirms your API key never left the server.

Confirm the reply streams or resolves

Chat responses should stream in; one-off calls (e.g. a dashboard summary) should resolve with the expected shape.

Repeat after deploying

Env vars connected here don’t automatically reach your deployed app — ask your assistant to push them (see Troubleshooting) and re-test on the live URL.

Common Questions

Do I need a separate agent for every feature?

Not necessarily — one agent can back multiple features if its system prompt is general enough. Many projects do split by feature (a support agent, a summary agent, etc.) since each has a different system prompt and output shape. If you use more than one, ask your assistant to name each env var with a label, e.g. CHOCOLATE_FACTORY_AGENT_ID_DASHBOARD_SUMMARY.

Can end users see my Chocolate Factory API key?

No, by default. Buildpad’s onboarding issues a project-scoped key with access to every agent in the project, so the default pattern proxies browser requests through your own server — the real key never reaches the browser.

Widget or custom chat UI — which should I use?

Start with the pre-built widget (Example 1 above) — it’s a few lines and covers most chat use cases, including showing which tools an agent used. Reach for a custom UI only if the widget’s fixed panel and theming genuinely don’t fit your design.

Can the agent do more than chat?

Yes. Any agent can be called as a plain function — text or data in, text out — which works for dashboard cards, generated documents, form autofill, or structured JSON for a chart. The agent’s system prompt (configured in the Portal) decides the output shape.

Something Not Working?

Can’t Connect

Tell the agent:

Getting a 401 calling Chocolate Factory. 

Can you check:
1. CHOCOLATE_FACTORY_API_KEY and CHOCOLATE_FACTORY_BASE_URL are set 
   in .env.local
2. The connector shows "Connected" on the project's Connectors page
3. Whether I need to restart `pnpm dev` after adding the env vars

Widget Doesn’t Appear

Tell the agent:

Added the Chocolate Factory widget but nothing shows up on the page.

Agent ID: [paste it]

Can you check the browser console for errors and confirm the widget
component is actually rendered in the layout?

Works Locally, Not After Deploying

Tell the agent:

The Chocolate Factory feature works with `pnpm dev` but not on the 
deployed app.

Can you check whether CHOCOLATE_FACTORY_API_KEY, CHOCOLATE_FACTORY_BASE_URL, 
and CHOCOLATE_FACTORY_AGENT_ID are set in the Amplify environment, 
and redeploy if you add or change any of them?

Agent Replies, But I Don’t See Tool Calls

Tell the agent:

My Chocolate Factory agent has tools attached, but I can't see which 
tools ran or with what input/output.

Can you check whether this is using the chat widget/ChatClient (which 
supports tool visibility) or a backend-only call (which doesn't)?

Real Examples

Example: Sales lead follow-up drafts

Add a "Draft Follow-up" button on each row of my leads table.

Agent ID: a1b2c3d4-5e6f-47a8-xxxx-xxxxxxxxxxxx
(configured to write a short, friendly follow-up email)

When clicked:
- Send the lead's name, company, and last contact date to the agent
- Show the drafted email in a modal
- Let me copy it or edit before sending

Please build this.

Example: Support ticket summarizer

When a support ticket has more than 5 messages, show an AI summary 
at the top.

Agent ID: c3d4e5f6-7a8b-49c0-xxxx-xxxxxxxxxxxx

- Pass the full message thread to the agent
- Show the summary in a collapsible card above the thread
- Add a "Regenerate" button

Please set this up.

Advanced Features

Once the basics work:

Multiple Agents

I want to add a second Chocolate Factory agent for a different feature.

Agent ID: a7b8c9d0-1e2f-4a3b-xxxx-xxxxxxxxxxxx
Purpose: summarizing weekly analytics

Please add this as its own labeled environment variable, separate 
from my existing agent, and use it for a new /analytics/summary route.

Structured Output

I want this agent to return JSON instead of chat text, so I can 
render it as a chart.

Agent ID: c9d0e1f2-3a4b-4c5d-xxxx-xxxxxxxxxxxx
Expected shape: { labels: string[], values: number[] }

Please parse the response and handle the case where the agent 
returns something that isn't valid JSON.

Tool Call Visibility

Show a "using tool: X…" badge live while my chat widget's agent 
is calling one of its tools, not just the final answer.

Quick Checklist

Before going live:

  • Connector shows Connected on the Connectors page
  • Agent ID is set as an env var, not hardcoded in a prompt or component
  • Feature works with pnpm dev locally
  • Env vars pushed to the Amplify deployment and redeployed
  • Tested on the live URL, not just locally
  • Network tab confirms requests hit your app’s own routes, not Chocolate Factory directly
  • Checked what happens when the agent errors or times out
Agent ConfigurationObservability

Remember

Credentials stay server-side — Buildpad’s connector model keeps your API key out of the browser by default; you don’t need to ask for this.

Agent IDs are yours to manage — Buildpad never stores or picks them for you.

One playbook, many UIs — chat widget, dashboards, summaries, and forms all use the same connected agent.

Deploying is a separate step — connecting Chocolate Factory doesn’t push env vars to your live app automatically.

Great for embedding AI without building your own LLM plumbing — the agent’s behavior lives in the Chocolate Factory Portal, not your codebase.

Stuck? Tell your coding assistant: “I need help with the Chocolate Factory integration” and describe the issue.

Last updated on
OverviewAgent Configuration