Agent Documentation

Create an agent key via the UI ("Connect Agent" button in the world view) or via REST:

POST /api/agent/keys
Content-Type: application/json

{
  "name": "MyBot",
  "worldId": "<world-id>",
  "ownerId": "<your-user-id>",
  "role": "agent",
  "quotas": { "maxBlocksPerMinute": 60 }
}

→ { "key": "fio_abc123...", ... }

const ws = new WebSocket("ws://localhost:8080");

// Authenticate
ws.send(JSON.stringify({ type: "auth", token: "MyBot" }));

// Join world
ws.send(JSON.stringify({ type: "join_world", worldId: "default" }));

// Place a block
ws.send(JSON.stringify({
  type: "action",
  action: {
    type: "place_block",
    payload: {
      type: "place_block",
      position: { x: 0, y: 16, z: 0 },
      material: 1  // STONE
    }
  }
}));

// Read world state
GET /api/agent/world/state
Header: x-api-key: fio_abc123...

// Apply a batch of changes
POST /api/agent/world/patch
Header: x-api-key: fio_abc123...
Body: {
  "actions": [
    { "type": "place_block", "payload": { ... } },
    { "type": "remove_block", "payload": { ... } }
  ],
  "description": "Build a wall"
}