Decision-PGA Agent Toolkit

This page is the practical companion to the article and demo. It is for developers asking: “How would I actually try this in an agent workflow?”

Imagine an agent that can answer, ask a clarifying question, retrieve more evidence, route to review, abstain, or replan. A confidence score can say that the situation is uncertain. Decision-PGA asks a more workflow-shaped question: what kind of uncertainty is it?

The prototype accepts repeated probability-like observations over a fixed set of candidate actions, then returns a compact decision-state readout. It is local, deterministic, and model-neutral. It is not a production safety layer or a claim that an answer is correct.

Open full toolkit docs View code Try visual demo

Use Decision-PGA in five minutes

git clone https://github.com/zmichels/Decision-PGA.git
cd Decision-PGA
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[mcp]"
decision-pga diagnose --pretty examples/agent/tool_action_ambiguity.json

Launch the local MCP server:

decision-pga-mcp

Inspect it with MCP Inspector:

npx @modelcontextprotocol/inspector decision-pga-mcp

Diagnostic Payload Gallery

Each gallery item below mirrors a copy-paste JSON payload in the public repo. The examples are synthetic, but the situations are meant to feel familiar to agent builders. The point is to see how similar-looking uncertainty can call for different next actions.

Tool/action ambiguity

A support agent is split between searching documentation and querying an internal database before answering. The useful move is to resolve that tool path, not treat the case as generic low confidence.

Expected state: binary_ambiguity
Example: tool_action_ambiguity.json

RAG evidence conflict

Two retrieved snippets support incompatible answer paths. Decision-PGA can preserve the fact that uncertainty is concentrated between two evidence routes, which is different from missing all evidence.

Expected state: binary_ambiguity
Example: rag_evidence_conflict.json

Document extraction routing

The workflow sees weak support for several routes because a referenced attachment or source page is missing. The practical next action is to retrieve more context, not ask a narrow two-choice question.

Expected state: diffuse_uncertainty
Example: document_extraction_routing.json

Multi-step agent drift

Early trajectory windows prefer retrieval, while later windows prefer drafting. The trace should be segmented or replanned instead of averaged into one static decision state.

Expected state: regime_shift
Example: multi_step_agent_drift.json

Stable abstain decision

Abstention can be the stable top action. In that case, proceed means proceed with the abstain route, not answer anyway.

Expected state: stable
Example: abstain_defer_decision.json

What to look for

The key comparison is not “certain versus uncertain.” It is the shape of the uncertainty:

tight clouds suggest the workflow can continue with the top action;
line-shaped clouds suggest a focused two-choice ambiguity;
broad clouds suggest missing or inadequate context;
boundary-sensitive clouds deserve threshold or policy review;
drifting clouds suggest segmentation or replanning.

For implementation details, see the full agent toolkit docs and the MCP quickstart.