Skip to main content

Overview

The swarms.prompts module provides tools for creating, managing, and versioning prompts with comprehensive history tracking, autosaving capabilities, and integration with agent systems. swarms.prompts exports 12 names: the Prompt class, eight prompt strings (AUTO_AGENT_BUILDER_SYSTEM_PROMPT, CODE_INTERPRETER, DOCUMENTATION_WRITER_SOP, FINANCE_AGENT_PROMPT, GROWTH_AGENT_PROMPT, LEGAL_AGENT_PROMPT, OPERATIONS_AGENT_PROMPT, PRODUCT_AGENT_PROMPT), and three autonomous-prompt functions. All of them are re-exported from the top-level swarms package. The prompts that framework structures use internally live in their own modules; see Prompts used by framework structures.

Prompt Class

A Pydantic model for managing prompts with version control, edit history, and autosaving features.

Constructor

str
default:"uuid.uuid4().hex"
Identifier for the prompt, also used in the autosave file name
The default id is generated once, when the module is imported, so every Prompt created without an explicit id shares the same value. With autosave=True those prompts overwrite each other’s file. Pass your own id (for example uuid.uuid4().hex) for each prompt you autosave.
str
default:"prompt"
Name of your prompt
str
default:"Simple Prompt"
Description of the prompt
str
required
The main content of the prompt. Leading and trailing whitespace is stripped, and at least 1 character must remain
str
default:"current_time"
Timestamp when the prompt was created
str
default:"current_time"
Timestamp when the prompt was last modified
int
default:"0"
Number of times the prompt has been edited
List[str]
default:"[]"
History of all prompt versions
bool
default:"False"
Save the prompt to disk on creation and after every edit or rollback
str
default:"prompts"
Folder path within WORKSPACE_DIR for autosaving
bool
default:"False"
Stored on the model but not used by any Prompt method
str
default:"WORKSPACE_DIR"
Defaults to the workspace directory. Stored only; autosave always writes under WORKSPACE_DIR
Any
default:"None"
Stored on the model but not used by any Prompt method

Methods

edit_prompt

Edit the prompt content and update version control.
str
required
The updated content of the prompt
It appends the new content to edit_history, increments edit_count, and updates last_modified_at. Raises:
  • ValueError: If the new content is identical to the current content

rollback

Roll back the prompt to a previous version. The content becomes edit_history[version] and edit_count is set to version. edit_history is not trimmed, so you can roll forward again.
int
required
The version index to roll back to (0 is the first version)
Raises:
  • IndexError: If the version number is out of range

get_prompt

Return the current prompt content as a string.
str
The current prompt content

return_json

Return the prompt as a JSON string.
str
JSON representation of the prompt with all metadata

add_tools

Intended to append the OpenAI schemas of a list of functions to the prompt content.
List[Callable]
required
List of callable functions to add as tools
add_tools() currently raises TypeError, because it concatenates the schema dict to the content string. It appends two newlines to content before it fails. Until it is fixed, build the schema yourself and pass it to edit_prompt():

save_to_storage and load_from_storage

Placeholders for a storage backend. Both raise NotImplementedError; use autosave or return_json() to persist a prompt.

Pre-built Prompt Templates

The module includes numerous pre-built prompt templates for common agent roles:

Finance Prompts

FINANCE_AGENT_PROMPT

Comprehensive prompt for financial analysis agents.
Prompt template for legal analysis and research agents.

Product & Operations

PRODUCT_AGENT_PROMPT

Prompt for product management agents.

OPERATIONS_AGENT_PROMPT

Prompt for operations management agents.

GROWTH_AGENT_PROMPT

Prompt for growth and marketing agents.

Development Prompts

CODE_INTERPRETER

Prompt for code interpretation and execution agents.

DOCUMENTATION_WRITER_SOP

Standard operating procedure for documentation writing agents.

AUTO_AGENT_BUILDER_SYSTEM_PROMPT

System prompt for an architect agent that designs a small team of specialized agents for a task. It is the default system prompt of AutoAgentBuilder.

Autonomous Agent Prompts

These build the system prompt an agent uses with max_loops="auto". See Autonomous mode.

autonomous_agent_system_prompt

Return the base autonomous agent system prompt. Its Time: line holds the date and time when you call it.
The AUTONOMOUS_AGENT_SYSTEM_PROMPT constant has been removed. As a module-level string, it froze the time at import, so long-running processes told every agent the process start time. Call autonomous_agent_system_prompt() instead.

get_autonomous_agent_prompt

Return the autonomous agent prompt, matched to whether the agent has the think tool.
bool
default:"False"
Whether the agent has the think tool. When False, a section is appended telling the model the tool is unavailable and to reason inline instead

get_autonomous_agent_prompt_with_context

Generate an autonomous agent prompt customized with agent identity and available tools.
str
default:"None"
Name of the agent to embed in the prompt
str
default:"None"
Description of the agent’s role to embed in the prompt
list
default:"None"
List of tool names available to the agent. The first 20 are listed, followed by a count of the rest
The agent name replaces the opening “You are an elite autonomous agent” line, and the description and tools are appended as ## AGENT ROLE and ## AVAILABLE TOOLS sections. This function always keeps the think tool instructions.

Prompts used by framework structures

Framework structures keep their prompts in dedicated modules under swarms/prompts. They are not exported from swarms.prompts, so import them from the module path. Read them to see what a structure tells its agents, or to build a variant.

Default agent system prompt

AGENT_SYSTEM_PROMPT_3 is the default agent persona without a timestamp. build_agent_system_prompt() returns the same text with a Time: line for the current date and time. Agent calls it in __init__ when system_prompt is None, so each agent gets the time it was created, not the time the module was imported.

Groupchat decision prompt

GROUPCHAT_DECIDE_PROMPT is formatted with agent_name, other_agents, sender and message. It asks the agent to assess the discussion, then call respond once with a calibrated score from 0.0 to 1.0 and its reply. It says what deserves a high, moderate or low score, gives a calibration scale, and says to answer 0.0 with an empty message when there is nothing distinct to add. It also tells the agent not to inflate the score to keep the conversation going.

LLM council prompts

The four councilor personas, the chairman prompt, and the peer-evaluation and synthesis builders live in swarms.prompts.llm_council_prompts. swarms.structs.llm_council imports them back, so existing imports from the struct module keep working.

Example: Complete Prompt Management

Best Practices

  1. Enable autosave: Always enable autosave for important prompts to prevent data loss
  2. Use descriptive names: Give prompts clear, descriptive names for easy identification
  3. Version control: Leverage the built-in version control to track prompt evolution
  4. Add context: Include detailed descriptions to document the prompt’s purpose
  5. Organize by folder: Use the autosave_folder parameter to organize prompts by category
  6. Regular rollbacks: Test different prompt versions using rollback functionality
  7. Unique IDs: Pass an explicit id to every prompt you autosave

Thread safety

Prompt does not lock. Edits, rollbacks and autosaves are plain attribute updates and file writes, so guard a Prompt shared across threads with your own threading.Lock.

Autosave Behavior

When autosave is enabled:
  1. Prompts are saved to {WORKSPACE_DIR}/{autosave_folder}/prompt-id-{id}.json. When WORKSPACE_DIR is unset, importing swarms sets it to ./agent_workspace
  2. Creating the prompt triggers a save
  3. Each edit automatically triggers a save
  4. Rollback operations also trigger saves
  5. The entire prompt state (including history) is preserved

Integration with Agents