TheRock/rocm-systems/experimental/python/perfxpert/docs/archive/migration-to-agentic.md

Migrating to the Agentic Path

Historical — the legacy path has been removed. This document is retained for reference only. New users can disregard PERFXPERT_LEGACY entirely; the agentic runtime is the only path.

---

As of v0.2.0, perfxpert's execution path is the agentic runtime (OpenAI Agents SDK + ~45 deterministic tools + split fence). This is now the only runtime — the pre-v0.2.0 execution path and its opt-in toggle were removed during the agentic refactor, so nothing here is optional.

What changed

Concern	Pre-v0.2.0	Agentic (v0.2.0+)
Interactive TUI	Inline conversational mode on perfxpert analyze	perfxpert-code (bundled AMD-themed opencode)
Session resume	Resume-session flag on perfxpert analyze	opencode sessions (persistent by default)
LLM "fence"	Monolithic reference guide	Per-agent agents/fence/*.md + knowledge YAMLs
Recommendation engine	Rule-based function in analyze.py	Multi-agent (Analysis → Recommendation → Specialists)
Correctness checks	Inline in the interactive-session revert helper	5-gate cascade in runtime/gate_cascade.py
Code edits	WorkflowSession._llm_rewrite_file()	opencode-native edit + MCP verify
Library API	Single-shot LLM call	perfxpert.agents.runtime.build_session() + session.run_root(...)

What stays the same

• perfxpert analyze CLI command (the conversational flags are removed — see below)
• AnalysisResult dataclass and its to_json/markdown/webview methods
• JSON schema (analysis-output.schema.json)
• All --format, --llm, --prompt, --source-dir, -d, -o flags
• ROCm / rocprofv3 integration — we still read .db files and produce reports

If your workflow was...

Conversational mode on perfxpert analyze

→ Switch to perfxpert-code, which uses the default AMD-themed patched opencode path for the conversational TUI. Calls into the same agent runtime as batch mode, just wrapped in a conversational UI.

Conversational mode with session resume

→ Use opencode sessions. perfxpert-code persists sessions in .perfxpert/ by default; see perfxpert-code --list-sessions and perfxpert-code --resume <id>.

Calling the pre-v0.2.0 conversation class

→ Use the current library API:

from perfxpert.agents.runtime import build_session
from perfxpert.agents.schemas import RootInput

session = build_session(airgap=True)  # or provider='anthropic'
output = session.run_root(RootInput(
    user_query="Summarize the primary bottleneck.",
    airgap=True,
))
print(output.primary_bottleneck)

The new API is typed (Pydantic), streams via the SDK, and supports all 5 providers uniformly.

Loading the monolithic reference guide

→ Use from perfxpert.agents.fence import load_fence_slice. Pass the agent name ("root", "analysis", etc.) to get the per-agent fence slice. The monolithic guide was removed during the agentic refactor.

Modifying llm-reference-guide.md to change LLM behavior

→ Edit the relevant agents/fence/*.md slice. Each agent has its own narrow-scope fence (≤ 400 lines enforced by CI). See CONTRIBUTING.md for which file controls which behavior.

I need the old behavior back

There is no runtime toggle. PERFXPERT_LEGACY was removed during the agentic refactor, along with the pre-v0.2.0 code paths it used to gate. To run the old pipeline you must check out a release tag ≤ v0.2.x (see git tag); the pre-rename reference-guide override env var is no longer honored either.

If you hit a behavioral difference between the new runtime and what you expected from the earlier code path, file an issue with:

1. perfxpert doctor output
2. A reproducer DB (minimal fixture preferred)
3. Expected vs actual output

We treat regressions versus documented v0.2.x behavior as bugs in the agentic runtime and aim to close them quickly.

Questions?

See CONTRIBUTING.md for extension surface docs or open an issue.