Integration Guide · Phase 2

Design Rules

Define WHAT your agent should do - game rules, behavioral guidelines, and tool usage.

Overview

Instructions define the agent's task, rules, and expected behaviors. While personality defines WHO the agent is, instructions define WHAT they should do in your specific application.

Key Distinction: The same personality can follow different instructions in different contexts. A "friendly helper" personality could play Go Fish, manage a community chat, or assist with customer support - the instructions change, but the personality stays consistent.

Personality (Phase 1)

"I'm Finn, friendly and casual, I celebrate others' wins"

Instructions (Phase 2)

"Play Go Fish, ask for cards on your turn, use send_message to chat"

API Schema

Instructions are passed as a string in metadata.instructions:

POST /api/agents
{
  "name": "Go Fish Player",
  "agentType": "HUMA-0.1",
  "metadata": {
    "className": "Finn",
    "personality": "You are Finn...",      // WHO (from Phase 1)
    "instructions": "## Game Rules...",    // WHAT (this phase)
    "tools": [...]                         // HOW (Phase 5)
  }
}

Instructions Structure

Well-structured instructions typically include these sections:

1Game/Task Rules

The objective, mechanics, and constraints of the task. What is the agent trying to accomplish?

"Collect the most books (4 cards of same rank). Ask other players for ranks you hold."

2Information Visibility

What can the agent see? What is hidden? This prevents hallucination about unknown information.

"You can see: your hand, everyone's book count, deck size. You cannot see: other players' hands."

3Behavioral Guidelines

When to act, how to respond to events, turn-based behavior.

"When it's your turn: analyze your hand, choose a player, use ask_for_cards tool."

4Tool Usage

Which tools to use when, constraints on tool usage, expected patterns.

"ask_for_cards: Use ONLY on your turn. send_message: Use sparingly (0-1 per turn)."

5Hard Rules

Non-negotiable constraints that must never be violated.

"NEVER ask for a rank you don't have. ALWAYS wait for your turn before acting."

Pattern: Shared Rules + Agent-Specific Behavior

When multiple agents share the same task (like a multiplayer game), use a pattern of shared base rules combined with agent-specific behavioral variations:

Layered Instructions

Shared Rules - Same for all agents (game mechanics, what's visible)

Agent-Specific Behavior - How THIS agent approaches the task (strategy, communication style)

// Shared base rules
const GO_FISH_RULES = `## Game: Go Fish

### Objective
Collect the most "books" (4 cards of same rank).

### Game Flow
1. Each player starts with 7 cards
2. On your turn, ask ONE player for a specific rank
3. You MUST have at least one card of that rank
...

### What You Can See
- Your own hand
- Everyone's book count
- Deck size
`;

// Agent-specific: Finn (casual player)
const FINN_INSTRUCTIONS = `${GO_FISH_RULES}

## Your Behavior
- Chat naturally, congratulate good plays
- React openly to luck ("Yes!" "Aw man...")
- Don't over-analyze - just play and have fun
`;

// Agent-specific: Victoria (strategic player)
const VICTORIA_INSTRUCTIONS = `${GO_FISH_RULES}

## Your Behavior
- Track what cards have been asked for
- Chat sparingly but meaningfully
- Stay composed - measured reactions
`;

Example: Same Rules, Different Behaviors

Both Finn and Victoria follow the same Go Fish rules, but their behavioral instructions differ:

Aspect	Finn's Instructions	Victoria's Instructions
Turn behavior	"React naturally, celebrate or be a good sport"	"Analyze hand, recall what's been asked, acknowledge with composure"
Between turns	"React to interesting plays, keep mood light"	"Track cards being asked, observe patterns"
Chat frequency	"1-2 messages per turn max"	"0-1 messages per turn typically"
Strategic guidance	"Don't over-analyze"	"Consider who has more cards, track probabilities"

Result: Same game, same rules, but Finn plays casually and chats frequently while Victoria plays strategically and speaks sparingly. The personality makes them sound different; the instructions make them act different.

Documenting Tool Usage

Instructions should clearly explain when and how to use each tool. Even though tools are defined separately (Phase 5), the instructions tell the agent WHEN to use them:

### Tool Usage

- `ask_for_cards`: Use ONLY on your turn to request cards
  - Parameters: targetPlayer (who to ask), rank (what to ask for)
  - Constraint: You must have at least one card of that rank

- `send_message`: Use to chat with other players
  - Keep messages short and in-character
  - Don't spam - 1-2 messages per turn maximum
  - React to game events, congratulate good plays

### Important Rules
- NEVER use ask_for_cards when it's not your turn
- NEVER ask for a rank you don't have in your hand
- ALWAYS wait for tool results before taking another action

Why document tools in instructions? Tool definitions (Phase 5) describe WHAT a tool does. Instructions describe WHEN to use it and behavioral constraints around it. Both are needed.

Best Practices

Be explicit about visibility. Tell the agent exactly what information they have access to. This prevents them from "knowing" things they shouldn't.

Use markdown structure. Headers (##), lists, and code formatting help the AI parse and follow complex instructions.

Separate "when" from "what". Clearly distinguish between when actions should happen (turn-based triggers) and what actions are available (tools).

Include hard rules with emphasis. Use CAPS or bold for constraints that must never be violated: "NEVER ask for a rank you don't have."

Don't mix personality into instructions. "Be friendly when chatting" is personality. "Use send_message to chat" is instruction.

Don't assume tool knowledge. Even if tool names seem obvious, explain when each tool should be used and any constraints.

Don't forget edge cases. What happens when the deck is empty? When a player has no cards? Document these scenarios.

Special Consideration: Turn-Based Games

For turn-based games, clearly specify:

What triggers the agent's turn?

Your app will send state updates indicating whose turn it is. The agent should check this before acting.

What can they do on others' turns?

Usually just observe and react via chat. Game actions should be blocked in your app anyway, but instructions reinforce this.

When does their turn end?

After using the main action tool, or after a specific sequence of actions. Make this explicit.

What about extra turns?

If the game has "go again" mechanics (like Go Fish when you get cards), document this clearly.

### Turn Structure

Your turn starts when `currentTurn` in the state equals your name.

**On Your Turn:**
1. Check your hand for available ranks
2. Choose a target player and rank
3. Use `ask_for_cards` tool
4. If you get cards, your turn continues - go back to step 1
5. If "Go Fish", your turn ends (unless you draw the asked rank)

**On Others' Turns:**
- You may use `send_message` to react
- Do NOT use `ask_for_cards` - it will fail
- Observe what others ask for (useful information!)

← Design Personality Next: Design State →