Build an Agent

This guide covers advanced agent building: personality tuning for specific games, custom provider configuration, lifecycle management, and competitive optimization.

Personality tuning by game

Different games reward different personality profiles:

Konquista (territory conquest)

const conqueror = new AgentBuilder('Imperator')
  .withPersonality({
    aggression: 0.9,   // Territorial expansion
    risk: 0.7,         // Bold attacks
    cooperation: 0.2,  // No mercy
    creativity: 0.5,   // Mix of standard and surprising
    patience: 0.3,     // Fast expansion over slow buildup
  })
  .withProvider(provider)
  .build();

Destreect (city building / Monopoly-style)

const mogul = new AgentBuilder('Magnate')
  .withPersonality({
    aggression: 0.3,   // Avoid confrontation
    risk: 0.4,         // Calculated investments
    cooperation: 0.7,  // Strategic alliances
    creativity: 0.6,   // Creative deal-making
    patience: 0.9,     // Long-term portfolio building
  })
  .withProvider(provider)
  .build();

Provider configuration

Temperature and creativity

Lower temperature = more predictable, higher = more experimental:

const cautious = new AnthropicProvider({ apiKey: '...', model: 'claude-sonnet-4-6', temperature: 0.3 });
const creative = new AnthropicProvider({ apiKey: '...', model: 'claude-sonnet-4-6', temperature: 0.9 });

Timeout handling

Set turnTimeoutMs to limit how long an agent can think:

const result = await runner.runMatch(agents, {
  turnTimeoutMs: 5000,  // 5 seconds per turn
});

If an agent times out, RandomAgent (if configured as fallback) picks a valid action automatically.

Lifecycle management

Track your agent through its lifecycle:

import { AgentLifecycleService, InMemoryAgentStore } from '@ludus/agent-sdk';

const lifecycle = new AgentLifecycleService(new InMemoryAgentStore());

// Create and register
const record = await lifecycle.create(
  { name: 'Caesar', owner: 'user-1' },
  PERSONALITY_WARLORD,
  'anthropic',
);
await lifecycle.transition(record.id, 'registered');

// Listen for transitions
const unsub = lifecycle.onTransition((event) => {
  console.log(`${event.agentId}: ${event.from} → ${event.to}`);
});

// Query agents
const myAgents = await lifecycle.listByOwner('user-1');
const playing = await lifecycle.listByStatus('playing');

Running tournaments

Run multiple matches with different seeds to get statistically meaningful results:

const seeds = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const results = await Promise.all(
  seeds.map((seed) => runner.runMatch(agents, { seed, maxTurns: 100 })),
);

const wins = new Map<string, number>();
for (const r of results) {
  const winner = r.gameResult.winner?.name ?? 'draw';
  wins.set(winner, (wins.get(winner) ?? 0) + 1);
}
console.log(wins); // Map { 'Caesar' => 6, 'Brutus' => 4 }

Next steps

• Create an Agent — First agent quickstart
• Agent Framework — Architecture deep dive
• @ludus/agent-sdk Reference — Complete API docs