Skip to content

First useful result

AgentLoop has two orchestration commands for people who do not yet need the lower-level workflow. For existing OTLP/OpenInference telemetry or a client already used by your application, the onboarding path adds capture validation and an explicit SDK startup helper before these analysis steps.

For classifiers, rules and decision pipelines, see the AI execution profiling guide. Its workflow APIs are included in version 0.1.0; run the reference examples from a source checkout.

1. Verify the install without an account or API key

agentloop quickstart

quickstart creates a deterministic synthetic trace locally, analyzes it, and prints several concrete findings. It does not use a network connection, model provider, account, API key, database, or paid API.

The trace is written to:

runs/agentloop_quickstart.json

You can choose another path:

agentloop quickstart --out /tmp/agentloop-example.json

For the combined machine-readable report:

agentloop quickstart --json-out runs/quickstart_analysis.json

The trace is marked with:

{
  "synthetic": true,
  "source": "agentloop_quickstart"
}

so it cannot be confused with production evidence.

2. Analyze one real trace

After instrumenting an agent and exporting a trace:

agentloop analyze runs/my_agent.json

This one command combines the existing report, diagnosis, and optimization analysis and prints the most useful findings first.

For an offline report you can open in a browser or attach to a review:

agentloop analyze runs/my_agent.json --html runs/my_agent_report.html

See HTML reports for baseline comparisons, content controls, and CI artifacts.

To retain the complete structured output:

agentloop analyze runs/my_agent.json --json-out runs/my_agent_analysis.json

The JSON contains four sections:

  • trace: the validated native trace;
  • report: measured runtime, token, call, retry, and cost information;
  • diagnosis: evidence-backed findings;
  • optimization: rewrite opportunities and savings-selection metadata.

3. Move to proof

analyze is for finding a problem. Once you change the agent, compare the before and after runs:

agentloop replay \
  --baseline runs/baseline.json \
  --candidate runs/candidate.json

Add quality fixtures when faster or cheaper is not sufficient evidence by itself:

agentloop replay \
  --baseline runs/baseline.json \
  --candidate runs/candidate.json \
  --quality-fixtures evaluation/fixtures.json \
  --min-quality-score 0.9

For pull-request gating, use the same inputs with agentloop ci.

Keep source traces and fixtures separate from report destinations. CLI analysis and report commands reject overlapping input/output files and report formats before writing, including symlink and hard-link aliases. An existing report can be regenerated at its own output path.

analyze reports comparison failures for inspection and does not enforce gates. Use replay, quality-report, or ci when failure must produce exit code 1. Invalid arguments, including conflicting paths, produce exit code 2.

Advanced commands remain available

quickstart and analyze orchestrate existing AgentLoop capabilities. They do not replace the lower-level commands. Use report, diagnose, optimize, patch, replay, quality-report, ci, store commands, and API commands when you need control over one stage of the workflow.