dokugent trace¶

The dokugent trace command is used to analyze and explain agent behavior. It generates a trace from the agent’s certificate and plan, outputting step-by-step reasoning, token estimates, constraint checks, and logic flow.

Unlike dokugent simulate, which predicts output and next actions, trace focuses on introspective explainability for auditing and debugging purposes.

Usage¶

dokugent trace <doku://agent@timestamp>

Options¶

(No flags currently required. Just pass a valid doku:// URI.)

Example¶

dokugent trace doku://happybot@2025-05-24_19-15-55-492

Output Format¶

The trace command returns the full contents of the certified .doku.json file. If the file contains agent metadata, task plans, constraints, and conventions, all will be included. The example below shows a minimal file with only agent metadata.

{
  "status": "ok",
  "result": {
    "agent": {
      "agentName": "happybot",
      "ecosystem": "nvidia"
    }
  }
}

In future versions, this will expand to include full plan analysis, step-by-step logs, and context deltas.

What It Does¶

dokugent trace provides introspective explainability for certified agent plans. Unlike simulate, it does not run the plan in real-time, but instead reveals:

Trace = inspect behavior | Simulate = run behavior

Step-by-step intent breakdown
Constraint adherence or violations
Token estimates per action
LLM reasoning traces

How It Works¶

Doku URI Resolution¶

When passed a doku://<agent>@<born-timestamp> URI, Dokugent resolves the slug to a secure MCP URL. This lets trace work with remote agents or certified third-party plans.

Remote Fetch & Auth¶

If the URI points to a Supabase-protected resource, dokugent trace uses your API key (or JWT) to authorize the request before downloading the .doku.json.

Note: You must provide a valid SUPABASE_SERVICE_ROLE_KEY in your .env file or pass --token manually. Without this, remote trace will be denied.

Trace Logic Internals¶

Once loaded, the trace runner:

Parses the plan, criteria, and any constraints
Applies mutations from --change-constraints or --violate
Executes LLM-based dry introspection
Produces a memory-safe audit trail

Remote Powered by MCP¶

All trace operations are routed through a secure MCP (Model Context Protocol) server. When you run dokugent trace, the CLI sends:

The resolved dokuUri (points to a compiled agent certificate)
A signed intent token (JWT for authentication)

The MCP endpoint validates, fetches, and parses the agent data before returning a structured response to Dokugent CLI.

Description¶

This command analyzes the reasoning process of an agent by:

Resolving doku://<agent>@<born-timestamp> URIs into remote certificate locations
Applying optional constraint mutations or overrides
Generating a trace file based on what the agent would do
Logging decision-making steps and projected token cost

Use this when you need to:

Explaining agent behavior before execution
Debugging missing context or misaligned plans
Conducting Human-in-the-Loop reviews