Role

A Role defines an agent's identity and behavior: its name, the model it uses, and how it interacts with tools.

Constructor

from peteos.persona.role import Role

Role(
    name: str,
    description: str | None,
    system_prompt: str | None = None,
    system_prompt_hooks: list[Callable[[], str]] | None = None,
    required_tools: list[str] | None = None,
    execution_environment: str = "REPL",
    model: str = ".*",
    auto_approve_tools: list[str] | None = None,
    tool_filter: list[str] | None = None,
    behavior_policy: str = "responsive",
    max_truncation_retries: int = 2,
    max_output_turns: int = 3,
    max_output_attempts: int = 3,
)

Parameter	Default	Description
name	required	Unique identifier for the role.
description	None	Brief description of what the agent does.
system_prompt	None	Static text that forms the agent's initial instructions.
system_prompt_hooks	None	Callbacks invoked at session creation to append dynamic fragments to the system prompt.
required_tools	None	Tools that must be available for this role.
execution_environment	"REPL"	Execution environment identifier.
model	".*"	Regex pattern to match model IDs.
auto_approve_tools	None	Tool names the agent can call without user approval.
tool_filter	None	Regex patterns. Only tools whose names match any pattern are visible to the agent.
behavior_policy	"responsive"	Agent behavior strategy. "responsive" yields on text output; "continuous" keeps looping until yield.
max_truncation_retries	2	Maximum number of retries due to token window truncation.
max_output_turns	3	Maximum number of output-producing turns per invoke_agent call before giving up.
max_output_attempts	3	Maximum number of produce_output call attempts per output turn before failing.

Methods

Method	Description
add_system_prompt_hook(hook) → None	Add a callback that returns a dynamic fragment for the system prompt.
load_from_dict(data) → Role	Create a new Role from a dictionary.
load_from_path(path) → Role	Create a new Role from a directory containing description.md and optional files.