1
interface AgentState {
2
  // Core attributes
3
  inventory: string[];
4
  skills: Record<string, number>;
5
  relationships: Record<string, number>;  // -100 to 100
6
  
7
  // Emotional state
8
  mood: 'hostile' | 'suspicious' | 'neutral' | 'friendly' | 'loyal';
9
  
10
  // Custom attributes (application-specific)
11
  [key: string]: unknown;
12
}

1
interface AgentResponse {
2
  dialogue: string;           // What the agent says
3
  action?: AgentAction;       // What the agent does
4
  thought?: string;           // Internal reasoning (debug)
5
}

1
import { createAgent, createCortex } from 'forbocai';
2
3
// Initialize Cortex first
4
const cortex = createCortex({ model: 'smollm2-135m' });
5
await cortex.init();
6
7
// Create agent with persona and initial state
8
const merchant = createAgent({
9
  id: 'npc_merchant_001',
10
  cortex,
11
  persona: `You are Kira, a cautious merchant in a dystopian market.
12
            You distrust strangers but can be won over with fair trades.
13
            You speak in short, clipped sentences.`,
14
  initialState: {
15
    inventory: ['rusty_key', 'healing_potion', 'ancient_map'],
16
    mood: 'suspicious',
17
    skills: { bargaining: 0.8, appraisal: 0.9 },
18
    relationships: {}
19
  }
20
});

1
const response = await merchant.process(
2
  "I'd like to buy that key from you.",
3
  { playerGold: 50, playerReputation: 30 }
4
);
5
6
console.log(response.dialogue);
7
// "That key? It's... special. 50 gold and we have a deal."
8
9
console.log(response.action);
10
// { type: 'OFFER_TRADE', item: 'rusty_key', price: 50 }

1
// Get current state (returns a copy)
2
const state = merchant.getState();
3
console.log(state.mood); // 'suspicious'
4
5
// Update state (replaces entire state)
6
merchant.setState({
7
  ...state,
8
  mood: 'friendly',
9
  relationships: { player_1: 25 }
10
});

1
const soul = merchant.export();
2
// Returns: { id, version, name, persona, memories, state }

1
import { fromSoul, createCortex } from 'forbocai';
2
3
// Assume `soulData` was loaded from IPFS or storage
4
const cortex = createCortex({ model: 'smollm2-135m' });
5
await cortex.init();
6
7
const restoredAgent = fromSoul(soulData, cortex);

1
// ✅ Good: Rich personality
2
persona: `You are Marcus, a grizzled blacksmith who lost his family 
3
          in the war. You channel your grief into your craft. 
4
          You speak softly but carry immense strength.`
5
6
// ❌ Bad: Generic
7
persona: `You are a blacksmith NPC.`

1
// ✅ Good: One Cortex, many agents
2
const cortex = createCortex({ model: 'smollm2-135m' });
3
await cortex.init();
4
5
const npc1 = createAgent({ cortex, persona: '...' });
6
const npc2 = createAgent({ cortex, persona: '...' });
7
8
// ❌ Bad: Multiple Cortex instances
9
const npc1 = createAgent({ 
10
  cortex: createCortex({...}), // Wasteful!
11
  persona: '...' 
12
});

1
const state = agent.getState();
2
const playerRelation = state.relationships['player_1'] || 0;
3
4
if (playerRelation > 50) {
5
  // Offer special dialogue options
6
} else if (playerRelation < -50) {
7
  // Refuse to trade
8
}

1
// Agent Configuration
2
interface AgentConfig {
3
  id: string;
4
  cortex: ICortex;
5
  memory?: IMemory;
6
  persona: string;
7
  initialState?: Partial<AgentState>;
8
  apiUrl?: string;
9
}
10
11
// Agent Interface
12
interface IAgent {
13
  process(input: string, context?: Record<string, unknown>): Promise<AgentResponse>;
14
  getState(): AgentState;
15
  setState(newState: AgentState): void;
16
  export(): Soul;
17
}