LLM & Role Design
Session config, role definitions, prompt-to-tool routing
PILSO OS is powered by LLM agents — but unlike basic chat-based tools, these agents are structured, scoped, and controlled through roles.
Every agent session in PILSO is defined by:
The language model (e.g. Claude, GPT, Deepseek)
The role it assumes (e.g. signer, deployer, auditor)
The tool access it’s allowed to invoke
The memory and context it’s initialized with
This allows you to build agents that behave like secure, purpose-built copilots — not generic chatbots.
What is a Role?
A role is a configuration object that defines an agent’s personality, scope, and access within a PILSO session.
It acts as:
A prompt template that sets the tone, behavior, and goals of the agent
A permissions layer for controlling tool usage
A contextual identity that guides the LLM's responses
Each role lives in your .roles.json file and is selected at runtime using the CLI.
Example Role: "Deployer"
{
"name": "deployer",
"description": "You are a smart contract deployment agent.",
"tools": ["solc.compile", "metamask.sign"],
"goals": [
"Compile contracts",
"Prepare and sign deployment transactions",
],
"guardrails": [
"Never send tokens",
"Never interact with unknown contracts",
"Always ask for confirmation before signing"
]
}This configuration:
Sets clear boundaries for the LLM’s behavior
Limits which MCP tools it can call
Hardcodes safe defaults that prevent key misuse or permission drift
Why Roles Matter
LLMs are flexible but fragile — without guardrails, they can:
Confuse one task for another
Attempt risky or unintended operations
Misuse tools if poorly prompted
Roles ensure:
Consistent and reproducible behavior
Better prompt injection protection
Clear auditability and traceability of intent → tool usage
They transform the LLM from a general-purpose assistant into a task-specific agent.
Session Flow with Roles
Here’s how a role-based session works in PILSO:
User selects a role
npx pilso start -r deployerThe role loads:
Model config (Claude, GPT, etc)
Prompt personality & goals
Allowed tool set
Guardrails
Agent receives a prompt → “Deploy this contract on Base”
Agent maps to tool flow →
solc.compile→chainlist.resolve→metamask.signResponse is returned and signed via wallet
Security Through Role Design
While the wallet remains the ultimate authority in PILSO, a well-structured role helps ensure:
Agents don’t accidentally request dangerous operations
You don’t over-expose tools to general-purpose models
Every tool call can be traced back to a scoped role
Roles are your first line of logic-level defense — and your main abstraction for intelligent automation.
Last updated