Writing Effective Instructions
Instructions are how you tell an agent what to do. They're the primary control in the agent panel — plain-language guidance that shapes the agent's behavior on every run. This guide explains how Instructions relate to the system prompt, how to reference inputs, and how to write Instructions that get reliable results.
Instructions, not "prompts." In Ema the builder-facing field is Instructions. There's also an advanced system prompt that most builders never touch — the difference is below.
Instructions vs. the system prompt
Every agent has two layers of guidance:
- Instructions — the field you'll use day to day. It's the first thing in the agent panel. You write what you want the agent to accomplish, and the platform supplies it to the agent as the
instructionsinput on every run. - System prompt — a lower-level template that frames the agent's role. Each agent type ships with a sensible default system prompt, so you rarely change it. It lives under Advanced settings.
The two are connected. The default system prompt usually references your Instructions with a {{input.instructions}} placeholder, so what you type into Instructions flows into the agent's context exactly where it's needed. For example, the search-and-respond agent ships with:
You are a research assistant. Search for relevant information and synthesize a comprehensive answer.
User instructions: {{input.instructions}}You write the Instructions; the system prompt template decides where they land.
Start with Instructions only. Reach for the system prompt under Advanced settings only when you need to change the agent's role or framing rather than the task — for example, to set a fixed role, tone, or output discipline that should apply regardless of the per-run task.
Referencing inputs with {{input.x}}
The system prompt is a template. Anywhere you write {{input.<field>}}, the platform substitutes the value of that input field when the agent runs. The most common reference is {{input.instructions}}, but you can reference any field the agent receives through its input mapping.
For example, if you map a Start-node field customer_name into the agent (so the agent receives an input named customer_name), you can reference it in the system prompt:
You are a support assistant helping {{input.customer_name}}.
Follow these instructions: {{input.instructions}}Two {{...}} namespaces appear in the builder, and they're easy to mix up:
{{input.x}}— used inside an agent's system prompt. It refers to the inputs the agent itself receives.{{workflow_input.x}}and{{node_id.output.x}}— used in an agent's input mapping to pull values from the Start node or upstream agents.
The mapping is how data reaches the agent; {{input.x}} is how the agent's system prompt reads it once it arrives.
How agent types use Instructions
All of Ema's LLM-driven agent types take Instructions, but they put them to different uses:
| Agent type | What Instructions should describe |
|---|---|
| Intent classification | What each category means and how to tell them apart. Pair with the configured intent labels. |
| Search and respond | What question to answer and how to use the searched knowledge to answer it. |
| Extraction | What to pull out of the input. Pair with the output schema that defines the fields. |
| Rule validation | What the input represents and how to weigh it. Pair with the configured rules. |
| Document agent | What document to produce and how to structure it. |
| Respond | The full task — this type relies most directly on your Instructions and system prompt. |
| Custom | The task plus when and how to use the agent's Tools. |
Some agent types don't take free-form Instructions. The feedback router, code agent, and App Navigator are configured entirely through their own controls (rules, a code editor, or browser steps) rather than an Instructions textarea.
Writing Instructions that work
Instructions are read by an LLM, so clarity and specificity matter more than length. The patterns below are reliable across agent types.
Be specific about the task and the output
State exactly what you want and what "done" looks like. Vague Instructions produce vague results.
- Weak: "Help with the support ticket."
- Strong: "Read the customer message. Classify its urgency as
high,medium, orlow. High means a production outage or a security issue; medium means a blocked workflow; low means a question or feature request."
Describe the inputs the agent will see
Tell the agent what it's looking at, especially when you've mapped several inputs. If the agent receives {{input.instructions}} plus a mapped transcript, say so: "You will receive a support message in instructions and the prior chat transcript in transcript."
Constrain the output shape when it matters
For extraction and classification, define the structure in the type-specific config (output schema or intents) and use Instructions to explain how to fill it. For free-form responses, state the format you want: "Reply in two short paragraphs. Do not include a greeting or sign-off."
Tell the agent when to use its Tools
For a custom agent with Tools attached, Instructions should cover when each tool applies and what to do with the result. "Use the lookup-order tool when the customer references an order number. If no order is found, ask the customer to confirm the number rather than guessing."
Set boundaries
State what the agent must not do. "Never share internal pricing. If asked, say you'll route the request to an account manager." Boundaries in Instructions are more reliable than hoping the model infers them.
Knowledge and citations
When an agent has a knowledge base attached, the searched passages are added to its context automatically — you don't reference them in Instructions. For text-output agents, the platform also asks the model to cite which sources it used, and surfaces those citations on the response. Your Instructions should tell the agent how to use the knowledge ("Answer only from the attached policy documents; if the answer isn't there, say so"), not where the knowledge comes from.
Resetting to the default
The system prompt field is in "override" mode for library agents: it shows your override, and clearing the textarea resets it to the agent type's shipped default. This makes it safe to experiment — if an edit makes things worse, clear the field to return to the known-good default.
What's next
- Build your first workflow — where Instructions fit in the overall build.
- Setting up a knowledge base — give an agent searched context to reason over.
- Agent reference — per-type configuration details.