Agent Providers Reference

Providers supply game context to ElizaOS agents, enabling the LLM to make informed decisions. There are 10 providers that run before each agent decision.

Providers are defined in packages/plugin-hyperscape/src/providers/. PR #628 added 3 new providers for enhanced LLM decision-making.

Provider Execution Order

Providers run in a specific order to ensure dependencies are met:

goalProvider - Current goal (runs first for goal-aware decisions)
gameStateProvider - Health, position, combat status
inventoryProvider - Items and equipment
nearbyEntitiesProvider - Surrounding entities
skillsProvider - Skill levels and XP
equipmentProvider - Currently equipped items
availableActionsProvider - Context-aware action list
possibilitiesProvider - What actions are currently possible (NEW)
goalTemplatesProvider - Structured goal templates (NEW)
guardrailsProvider - Safety constraints and warnings (NEW)

Goal Provider

Provides the agent’s current goal and progress.

// From providers/goalProvider.ts
export const goalProvider: Provider = {
  name: "goal",
  description: "Current goal and progress",

  async get(runtime: IAgentRuntime, message: Memory): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const goal = service.getCurrentGoal();

    if (!goal) {
      return "No current goal set. Consider setting a goal with SET_GOAL.";
    }

    return `
Current Goal: ${goal.description}
Priority: ${goal.priority}/10
Progress: ${goal.progress}%
Started: ${formatTime(goal.startedAt)}
    `.trim();
  },
};

Output Example

Current Goal: Reach level 10 Woodcutting
Priority: 7/10
Progress: 45%
Started: 10 minutes ago

Game State Provider

Provides core player status information.

// From providers/gameState.ts
export const gameStateProvider: Provider = {
  name: "gameState",
  description: "Player health, position, and combat status",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const state = service.getGameState();

    return `
## Player Status
Health: ${state.health}/${state.maxHealth} (${Math.round(state.health/state.maxHealth*100)}%)
Position: (${state.position.x.toFixed(1)}, ${state.position.y.toFixed(1)}, ${state.position.z.toFixed(1)})
In Combat: ${state.inCombat ? "Yes" : "No"}
Combat Target: ${state.combatTarget || "None"}
Run Energy: ${state.runEnergy}%
    `.trim();
  },
};

Output Example

## Player Status
Health: 45/100 (45%)
Position: (125.5, 10.0, -42.3)
In Combat: Yes
Combat Target: goblin_warrior_1
Run Energy: 78%

Inventory Provider

Provides inventory contents and capacity.

// From providers/inventory.ts
export const inventoryProvider: Provider = {
  name: "inventory",
  description: "Items in inventory",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const inventory = service.getInventory();

    const itemList = inventory.items
      .map(item => `- ${item.name} x${item.quantity}`)
      .join("\n");

    return `
## Inventory (${inventory.usedSlots}/${inventory.maxSlots} slots)
Coins: ${inventory.coins.toLocaleString()}

Items:
${itemList || "Empty"}
    `.trim();
  },
};

Output Example

## Inventory (15/28 slots)
Coins: 1,234

Items:
- Bronze Hatchet x1
- Oak Logs x10
- Raw Shrimp x5
- Cooked Shrimp x3
- Tinderbox x1

Nearby Entities Provider

Provides information about surrounding entities.

// From providers/nearbyEntities.ts
export const nearbyEntitiesProvider: Provider = {
  name: "nearbyEntities",
  description: "Players, NPCs, and resources nearby",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const entities = service.getNearbyEntities();

    const players = entities.players.map(p =>
      `- ${p.name} (Level ${p.combatLevel}, ${p.distance.toFixed(1)}m away)`
    ).join("\n");

    const mobs = entities.mobs.map(m =>
      `- ${m.name} (Level ${m.level}, HP: ${m.health}/${m.maxHealth}, ${m.distance.toFixed(1)}m away)`
    ).join("\n");

    const resources = entities.resources.map(r =>
      `- ${r.type} (${r.distance.toFixed(1)}m away)`
    ).join("\n");

    return `
## Nearby Players
${players || "None"}

## Nearby Mobs
${mobs || "None"}

## Nearby Resources
${resources || "None"}
    `.trim();
  },
};

Output Example

## Nearby Players
- PlayerOne (Level 45, 5.2m away)
- PlayerTwo (Level 23, 12.8m away)

## Nearby Mobs
- Goblin Warrior (Level 5, HP: 15/20, 3.1m away)
- Goblin (Level 2, HP: 10/10, 8.4m away)

## Nearby Resources
- Oak Tree (2.5m away)
- Oak Tree (6.1m away)
- Fishing Spot (15.3m away)

Skills Provider

Provides skill levels and XP progress.

// From providers/skills.ts
export const skillsProvider: Provider = {
  name: "skills",
  description: "Skill levels and experience",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const skills = service.getSkills();

    const skillList = Object.entries(skills)
      .map(([name, data]) =>
        `- ${capitalize(name)}: Level ${data.level} (${data.xp.toLocaleString()} XP)`
      )
      .join("\n");

    return `
## Skills
Combat Level: ${skills.combatLevel}
Total Level: ${skills.totalLevel}

${skillList}
    `.trim();
  },
};

Output Example

## Skills
Combat Level: 15
Total Level: 95

- Attack: Level 10 (1,154 XP)
- Strength: Level 12 (1,623 XP)
- Defense: Level 8 (737 XP)
- Constitution: Level 15 (2,411 XP)
- Ranged: Level 1 (0 XP)
- Prayer: Level 5 (388 XP)
- Woodcutting: Level 25 (8,740 XP)
- Fishing: Level 18 (3,258 XP)
- Mining: Level 10 (1,154 XP)
- Firemaking: Level 10 (1,154 XP)
- Cooking: Level 6 (535 XP)
- Smithing: Level 3 (276 XP)
- Agility: Level 8 (737 XP)

Equipment Provider

Provides currently equipped items.

// From providers/equipment.ts
export const equipmentProvider: Provider = {
  name: "equipment",
  description: "Currently equipped items",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const equipment = service.getEquipment();

    return `
## Equipment
Weapon: ${equipment.weapon?.name || "None"}
Shield: ${equipment.shield?.name || "None"}
Helmet: ${equipment.helmet?.name || "None"}
Body: ${equipment.body?.name || "None"}
Legs: ${equipment.legs?.name || "None"}
Boots: ${equipment.boots?.name || "None"}
Gloves: ${equipment.gloves?.name || "None"}
Cape: ${equipment.cape?.name || "None"}
Ring: ${equipment.ring?.name || "None"}
Amulet: ${equipment.amulet?.name || "None"}

## Combat Stats
Attack Bonus: +${equipment.stats.attack}
Strength Bonus: +${equipment.stats.strength}
Defense Bonus: +${equipment.stats.defense}
    `.trim();
  },
};

Output Example

## Equipment
Weapon: Iron Scimitar
Shield: Wooden Shield
Helmet: None
Body: Leather Body
Legs: Leather Chaps
Boots: None
Gloves: None
Cape: None
Ring: None
Amulet: None

## Combat Stats
Attack Bonus: +10
Strength Bonus: +7
Defense Bonus: +15

Available Actions Provider

Provides context-aware list of available actions.

// From providers/availableActions.ts
export const availableActionsProvider: Provider = {
  name: "availableActions",
  description: "Actions the agent can currently perform",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const state = service.getGameState();
    const inventory = service.getInventory();
    const entities = service.getNearbyEntities();

    const actions: string[] = [];

    // Always available
    actions.push("MOVE_TO", "EXPLORE", "IDLE", "SET_GOAL");

    // Combat actions
    if (entities.mobs.length > 0) {
      actions.push("ATTACK_ENTITY", "APPROACH_ENTITY");
    }
    if (state.inCombat) {
      actions.push("FLEE", "CHANGE_COMBAT_STYLE");
    }

    // Skill actions based on tools and resources
    if (hasItem(inventory, "hatchet") && entities.resources.some(r => r.type === "tree")) {
      actions.push("CHOP_TREE");
    }
    if (hasItem(inventory, "fishing_rod") && entities.resources.some(r => r.type === "fishing_spot")) {
      actions.push("CATCH_FISH");
    }
    if (hasItem(inventory, "tinderbox") && hasItem(inventory, "logs")) {
      actions.push("LIGHT_FIRE");
    }
    if (hasItem(inventory, "raw_food") && entities.resources.some(r => r.type === "fire")) {
      actions.push("COOK_FOOD");
    }

    // Inventory actions
    if (inventory.items.length > 0) {
      actions.push("EQUIP_ITEM", "USE_ITEM", "DROP_ITEM");
    }

    // Social
    if (entities.players.length > 0) {
      actions.push("CHAT_MESSAGE", "FOLLOW_ENTITY");
    }

    // Banking
    if (isNearBank(state.position)) {
      actions.push("BANK_DEPOSIT", "BANK_WITHDRAW");
    }

    return `
## Available Actions
${actions.join(", ")}

Use these actions based on your current goal and situation.
    `.trim();
  },
};

Output Example

## Available Actions
MOVE_TO, EXPLORE, IDLE, SET_GOAL, ATTACK_ENTITY, APPROACH_ENTITY, FLEE, CHANGE_COMBAT_STYLE, CHOP_TREE, EQUIP_ITEM, USE_ITEM, DROP_ITEM, CHAT_MESSAGE, FOLLOW_ENTITY

Use these actions based on your current goal and situation.

Possibilities Provider

Analyzes inventory and nearby entities to determine what’s currently possible.

// From providers/possibilitiesProvider.ts (PR #628)
export const possibilitiesProvider: Provider = {
  name: "possibilities",
  description: "What actions are currently possible based on inventory, skills, and nearby entities",
  
  async get(runtime: IAgentRuntime): Promise<ProviderResult> {
    const service = runtime.getService("hyperscapeService");
    const player = service.getPlayerEntity();
    const nearbyEntities = service.getNearbyEntities();
    
    // Calculate what's craftable
    const craftable = {
      smelting: getSmeltableBars(inventory, smithingLevel),
      smithing: getSmithableItems(inventory, smithingLevel),
      cooking: getCookableFood(inventory, cookingLevel),
      firemaking: getBurnableLogs(inventory, firemakingLevel)
    };
    
    // Calculate what's gatherable
    const gatherable = getGatherableResources(nearbyEntities, skills);
    
    // Calculate combat opportunities
    const attackableTargets = getAttackableTargets(nearbyEntities);
    const combatReadiness = getCombatReadiness(service);
    
    return {
      text: formatPossibilities(craftable, gatherable, attackableTargets),
      data: { craftable, gatherable, combat: { attackableTargets, combatReadiness } }
    };
  }
};

Output Example

## What You Can Do Right Now

### Crafting
**Smelting** (at a furnace):
- Bronze Bar: You have copper_ore + tin_ore (can make 5)

**Smithing** (at an anvil):
- Bronze Sword: Need 1 bronze_bar (can make 3)

**Cooking** (on fire/range):
- Raw Shrimp -> Shrimp (10 available)

### Gathering (Nearby)
- Oak Tree x3 (tree) - CAN gather
- Copper Rock x2 (rock) - CAN gather

### Combat
Combat Readiness: 75%
Attackable targets:
- Goblin x5

### Skills You Can Train Now
- **Woodcutting** (Level 10): Chop nearby trees
- **Mining** (Level 5): Mine nearby rocks
- **Cooking** (Level 8): Cook food on a fire or range

Goal Templates Provider

Provides structured goal templates for OSRS beginner flows.

// From providers/goalTemplatesProvider.ts (PR #628)
export const goalTemplatesProvider: Provider = {
  name: "goalTemplates",
  description: "Structured goal templates for OSRS beginner activities",
  
  async get(runtime: IAgentRuntime): Promise<ProviderResult> {
    const service = runtime.getService("hyperscapeService");
    const player = service.getPlayerEntity();
    const nearbyEntities = service.getNearbyEntities();
    
    // Build player context
    const ctx = buildPlayerContext(player, nearbyEntities, combatReadiness);
    
    // Score all templates
    const scoredTemplates = GOAL_TEMPLATES
      .map(template => scoreTemplate(template, ctx))
      .sort((a, b) => b.score - a.score);
    
    const topTemplates = scoredTemplates.filter(t => t.applicable).slice(0, 5);
    
    return {
      text: formatGoalTemplates(topTemplates),
      data: { templates: scoredTemplates, topTemplates }
    };
  }
};

Goal Template Structure

interface GoalTemplate {
  id: string;                    // "woodcutting_basics"
  name: string;                  // "Learn Woodcutting"
  type: string;                  // "woodcutting"
  description: string;           // "Chop trees to gather logs..."
  prerequisites: string[];       // ["Have an axe equipped or in inventory"]
  hardRequirements: string[];    // ["has_axe"] - MUST be met
  steps: string[];               // Step-by-step instructions
  successCondition: string;      // "Woodcutting level 10+"
  recommendedWhen: string[];     // ["trees_nearby", "woodcutting < 20"]
  priority: number;              // Base priority (0-100)
  estimatedTime: string;         // "5-10 minutes"
}

Output Example

## Recommended Goals

Based on your current situation, here are recommended goals:

### 1. Learn Woodcutting (Score: 85)
**Type**: woodcutting
**Description**: Chop trees to gather logs and train woodcutting skill
**Why**: Trees nearby, woodcutting level 5 (room to grow)
**Steps**:
  - Ensure you have an axe (bronze axe works for beginners)
  - Travel to an area with trees (forest location)
  - Click on a tree to start chopping
  - Continue until inventory is full or target level reached
**Success**: Woodcutting level 10+ OR inventory full of logs

### 2. Get Starter Tools (Score: 95)
**Type**: starter_items
**Description**: Acquire basic tools needed for gathering skills
**Why**: No axe - need to acquire tools
**Steps**:
  - Find and loot starter chest near spawn
  - Or: Kill goblins - they sometimes drop tools
  - Priority: Get axe first (for logs), then pickaxe (for ore)
**Success**: Have axe AND pickaxe in inventory

Goal Types:

woodcutting, mining, fishing - Gathering skills
smithing, firemaking, cooking - Artisan skills
combat - Combat training
exploration - Discover new areas
starter_items - Acquire basic tools

Guardrails Provider

Provides safety constraints and warnings to prevent dangerous decisions.

// From providers/guardrailsProvider.ts (PR #628)
export const guardrailsProvider: Provider = {
  name: "guardrails",
  description: "Safety constraints and warnings for decision making",
  
  async get(runtime: IAgentRuntime): Promise<ProviderResult> {
    const service = runtime.getService("hyperscapeService");
    const player = service.getPlayerEntity();
    const nearbyEntities = service.getNearbyEntities();
    const combatReadiness = getCombatReadiness(service);
    
    // Generate warnings and blocked actions
    const activeWarnings = generateWarnings(player, nearbyEntities, combatReadiness);
    const blockedActions = generateBlockedActions(player, nearbyEntities, combatReadiness);
    
    return {
      text: formatGuardrails(activeWarnings, blockedActions),
      data: { hardConstraints, softConstraints, activeWarnings, blockedActions }
    };
  }
};

Output Example

## Safety Guardrails

### ⚠️ CRITICAL WARNINGS
**Health critically low (22%) - FLEE IMMEDIATELY!**
→ Use FLEE action to escape combat

### ⚡ Warnings
- No food in inventory - get food before combat
  → Fish and cook, or buy food from a shop
- Combat readiness low (35%): No weapon equipped, No food
  → Address issues before engaging in combat

### 🚫 Blocked Actions
- **ATTACK_ENTITY**: No weapon equipped
  → Fix by: Equip a weapon from inventory or smith one
- **combat**: No food for healing during combat
  → Fix by: Gather or buy food first

### Hard Rules (MUST Follow)
- NEVER set combat goals when health is below 30%
- NEVER engage in combat without a weapon equipped
- ALWAYS flee immediately when health drops below 25% during combat
- ALWAYS finish killing current target before switching to another

**Status**: 🔴 CRITICAL ISSUES - Address immediately

Warning Levels:

critical - Immediate danger, must address
warning - Risky situation, should address
info - Informational, nice to address

Custom Providers

You can create custom providers for additional context:

import { Provider, IAgentRuntime, Memory } from "@elizaos/core";

export const customProvider: Provider = {
  name: "custom",
  description: "Custom context for agents",

  async get(runtime: IAgentRuntime, message: Memory): Promise<string> {
    // Fetch custom data
    const data = await fetchCustomData(runtime);

    return `
## Custom Context
${formatCustomData(data)}
    `.trim();
  },
};

Possibilities Provider

Tells the LLM what actions are currently possible based on inventory, skills, and nearby entities.

// From providers/possibilitiesProvider.ts
export const possibilitiesProvider: Provider = {
  name: "possibilities",
  description: "What actions are currently possible based on inventory, skills, and nearby entities",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const player = service.getPlayerEntity();
    const nearbyEntities = service.getNearbyEntities();
    const inventory = player.items || [];
    const skills = player.skills;

    // Calculate what can be crafted
    const craftable = {
      smelting: getSmeltableBars(inventory, skills.smithing.level),
      smithing: getSmithableItems(inventory, skills.smithing.level),
      cooking: getCookableFood(inventory, skills.cooking.level),
      firemaking: getBurnableLogs(inventory, skills.firemaking.level),
    };

    // Calculate what can be gathered
    const gatherable = getGatherableResources(nearbyEntities, skills);

    // Calculate combat readiness
    const combatReadiness = getCombatReadiness(service);

    return formatPossibilities(craftable, gatherable, combatReadiness);
  },
};

Output Example

## What You Can Do Right Now

### Crafting
**Smelting** (at a furnace):
- Bronze Bar: You have copper_ore + tin_ore (can make 5)

**Smithing** (at an anvil):
- Bronze Sword: Need 1 bronze_bar (can make 3)
- Bronze Pickaxe: Need 2 bronze_bar (can make 1)

### Gathering (Nearby)
- Oak Tree x3 (tree) - CAN gather
- Copper Rock x2 (rock) - CAN gather

### Combat
Combat Readiness: 75%
Attackable targets:
- Goblin x5

### Status
- Food: Yes
- Inventory: 12 slots free

Goal Templates Provider

Provides structured goal templates for OSRS beginner flows with scoring based on current state.

// From providers/goalTemplatesProvider.ts
export const goalTemplatesProvider: Provider = {
  name: "goalTemplates",
  description: "Structured goal templates for OSRS beginner activities",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const player = service.getPlayerEntity();
    const nearbyEntities = service.getNearbyEntities();

    // Score all templates based on current state
    const scoredTemplates = GOAL_TEMPLATES.map(template =>
      scoreTemplate(template, buildPlayerContext(player, nearbyEntities))
    ).sort((a, b) => b.score - a.score);

    // Filter to applicable templates (prerequisites met)
    const topTemplates = scoredTemplates.filter(t => t.applicable).slice(0, 5);

    return formatGoalTemplates(topTemplates);
  },
};

Goal Templates Include:

Acquire starter tools (axe, pickaxe, tinderbox)
Woodcutting basics
Mining basics
Fishing basics
Bronze gear crafting chain (mine → smelt → smith)
Combat training on goblins
Firemaking and cooking

Scoring Factors:

Prerequisites met (hard requirements)
Recommended conditions (soft factors)
Diversity penalty (encourages variety)
Recent goal history (prevents repetition)

Output Example

## Recommended Goals

### 1. Learn Woodcutting (Score: 85)
**Type**: woodcutting
**Description**: Chop trees to gather logs and train woodcutting skill
**Why**: Trees nearby, woodcutting level 5 (room to grow)
**Steps**:
  - Ensure you have an axe (bronze axe works for beginners)
  - Travel to an area with trees (forest location)
  - Click on a tree to start chopping
**Success**: Woodcutting level 10+ OR inventory full of logs

Guardrails Provider

Provides safety constraints and warnings for LLM decision-making.

// From providers/guardrailsProvider.ts
export const guardrailsProvider: Provider = {
  name: "guardrails",
  description: "Safety constraints and warnings for decision making",

  async get(runtime: IAgentRuntime): Promise<string> {
    const service = runtime.getService("hyperscape") as HyperscapeService;
    const player = service.getPlayerEntity();
    const nearbyEntities = service.getNearbyEntities();
    const combatReadiness = getCombatReadiness(service);

    // Generate warnings and blocked actions
    const activeWarnings = generateWarnings(player, nearbyEntities, combatReadiness);
    const blockedActions = generateBlockedActions(player, nearbyEntities, combatReadiness);

    return formatGuardrails(activeWarnings, blockedActions);
  },
};

Hard Constraints (MUST follow):

NEVER set combat goals when health is below 30%
NEVER engage in combat without a weapon equipped
ALWAYS flee immediately when health drops below 25% during combat
NEVER travel more than 200 tiles from spawn point
ALWAYS finish killing current target before switching

Soft Constraints (SHOULD follow):

Prefer goals that utilize current inventory items
Prefer nearby resources over distant ones
Balance skill training - don’t over-specialize too early
Gather food supplies before extended combat sessions

Output Example

## Safety Guardrails

### ⚠️ CRITICAL WARNINGS
**Health at 28% - eat food or avoid combat**
→ Eat food to restore health

### 🚫 Blocked Actions
- **ATTACK_ENTITY**: No weapon equipped
  → Fix by: Equip a weapon from inventory or smith one

### Hard Rules (MUST Follow)
- NEVER set combat goals when health is below 30%
- NEVER engage in combat without a weapon equipped
- ALWAYS flee immediately when health drops below 25% during combat

**Status**: 🟡 Some actions blocked - see above

Overview

Engine Architecture

Client Application

Game Systems

AI Agents

Data Manifests

Technical Reference

Agent Providers Reference

Agent Providers Reference

Provider Execution Order

Goal Provider

Output Example

Game State Provider

Output Example

Inventory Provider

Output Example

Nearby Entities Provider

Output Example

Skills Provider

Output Example

Equipment Provider

Output Example

Available Actions Provider

Output Example

Possibilities Provider

Output Example

Goal Templates Provider

Goal Template Structure

Output Example

Guardrails Provider

Output Example

Custom Providers

Possibilities Provider

Output Example

Goal Templates Provider

Output Example

Guardrails Provider

Output Example

Overview

Engine Architecture

Client Application

Game Systems

AI Agents

Data Manifests

Technical Reference

​Agent Providers Reference

​Provider Execution Order

​Goal Provider

​Output Example

​Game State Provider

​Output Example

​Inventory Provider

​Output Example

​Nearby Entities Provider

​Output Example

​Skills Provider

​Output Example

​Equipment Provider

​Output Example

​Available Actions Provider

​Output Example

​Possibilities Provider

​Output Example

​Goal Templates Provider

​Goal Template Structure

​Output Example

​Guardrails Provider

​Output Example

​Custom Providers

​Possibilities Provider

​Output Example

​Goal Templates Provider

​Output Example

​Guardrails Provider

​Output Example

​Related Documentation

Agent Providers Reference

Provider Execution Order

Goal Provider

Output Example

Game State Provider

Output Example

Inventory Provider

Output Example

Nearby Entities Provider

Output Example

Skills Provider

Output Example

Equipment Provider

Output Example

Available Actions Provider

Output Example

Possibilities Provider

Output Example

Goal Templates Provider

Goal Template Structure

Output Example

Guardrails Provider

Output Example

Custom Providers

Possibilities Provider

Output Example

Goal Templates Provider

Output Example

Guardrails Provider

Output Example

Related Documentation