Architecture

Roles

Structured agent contracts that define how agents behave—independent of the task-specific inputs they receive.

What Is a Role?

A role is a structured contract that defines an agent's behavior. It specifies what the agent is responsible for, what it may and may not do, and what form its output must take.

Roles are not prompts. They are not written by users at request time. They are stable, tested configurations that constrain agent behavior across all invocations.

When a workflow step executes, the system binds an agent to a role. The role determines how the agent behaves. The workflow determines when the agent acts and what inputs it receives.

Role Components

Every role definition includes these elements:

Responsibility

What this agent is accountable for producing. Defines the scope of work and success criteria.

"Synthesize source materials into a structured literature review with thematic organization."

Scope

What the agent may and may not do. Establishes boundaries on behavior and output.

"May not introduce claims unsupported by provided sources. May not exceed 2000 words."

Biases

Intentional stylistic or epistemic orientations. How the agent should approach ambiguity or emphasis.

"Prefer primary sources over secondary. When evidence conflicts, present both positions."

Constraints

Hard limits on execution. Format requirements, forbidden patterns, mandatory inclusions.

"All factual claims must include inline citations. Output must be valid Markdown."

Output Schema

The structure the agent's output must satisfy. May include required sections, fields, or format specifications.

"Must include: summary, methodology, findings, limitations, references."

Roles vs. Prompts

In many AI systems, users write prompts that begin with role-like instructions: “You are a world-class researcher...” This pattern conflates identity, instruction, and constraints into a single user-authored string.

Esy separates these concerns:

Aspect
Prompt-Based Systems
Esy Roles
Authorship
Written by user for each request
Pre-defined by workflow designers
Stability
Varies with each invocation
Stable across all invocations
Scope
Often task-specific instructions
General behavioral contract
Validation
No systematic validation
Tested and versioned
Visibility
User-facing interface element
System-level configuration

Key Distinction

Users select roles; they do not write them. A role like “Research Synthesizer” or “Citation Auditor” is a pre-engineered contract—not a text field for users to author “You are a...” instructions.

Roles and Workflows

Roles and workflows are complementary but distinct:

Workflows

Define the sequence of operations: which steps execute, in what order, with what inputs and outputs.

Workflows decide when agents act.

Roles

Define agent behavior: what responsibilities the agent has, what constraints it operates under, what outputs it produces.

Roles decide how agents behave.

A single role may be used across many workflows. A single workflow may invoke many different roles at different steps. This separation allows both to be designed, tested, and versioned independently.

Role Selection

For most users, role selection is handled automatically. When you use a pre-built workflow, roles are already assigned to each step.

Pro users designing custom workflows may select which role executes each step. This is selection from a curated set—not freeform authorship. Available roles are:

  • Tested for behavioral consistency
  • Documented with clear scope definitions
  • Versioned to track changes over time
  • Constrained to prevent scope creep

Roles Are Not Endlessly Customizable

Unlike prompt-first systems where users can write any instruction, Esy's roles are fixed contracts. This is intentional. Reliability comes from constraint. If you need behavior a role doesn't support, the solution is a different role—not ad-hoc prompt modification.

How Roles Become Prompts

At execution time, the system generates prompts from role definitions. This is an internal process:

  1. 1The workflow step identifies which role should execute
  2. 2The role definition is retrieved (responsibility, scope, constraints, output schema)
  3. 3Step inputs are prepared from workflow state and user context
  4. 4The system constructs a prompt that encodes the role's contract plus the step's inputs
  5. 5The agent executes against this prompt
  6. 6Output is validated against the role's output schema

Users never see or edit these generated prompts. The role contract, not user prompt-writing skill, determines output quality.

Related Concepts