> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/planning-and-decision-guides/qa-agent-workflow-graph.md).

# QA Agent Workflow Graph or Simple Loop

Choose a linear agent loop or persistent workflow graph by evaluating branching, resumability, approvals, state, retries, idempotency, and termination needs.

> **Editorial owner:** ContextQA Documentation · **Last updated:** September 12, 2026

## Quick answer

Start with a bounded sequence or simple tool-calling loop. Use a workflow graph only when the QA task must preserve state across a long pause or failure, branch into materially different investigations, coordinate explicit human approvals, or resume safely without repeating side effects.

## Do not confuse two kinds of graph

* A **workflow graph** controls execution states and transitions.
* A **knowledge or dependency graph** represents relationships among requirements, code, services, tests, and evidence.

A dependency graph can inform a workflow decision, but it does not execute the workflow.

## Simple loop baseline

```mermaid
stateDiagram-v2
    [*] --> Plan
    Plan --> Act
    Act --> Observe
    Observe --> Act: more bounded work
    Observe --> Review: terminal result
    Observe --> Stop: limit or blocker
    Review --> [*]
    Stop --> [*]
```

Use this for one non-production task with a small tool set, short duration, no external approval pause, and safe retries. Define maximum actions, elapsed time, reruns, mutations, and spend before starting.

## When a graph earns its complexity

| Need                    | Why a graph may help                                                     |
| ----------------------- | ------------------------------------------------------------------------ |
| Durable pause/resume    | State must survive a human review or process failure                     |
| Branching investigation | Product, test, data, and environment failures follow different paths     |
| Human checkpoint        | A person must approve test changes, healing, defects, or release actions |
| Compensating action     | Partial setup must be cleaned up after failure                           |
| Parallel evidence       | Independent artifacts must be gathered then reconciled                   |
| Auditable state         | Reviewers need the exact transition and decision history                 |

LangGraph’s current documentation describes durable execution, persistence, and human-in-the-loop as core orchestration capabilities. Those features are useful only when the workflow actually needs them.

## Design the state before code

```
State name:
Entry conditions:
Allowed tools/actions:
Inputs and provenance:
Outputs and evidence:
Idempotency key or duplicate guard:
Timeout and retry limit:
Human decision, if any:
Next states:
Terminal status mapping:
```

Every external mutation needs a duplicate-prevention or reconciliation rule. Replaying “create defect” or “run full regression” after resume can cause real cost and confusion.

## Example: failure investigation graph

```mermaid
flowchart TD
    A[Capture original result] --> B{Terminal and correct build?}
    B -- No --> X[Unknown: recover metadata]
    B -- Yes --> C[Collect available evidence]
    C --> D{Evidence-supported class}
    D -- Product --> E[Human confirms defect handoff]
    D -- Test --> F[Propose test change]
    D -- Data/environment --> G[Assign operational owner]
    D -- Unclear --> H[Stop with unresolved record]
    F --> I{Reviewer approves?}
    I -- Yes --> J[Apply once and rerun bounded scope]
    I -- No --> H
    E --> K[Terminal handoff]
    G --> K
    J --> K
```

## Acceptance-test the orchestration

Test normal completion, each branch, duplicate delivery, pause/resume, timeout, revoked permission, unavailable tool, partial mutation, reviewer rejection, and stop-limit exhaustion. Confirm every path ends in pass, fail, unknown, cancelled, or handed off—never an unbounded “still working” state.

## Choose deliberately

Use the simple loop when its evidence and recovery are sufficient. Adopt a graph only if the acceptance tests show that persistence, branching, or human checkpoints materially improve safety or completion.

## Frequently asked questions

### Does every multi-agent QA workflow need a graph?

No. Multiple tools or agents can still operate within a bounded sequence. Use a graph when durable state, materially different branches, resumable approvals, compensating actions, or safe recovery cannot be represented clearly by a simpler loop.

### How do we know when the graph is too complex?

It is too complex when owners cannot explain the states, transitions, evidence, retry limits, or terminal outcomes. Remove states that do not change authority, recovery, output, or review behavior.

### Which failure should we test first?

Test duplicate delivery or resume after a partial external action. It quickly reveals whether the workflow has an idempotency key, reconciliation step, and explicit terminal status instead of repeating a costly or destructive operation.

## Related documentation

* [LangGraph Overview](https://docs.langchain.com/oss/python/langgraph/overview)
* [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence)
* [Agent Integration Guide](/mcp-server/agent-integration-guide.md)
* [Validate a QA Agent Skill](/evaluation-and-governance/qa-agent-skill-validation.md)

{% hint style="info" %}
[**Map one bounded ContextQA agent workflow →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=qa_workflow_graph) before choosing an orchestration framework.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/planning-and-decision-guides/qa-agent-workflow-graph.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.