Prompt builder

Generate ServiceAgent implementation prompts that coding agents can actually ship.

Describe what you want to build, choose the right framework and ServiceAgent surface, and get a Cursor or Claude prompt grounded in the exact packages, endpoints, env vars, and docs links we support.

Open quickstart Compare packages

Hybrid prompt builderDeterministic + refinement

Generate a copy-ready Cursor or Claude prompt

Pick the right stack and ServiceAgent surface first, then add the exact build goal and any custom constraints. The builder keeps packages, env vars, and endpoints grounded in our docs.

Primary target

Framework

What are you building?

Embed an AI chat assistant with widget config, session creation, and messaging.

Product goalFreeform refinement

Public builder

Use this public builder to shape the implementation prompt first. The authenticated portal version adds app context and saved prompt history.

Packages

@serviceagent/nextjs

The default choice for Next.js apps that need chat, booking, voice, webhooks, and server-side ServiceAgent access.

npm install @serviceagent/nextjs

@serviceagent/cli

The fastest way to scaffold ServiceAgent chat, booking, voice, and webhook files into a project.

npx @serviceagent/cli add

Endpoints

GET

/v1/api/widget/:widgetKey/config

Fetch public widget configuration for the selected widget key.

POST

/v1/api/widget/:widgetKey/session

Create a visitor chat session before the first message.

POST

/v1/api/widget/:widgetKey/session/:sessionId/messages

Send follow-up chat messages after the session is created.

Shipping checklist

The app renders a ServiceAgent chat entry point without layout regressions.

The generated code uses the documented widget config and session endpoints only.

Any custom chat UI can create a session and post follow-up messages successfully.

Generated prompts

Copy one of these prompts into your coding tool. The output already includes the exact ServiceAgent packages, env vars, docs links, and endpoint references for this workflow.

Preferred target: cursor

Optimized for repo-aware coding agents that can edit files and run commands.

Cursor prompt

Generate an implementation for Cursor using ServiceAgent.

## Objective
Add a ServiceAgent chat assistant to our product and make the integration production-ready.

## Stack and package selection
- Framework/runtime: Next.js
- Primary ServiceAgent use case: Chat widget
- Install and use @serviceagent/nextjs via `npm install @serviceagent/nextjs`
- Install and use @serviceagent/cli via `npx @serviceagent/cli add`

## Required ServiceAgent endpoints and capabilities
- GET /v1/api/widget/:widgetKey/config: Fetch public widget configuration for the selected widget key.
- POST /v1/api/widget/:widgetKey/session: Create a visitor chat session before the first message.
- POST /v1/api/widget/:widgetKey/session/:sessionId/messages: Send follow-up chat messages after the session is created.

## Environment variables and auth
- NEXT_PUBLIC_SERVICEAGENT_WIDGET_KEY
- NEXT_PUBLIC_SERVICEAGENT_API_URL
- Use the official env var names exactly as written.

## Implementation order
1. Install the framework-native ServiceAgent package instead of hand-writing widget embeds.
2. Add the documented widget environment variables before rendering the component.
3. Create the chat surface, then wire session creation and message sending if custom UI is needed.
4. Keep chat setup isolated in one component so later voice or booking surfaces can reuse the same config.

## Cursor execution instructions
- Work directly in the existing repository and prefer editing the current codebase over proposing abstract snippets.
- Make package selection explicit and do not substitute unofficial ServiceAgent packages.
- Do not invent endpoints or env vars beyond the documented items listed below.
- When custom UI is needed, keep it production-lean and wire it to the documented integration path.

## Reference docs
- Quickstart: /quickstart
- @serviceagent/nextjs: /packages/nextjs
- @serviceagent/react: /packages/react
- @serviceagent/cli: /packages/cli

## Acceptance criteria
- The app renders a ServiceAgent chat entry point without layout regressions.
- The generated code uses the documented widget config and session endpoints only.
- Any custom chat UI can create a session and post follow-up messages successfully.

Environment variables

NEXT_PUBLIC_SERVICEAGENT_WIDGET_KEY
NEXT_PUBLIC_SERVICEAGENT_API_URL

Docs links used by the builder

Why hybrid generation wins

Deterministic package choice

The builder chooses official ServiceAgent packages from our package docs before the final prompt is composed.

Documented endpoints only

The generated prompt lists only the endpoints and env vars we already document, which reduces hallucinated integration steps.

Freeform refinement last

Your custom wording still matters, but it refines the brief after the core implementation path is locked in.

Best fit workflows

Public docs flow

Use the public builder when you are evaluating a ServiceAgent integration, generating a greenfield prompt, or sharing implementation briefs with external developers.

Developer portal flow

Use the authenticated version when you want app-scoped prompts that inherit app name, environment, credentials, webhooks, and saved prompt history.

If you already have a ServiceAgent app in the developer portal, open that app and use the prompt builder there so the output includes app context and team-saveable prompts.