Prompts

Define agent behavior with system prompts, user templates, and output schemas.

What Are Prompts?

A prompt is the set of instructions that defines how an agent behaves. It tells the agent who it is, what it should do, how it should respond, and what format its output should take. Every agent references exactly one prompt, and that prompt is the single most important factor in determining the quality of the agent's responses.

Prompts are managed as standalone objects in the system. This means you can create a prompt once and reuse it across multiple agents, version it over time, and edit it through the admin UI without any code changes. When you update a prompt, every agent that references it immediately picks up the new behavior.

Prompt Components

Each prompt is made up of several components that work together to shape the agent's behavior:

System Prompt

The system prompt establishes the agent's persona and behavioral rules. This is where you define who the agent is and how it should conduct itself. The system prompt is sent to the LLM at the beginning of every conversation and sets the context for everything that follows.

A system prompt might say something like: "You are a helpful data analyst who specializes in marketing metrics. You always present data clearly, explain your methodology, and flag any caveats or limitations in your analysis. You never make up data — if you do not have enough information to answer a question, say so."

User Prompt

The user prompt is a template that formats the user's input before it reaches the model. This is useful when you want to add structure, context, or instructions around what the user types. For example, a content summarization agent might have a user prompt template that wraps the user's text with instructions like "Summarize the following content in 2-3 sentences, focusing on the main argument and key takeaways."

The user prompt template ensures consistency — no matter how the user phrases their request, the model receives a well-structured input that leads to predictable, high-quality responses.

Input and Output Types

Prompts can define what kind of data the agent expects as input and what kind of data it returns. This helps the system route the right kind of work to the right agents and ensures that agents produce output in the expected format.

Output Schema

For agents that need to return structured data rather than free-form text, you can define an output schema using JSON Schema. When an output schema is set, the model is constrained to return a valid JSON response that conforms to the schema. The platform validates the response automatically.

This is particularly useful for agents that feed their output into other systems. For example, a topic extraction agent might have an output schema that requires it to return a list of topics, each with a name and a confidence score. Because the output is guaranteed to match the schema, downstream systems can consume it reliably without error-prone text parsing.

Prompt Management

Prompts are created and managed entirely through the admin UI. The workflow is straightforward:

1. Create a new prompt. Give it a name, a key, and a description. The key is a stable identifier that remains consistent across environments — use it to reference the prompt in configuration and automation.
2. Write the system prompt. Define the agent's persona, rules, and behavioral guidelines. This is the core of what makes the agent useful.
3. Add a user prompt template. If needed, define how user input should be formatted before it reaches the model.
4. Set input and output types. Specify what kind of data the agent works with, and optionally define an output schema for structured responses.
5. Assign the prompt to an agent. Link the prompt to one or more agents. The agents will immediately start using the new instructions.

When you need to change how an agent behaves, you edit the prompt. There is no code to modify, no build to trigger, and no deployment to wait for. Save the change in the UI and the agent's behavior updates immediately.

Keys for Stable References

Every prompt has a key — a short, human-readable identifier that remains stable across environments. While database IDs may differ between your development, staging, and production environments, keys stay the same. This makes it easy to reference prompts in configuration files, automation scripts, and cross-environment workflows.

Choose keys that are descriptive and consistent. For example, data-analyst-system or content-summarizer clearly communicate what the prompt does and are easy to reference in other parts of the system.

How Prompts Connect to Agents

Each agent references exactly one prompt. The relationship is straightforward: when you configure an agent, you select which prompt it should use. Multiple agents can share the same prompt if they need the same behavioral instructions — for example, you might have a single "friendly assistant" prompt used by agents that differ only in their model or tool assignments.

This separation of prompt and agent is intentional. It means you can:

• Reuse prompts across multiple agents without duplication.
• A/B test behavior by creating two agents with the same tools and model but different prompts.
• Iterate on instructions without touching the agent's model or tool configuration.
• Manage prompts centrally when multiple agents share the same behavioral rules.

Best Practices for Writing Prompts

• Be specific about what the agent should do. Vague instructions lead to inconsistent responses. Instead of "be helpful," say "answer questions about marketing metrics using data from the analytics dashboard, and always include the date range in your response."
• Define boundaries. Tell the agent what it should not do. If it should not make up data, say so explicitly. If it should not answer questions outside its domain, include that rule.
• Give examples when possible. If you want the agent to respond in a particular format or style, include an example in the system prompt. Models learn quickly from examples.
• Keep it focused. A prompt that tries to cover too many scenarios becomes confusing for the model. If you need an agent that handles many different situations, consider using sub-agents with focused prompts instead.
• Iterate based on real conversations. Write an initial prompt, test it with real questions, and refine based on what works and what does not. Prompt engineering is an iterative process.
• Use output schemas for structured data. When you need the agent to return data in a specific format, define a JSON Schema rather than relying on instructions alone. Schemas enforce structure reliably; instructions are suggestions the model may occasionally deviate from.