HX115 - Agent Builder

Agent Builder is the HyperionX surface for creating specialized Rion agents. It belongs in the course as its own module because it is different from the normal AI chat window: chat is a conversation surface, while Agent Builder defines identity, tools, workspace access, routing, risk limits, and audit behavior.

Goals

After this lesson you should be able to:

• Open Agent Builder from the main window or Rion chat.
• Understand the license gate.
• Configure an agent profile.
• Assign provider, model, prompt files, skills, and tool permissions.
• Keep agents read-only before allowing execution.
• Define trading limits before any order-routing capability is enabled.
• Know how Agent Builder fits with Code Lab, Validator, Optimizer, chart context, and local API actions.

Where To Open It

Agent Builder is available from:

• Main window Tools -> Agent Builder.
• Rion chat agent controls.

The window is license-gated. It requires a Pro, Elite, or Admin license with the agent_builder entitlement. If the entitlement is missing, HyperionX shows an Agent Builder locked message instead of opening the builder.

What Agent Builder Controls

An agent profile should define the boundaries of one specialized assistant.

Core areas:

Area	Purpose
Profile	Agent name, role, and system prompt.
Provider	Model, API key, endpoint, and model-specific settings.
Permissions	Chart data, indicators/scripts, Chart Trader state, and trading approval policy.
Workspace	Files and folders the agent can use.
Prompt files	Reusable instruction documents injected into the agent.
Skills	Task-specific instruction packs and tool rules.
Runtime routing	Agent id, session scope, chart routing, heartbeat, and queue mode.
Safety	Approval rules, read-only defaults, audit policy, pause-on-error behavior.
Trading limits	Quantity limits, daily loss stop, access profile, account/instrument rules, bracket/OCO rules.
Performance	Requests, token use, uptime, downtime, and recent action history.

The course should teach agents as configured workers, not as a loose chat prompt.

Profile

The Profile section defines the agent's identity.

Teach:

• Use a clear name tied to the job.
• Use a short role that says what the agent is allowed to do.
• Keep the system prompt specific to HyperionX and the selected workflow.
• Tell the agent whether it is read-only, draft-only, simulation-only, or approved for execution.

Examples:

Agent	Good role
Code Lab Builder	Draft and debug HyperionX indicators and strategies using local Code Lab rules.
Strategy Researcher	Review Validator and Optimizer results and explain parameter behavior.
Chart Scout	Read active chart context and summarize market structure.
Risk Monitor	Watch position, order, and account risk limits.
Journal Assistant	Convert trades and notes into structured journal entries.

Provider And Model

The Provider section controls the AI backend.

Teach:

• Pick the provider/model for the agent's job.
• Store API keys in the settings surface, not in script files.
• Keep endpoint fields provider-specific.
• Do not mix provider failure with local platform failure.
• Keep tool results separate from model text.

An agent can be useful with read-only chart context even before it has permission to execute tools.

Permissions

Agent permissions should be staged by risk.

Start with:

• Read chart.
• Read indicators.
• Read market data.
• Read strategy state.

Add only when needed:

• File access.
• Code Lab drafting.
• Code Lab compile diagnostics.
• Validator and Optimizer control.
• Drawing actions.
• Simulation order actions.
• Live trading actions.

Trading actions should require approval by default. Read-only default and audit every action should stay enabled for new agents.

Workspace And Prompt Files

Agent Builder includes workspace and prompt-file settings.

Typical workspace root:

%USERPROFILE%\Documents\HyperionX\Agents\Workspace

Prompt files can include:

• AGENTS.md
• SOUL.md
• TOOLS.md
• IDENTITY.md
• USER.md
• BOOTSTRAP.md

Course rule: prompt files can guide behavior, but platform permissions still enforce what the agent can actually do. Do not rely on prompt text alone for safety.

Skills

Skills are reusable task packs. A skill should be scoped to one kind of work.

Examples:

• Market context review.
• Order-risk review.
• Journal review.
• Build a HyperionX indicator.
• Build a HyperionX strategy.
• Explain a Validator result.
• Diagnose a connection error.

Skill path pattern:

%USERPROFILE%\Documents\HyperionX\Agents\Workspace\skills\<skill>\SKILL.md

Teach users to add skills slowly. A large pile of broad skills makes the agent harder to audit.

Runtime And Routing

Runtime settings decide where the agent operates.

Important fields:

• Agent id.
• Session scope.
• Routing rules.
• Heartbeat.
• Queue mode.

Session scope examples:

• Main chart session.
• Per instrument.
• Per workspace.

Routing should normally use the active chart, selected instrument, and Chart Trader context. If the user is in multi-chart mode, they should click the intended chart before asking the agent to inspect or act.

Safety And Trading Limits

Agent Builder includes safety and trading limits because an agent can move from analysis into action.

Default safety rules:

• Require approval.
• Read-only default.
• Audit every action.
• Pause on errors.

Trading-limit examples:

• Max order quantity.
• Daily loss stop.
• Sandbox/access profile.
• Escalation notes.
• Max position size.
• Max trades per day.
• Take-profit rule.
• Stop-loss rule.
• Stop on disconnect.
• Disable after loss stop.
• Pause outside session.

Agents should be trained in this order:

1. Read-only chart and platform context.
2. Code Lab draft generation.
3. Code Lab compile diagnostics.
4. Validator and Optimizer review.
5. Simulation-only order preparation.
6. Confirmed Hyperion Sim actions.
7. Live trading only after explicit product policy, entitlements, risk controls, and audit coverage.

Code Lab Integration

Agent Builder can connect users back to Code Lab through build indicator and build strategy actions.

Teach:

• Agent-generated scripts must follow HyperionX Code Lab policy.
• Scripts must compile before they are treated as usable.
• A Code Lab agent should inspect local API rules before generating code.
• Strategy agents should use Validator and Optimizer output before recommending parameter changes.

The agent should not paste unsupported platform calls into Code Lab. HyperionX scripts must use HyperionX namespaces, lifecycle, drawing APIs, order helpers, and generated-support rules.

Validator And Optimizer Integration

A research agent can help with:

• Creating a basic Validator setup from the active chart.
• Explaining Validator errors.
• Summarizing performance.
• Comparing optimization periods.
• Highlighting overfit parameter regions.
• Exporting or preserving a research record.

The agent should never treat one profitable result as production-ready. It should ask whether the test includes realistic fees, slippage, leverage, out-of-sample periods, and enough trades.

Acceptance Checklist

An Agent Builder workflow is ready when:

• Agent Builder opens from the main window and Rion chat path.
• The license gate blocks unentitled users clearly.
• The agent has a name, role, and specific system prompt.
• Provider/model settings are configured without exposing secrets in prompts.
• Prompt files and skills are scoped to the agent's job.
• Tool permissions start read-only.
• Trading actions require approval unless the user intentionally enables a stronger policy.
• Risk limits are defined before order-routing tools are enabled.
• Agent actions can be audited after the fact.
• Code Lab, Validator, Optimizer, and chart-context actions are taught as separate permissions.