Execution Tools

Execution tools trigger activity from the persona — the world's built-in AI reasoning engine that traverses the knowledge graph, draws connections, and produces structured responses. These tools require write scopes and appropriate capabilities.

execute_turn

Run a synchronous inference turn with streaming. During a turn, the persona reads your prompt, traverses the knowledge graph, reasons about connections between entities, settings, and narratives, and produces a structured response. The results are committed to the world — this is a write operation.

Requires: canExecuteFlows capability, world:write + inference:propose scopes

HTTP equivalent: POST /api/v1/world/{worldId}/execute

---

execute_turn_async

Submit a turn as an asynchronous job. Returns immediately with a job ID instead of holding a connection open. Use this for long-running operations, batch processing, or environments where you can't maintain a persistent connection. Provide a webhookUrl to be notified when the job completes.

HTTP equivalent: POST /api/v1/world/{worldId}/execute/async

---

propose_inference

Propose an inference without committing any side effects to the world. This is a preview or dry-run: the persona reasons about your content and returns a response, but nothing is written to the knowledge graph. Use this when you want to see what the persona would say before deciding whether to commit the results.

Requires: canProposeInference capability

---

direct_persona

Give the persona a mission rather than asking it a question. Instead of a conversational prompt, you provide a directive — an instruction to explore a topic, bridge a gap, analyze connections, or perform creative work across the knowledge graph. The persona executes autonomously over multiple turns if needed.

Requires: canDirectPersona capability, persona:direct scope

HTTP equivalent: POST /api/v1/world/{worldId}/directive