Roles

You can customize any agentic object's role from the outside without changing the class code. This is useful for steering the agent toward a specific model — for example, applying an expensive model where it is needed and a cheaper one elsewhere.

Automatic Configuration

Roles are automatically loaded from the roles/ sibling directory of peteos.json on import. Each subdirectory under roles/ represents one role:

my-project/
└── roles/
    └── MyRole/
        ├── description.md     # Required
        ├── system_prompt.md   # Optional
        └── config.json        # Optional

No Python code is needed — roles are loaded and registered automatically.

Directory Structure

File	Required	Purpose
description.md	Yes	Role description — used by the agent to identify its identity.
system_prompt.md	No	System prompt text to customize the agent's behavior.
config.json	No	Optional runtime configuration — see below.

Config File Format

{
    "model": "gpt-4",
    "required_tools": ["read_file"],
    "auto_approve_tools": ["read_file"],
    "tool_filter": ["read_.*"],
    "execution_environment": "REPL",
    "behavior_policy": "responsive",
    "max_truncation_retries": 2,
    "max_output_turns": 3,
    "max_output_attempts": 3
}

Field	Type	Default	Purpose
model	string	".*"	Regex matching allowed model IDs.
required_tools	string[]	[]	Tool names available to this role.
execution_environment	string	"REPL"	Execution environment identifier.
auto_approve_tools	string[]	[]	Tool names auto-approved without user confirmation.
tool_filter	string[]	[]	Regex patterns; only matching tools are visible to the role.
behavior_policy	string	"responsive"	"responsive" yields on output; "continuous" loops until yield_back.
max_truncation_retries	int	2	Max retries for token-window truncation.
max_output_turns	int	3	Max output-producing turns per invoke_agent call.
max_output_attempts	int	3	Max produce_output attempts per output turn.

Markdown files take precedence over config.json entries.

Manual Registration

For dynamic scenarios, you can register roles manually at runtime.

from peteos.persona.role import Role
from peteos.persona.rolemanager import RoleManager

RoleManager.register_role(Role(
    name="oap_MyAgent",
    model="gpt-4",
    description="A customized agent",
))

The role name must match the canonical role name of the agentic object class it targets. Use @agentic_object(role="...") to set a custom name on your class.

You can also load roles from an arbitrary directory:

loaded = RoleManager.load_from_dir("/path/to/roles/")