# LLM & Role Design

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"

```json
{
  "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:

1. User selects a role\
   `npx pilso start -r deployer`
2. The role loads:
   * Model config (Claude, GPT, etc)
   * Prompt personality & goals
   * Allowed tool set
   * Guardrails
3. Agent receives a prompt\
   → “Deploy this contract on Base”
4. Agent maps to tool flow\
   → `solc.compile` → `chainlist.resolve` → `metamask.sign`
5. Response 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/llm-and-role-design.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.