Prompt Authoring

Authoring prompts in Agentsmith is designed to be both powerful and straightforward. We use the Jinja2 templating syntax, which allows you to create dynamic, reusable prompts with variables, logic, and even composition.

Templating with Jinja

All prompts in Agentsmith are powered by Nunjucks, a rich and powerful templating language for JavaScript that is a port of Jinja2. This allows you to go beyond simple variable substitution and implement logic directly within your prompts.

Basic Variables

You can define variables in your prompt using the {{ variable_name }} syntax. In the Studio, you can define these variables, set their types (e.g., string, number, boolean), and provide default values.

Example:

The customer's name is {{ customer_name }} and their account number is {{ account_id }}.

Global Variables

For values that need to be accessible across all prompts in a project, you can define Global Variables under the "Globals" tab in the Studio. These are perfect for constants like your company name, brand voice guidelines, or system-wide instructions.

You can access them in any prompt using the {{ global.variable_name }} syntax.

Example:

As a support agent for {{ global.company_name }}, you must always be polite.

Provided Variables

Agentsmith also injects a few built-in variables for your convenience:

• {{ now() }}: Returns the current UTC date and time in ISO 8601 format (e.g., 2025-07-23T12:00:00.000Z).

Prompt Composition

To keep your prompts organized and reusable, you can include one prompt within another using the {% include %} tag. This is a powerful feature for building complex agents from smaller, manageable parts.

You can include a prompt by its slug, which will use the latest published version, or by a specific version string.

Example:

Let's say you have a prompt with the slug emoji-instruction:

You must include a single {{ color }} colored emoji in your response.

You can include it in another prompt like this:

{% include "emoji-instruction" %}

Respond with your name {{ agent_name }}

You can also specify a version:

{% include "emoji-instruction@0.1.0" %}

Advanced Templating

Jinja offers powerful control flow structures like conditionals and loops. This allows you to build highly dynamic prompts that can adapt to different inputs.

Conditionals

Use if/elif/else blocks to conditionally render content.

{% if user_tier == "premium" %}
Thank you for being a valued premium member.
{% else %}
Consider upgrading to our premium plan for more features.
{% endif %}

Loops

Use for loops to iterate over arrays. This is useful for formatting lists of items, generating examples, or processing structured data.

Please review the following items:
{% for item in item_list %}
- {{ item.name }}: {{ item.description }}
{% endfor %}

For more advanced templating features, refer to the official Nunjucks documentation.

Making Changes from Your Repository

While the Studio provides a great visual editor, you can also embrace a "Git-first" workflow by making changes directly to the prompt files in your local repository. When you push these changes, Agentsmith's Sync Engine will automatically detect them and update the Studio.

Updating an Existing Prompt

To update a prompt, simply edit the relevant files (e.g., content.j2 or variables.json) for the version you wish to change and push your commit. The sync process will update the corresponding prompt in the Studio.

Adding a New Prompt

You can also create a new prompt directly from your filesystem.

1. Create a new directory under agentsmith/prompts/ with the desired slug for your new prompt (e.g., my-new-prompt).
2. Inside that directory, create a prompt.json file.
3. Create a version directory (e.g., 0.0.1/) and add the necessary content.j2, variables.json, and version.json files.

Publishing via Git: Branches and the status Key

Agentsmith uses a combination of your Git branch and a status key in version.json to determine whether a prompt version should be published.

• Feature Branches: When you push changes to any non-default branch (e.g., a feature branch), new prompt versions will always be created in DRAFT status in the Studio. This allows you to safely test changes without affecting your production prompts.
• Default Branch (e.g., main): When you push changes to your repository's default branch, Agentsmith will look at the status field in the version.json file.
  • If "status": "PUBLISHED", the prompt version will be published.
  • If "status": "DRAFT", the version will remain a draft.

This system gives you fine-grained control, allowing you to prepare and review prompt changes in a feature branch and then publish them declaratively by merging to main.

Configuration

Each prompt version has a Configuration section in the Studio where you can set parameters that will be passed to the AI model during execution. This includes settings like:

• Model: The specific LLM to use (e.g., openai/gpt-4o, google/gemini-flash-1.5). You can also specify openrouter/auto to let OpenRouter select the best model.
• Temperature: Controls the randomness of the output.
• Max Tokens: The maximum length of the generated response.

You can find a full list of available models on OpenRouter and all supported configuration options in their API reference.

These settings can be overridden at runtime via the SDK, giving you maximum flexibility.