Prompts

Prompts are the system instructions attached to agents. They define the agent's role, communication style, operating rules, tool-use guidance, domain knowledge, safety constraints, output format, and examples.

Use layered_prompt(...) to build those instructions from named sections instead of one large free-form string. The helper renders deterministic prompt text, omits empty sections, and returns a LayeredPrompt with both the text and a cache key.

The cache key is a SHA-256 hash of the rendered prompt text. The harness uses it as a stable fingerprint for change detection and traceability when a LayeredPrompt is attached to an agent or when runtime assembly augments the prompt with tool descriptions. It is not a secret, and it is not a provider credential or provider-side cache directive.

layered_prompt

layered_prompt(*, identity: 'str', communication: 'TextSection' = None, operational_rules: 'TextSection' = None, tools: 'Iterable[ToolPromptInput] | None' = None, domain_knowledge: 'StructuredSection' = None, safety: 'TextSection' = None, output_format: 'StructuredSection' = None, examples: 'StructuredSection' = None) -> 'LayeredPrompt'

Parameter	Type	Default
identity	str	required
communication	TextSection	None
operational_rules	TextSection	None
tools	Iterable[ToolPromptInput] | None	None
domain_knowledge	StructuredSection	None
safety	TextSection	None
output_format	StructuredSection	None
examples	StructuredSection	None

Returns: LayeredPrompt

Build the sanctioned Flow AI layered prompt shape.

The returned text is deterministic for identical inputs. The cache key is the SHA-256 hash of the rendered prompt text, so changing any rendered section changes the key. The key is a stable fingerprint for change detection and traceability; it is not a provider credential or a provider-side cache directive. Empty sections are omitted.

Args: identity: Who the agent is. Required; string or sequence of strings rendered as a bullet list. communication: Tone and audience guidance; string or sequence of strings. operational_rules: Behavioral rules; string or sequence of strings. tools: Tool rows rendered as a Markdown table: ToolSpec values, mappings with name / description / approval, or plain names. Duplicate names keep the first row. domain_knowledge: Business context; a string, or any JSON-serializable structure rendered as a JSON code block. safety: Safety constraints; string or sequence of strings. output_format: Expected output shape; string or JSON-serializable structure. examples: Worked examples; string or JSON-serializable structure.

Returns: A LayeredPrompt with the rendered text and its deterministic cache key.

Raises: TypeError: If a text section is not a string or sequence of strings, or a structured section contains values that cannot be rendered as JSON.

LayeredPrompt

LayeredPrompt(text: 'str', cache_key: 'str') -> None

Parameter	Type	Default
text	str	required
cache_key	str	required

Returns: None

Rendered layered prompt plus its deterministic prompt fingerprint.

cache_key is the SHA-256 hash of text. It is used by the harness to detect rendered prompt changes and to refresh the agent prompt fingerprint after runtime tool descriptions are merged into the prompt.