Write the private instructions that shape how your agent behaves in every conversation.
The system prompt is the standing instruction set the agent follows on every turn. It is where you establish who the agent is, what it should do, and — most usefully — what it should refuse or escalate instead of improvising.
It lives in project Settings, applies to the next message with no deploy, and is never shown to the people using your product.
| Field | Notes |
|---|---|
| Project name | Up to 100 characters. Internal only — used to identify the project in the dashboard |
| Agent ID | Read-only. The value you pass as agentId to the embed |
| System prompt | Up to 12,000 characters of private runtime guidance |
Your instructions are appended to the runtime's own operating rules rather than replacing them. The runtime contributes the parts that have to be correct for the product to work — how to render generated UI, how to treat tool results as untrusted data, when tools exist at all — and your prompt supplies the domain knowledge and judgment on top.
Some of that context is assembled for you and does not belong in your prompt:
Listing tools or documents yourself only risks contradicting what is actually available. Write about when to use them instead.
A prompt that works in testing and drifts in production is usually missing structure rather than length. These sections cover most of what matters:
Role and scope. One or two sentences on what this agent is for, and explicitly what it is not for. Scope is what keeps an agent from confidently answering questions it has no business answering.
Voice. How to sound, and how long to be. Products differ far more here than teams expect — "answer in at most three sentences unless asked to elaborate" changes the felt quality of an agent more than most model choices.
Tool guidance. When to search knowledge versus ask a clarifying question. When to call a client tool versus explain what the person should do themselves. Which actions to confirm before taking.
Boundaries. What to refuse, and what to escalate. Give the agent the exact escape hatch you want — "direct billing disputes to support@example.com" beats a vague instruction not to discuss billing.
Domain facts that never change. Product names, tier names, the terminology your customers use. Anything that changes belongs in the knowledge base, not here.
Keep the prompt for judgment and put facts in documents. Documents are searched on demand and edited independently, while every sentence in the prompt is paid for on every single turn.
You are the assistant for Acme, a project management product for design teams.
Help with plans, billing, and how features work. For anything outside Acme,
say briefly that you can only help with Acme.
Answer in at most three sentences unless the person asks for detail. Prefer
concrete steps over description. Never invent a feature or a price.
Search knowledge before answering anything about pricing, limits, or refunds,
and quote what you find. If the documents do not cover it, say so plainly.
Confirm before changing anything in the person's workspace. Direct billing
disputes and account deletion requests to support@acme.com.When both are available, tell the agent which source fits the job instead of listing every tool and document by name:
Use the knowledge base for policies, pricing, plan limits, and troubleshooting.
Search before answering, cite the document you used, and never fill a gap with
an assumption. If the documents disagree or do not answer the question, say so.
Use connected MCP tools for live records and actions, such as checking an issue,
reading its current status, or creating a follow-up. Search for an existing record
before creating one. Before any tool call that writes or changes data, summarize
the action and ask for confirmation.
Use knowledge for reference answers and MCP tools for current state. If the right
source is unavailable, explain what is missing and do not guess.Treat the prompt as something you tune against evidence rather than get right the first time:
Changes apply to the next message in production immediately. Keep a separate project for staging if you want to validate a prompt change before customers see it.
Archiving disables the project's embeds and stops further editing. It is available to the workspace owner from the danger zone in Settings, and the owner can restore an archived project later.
Archive when a project was created by mistake or an integration is retired. For a temporary pause, disabling individual tools or documents is less disruptive.