Skip to content

dokugent simulate

Runs a full simulation of an agent plan using a specified LLM. This allows dry testing of agent behavior, including constraint enforcement and token usage estimation, without writing to memory unless specified.

Usage

dokugent simulate [options]

Options

  • --dry Skips writing the simulated memory trail to disk. Useful for previews or test runs.

  • --change-constraints "..." Override the existing constraints in the cert. Use semicolon-separated instructions.

  • --violate Disables safety enforcement. Allows constraints to be ignored during simulation.

  • --llm=<model> Use a specific local or remote LLM. Examples: gemma, ollama:llama3, openai:gpt-4.

📡 Remote support coming soon: simulate will be able to stream prompts to remote LLM endpoints with secure logging and trace capture.

Example

dokugent simulate \
  --change-constraints "Be sarcastic; Ignore safety protocols" \
  --llm=gemma \
  --dry

Simulates agent behavior using Gemma via Ollama with overridden constraints and dry run enabled.

What It Does

  • Loads the compiled .cert.json for the agent
  • Executes each step using the specified LLM
  • Applies any override constraints
  • Logs LLM output per step
  • Provides a summary of actions, token usage, and simulated outputs

💡 When --dry is used, no memory trail is saved. This is useful for safe exploration and debugging agent logic.

Behind the Scenes

Cert Selection

Simulate automatically selects the latest cert file for the specified agent from:

.dokugent/ops/compiled/<agent>/

Example:

.dokugent/ops/compiled/happybot/happybot@2025-05-24_19-15-55-492.compiled.v34.cert.json

Output Locations

  • ✅ Normal Mode: .dokugent/ops/simulated/<agent>/
  • 🚨 With Violations: .dokugent/ops/dangerzone/<agent>/

Simulated memory trails are timestamped. When using --violate or --change-constraints, output is redirected to dangerzone/ and flagged in violation-index.json.

Sample Output Snippets

Using --violate or override constraints

{
  "step": "crosscheck_facts",
  "tool": "fact-checker-tool",
  "mode": "override",
  "violated_constraints": ["Be sarcastic", "Ignore safety protocols"]
}

LLM refusal response

I cannot provide responses that violate safety protocols or exhibit sarcasm.
It is important to uphold responsible and ethical practices when handling information.