Overview
Theswarms.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
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 methodstr
default:"WORKSPACE_DIR"
Defaults to the workspace directory. Stored only; autosave always writes under
WORKSPACE_DIRAny
default:"None"
Stored on the model but not used by any
Prompt methodMethods
edit_prompt
Edit the prompt content and update version control.str
required
The updated content of the prompt
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 becomesedit_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)
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
save_to_storage and load_from_storage
Placeholders for a storage backend. Both raiseNotImplementedError; 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.Legal Prompts
LEGAL_AGENT_PROMPT
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 withmax_loops="auto". See Autonomous mode.
autonomous_agent_system_prompt
Return the base autonomous agent system prompt. ItsTime: line holds the date and time when you call it.
get_autonomous_agent_prompt
Return the autonomous agent prompt, matched to whether the agent has thethink 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 insteadget_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
## 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 underswarms/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 inswarms.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
- Enable autosave: Always enable autosave for important prompts to prevent data loss
- Use descriptive names: Give prompts clear, descriptive names for easy identification
- Version control: Leverage the built-in version control to track prompt evolution
- Add context: Include detailed descriptions to document the prompt’s purpose
- Organize by folder: Use the
autosave_folderparameter to organize prompts by category - Regular rollbacks: Test different prompt versions using rollback functionality
- Unique IDs: Pass an explicit
idto 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:- Prompts are saved to
{WORKSPACE_DIR}/{autosave_folder}/prompt-id-{id}.json. WhenWORKSPACE_DIRis unset, importingswarmssets it to./agent_workspace - Creating the prompt triggers a save
- Each edit automatically triggers a save
- Rollback operations also trigger saves
- The entire prompt state (including history) is preserved