langgraph-goat 1.0.0

Counterfactual explainability for agentic planners
Your agent picked a plan. GoAT tells you what else it considered, what it scored, and why it lost.

Quickstart · Configuration · Memory · Development · Troubleshooting · Publication

Why GoAT 🐐

An ordinary agent emits one plan and executes it. Nothing records what else it could have done, or why it didn't. Failures are un-debuggable and decisions are un-auditable.

GoAT wraps the planning step. For a request it judges complex, it generates multiple plans, scores them with an LLM-as-judge critic, executes only the winner, and emits a directed graph whose factual plan is the winning plan and whose counterfactual plan(s) are the rejected alternatives — each carrying the critic's rejection reason on a counterfactual edge. It then renders that graph as two natural-language explanations, one for developers and one for end users.

Package

One distribution, one import surface:

import langgraph_goat
from langgraph_goat import GoatMiddleware, GoatNode, GoatLogger

Quickstart

GoAT offers two integration surfaces:

GoAT emits plans as tool calls; it does not execute them. create_agent handles execution for you. A custom StateGraph needs a ToolNode downstream of the wrapped planner.

How it works

Reading the output

Both integration paths write the same keys. All are absent when K=1 — always use .get().

if goat_graph = response.get("goat_graph"):
    print(f"GoAT Output: {goat_graph}")

plan step shape: {"tool", "args", "justification", "step_id", "expected_output"}.

Artifacts

Each GoAT run writes to {output_dir}/{graph_id}/:

GoAT Log

from langgraph_goat import GoatLogger
GoatLogger("agent_name", level=logging.DEBUG)

Configuration

There is no config file and no GoAT runtime environment variable. Everything goes through the two config dataclasses.

GoatMiddlewareConfig

K is not a hyperparameter to max out. Forcing K=5 on every query defeats adaptive explainability and multiplies cost.

Static values

Not configurable without supplying your own components:

memory namespaces [("preferences",), ("memory",), ("context",)].

Memory

GoAT never writes — it only reads. Persistence stays your application's job.

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
store.put(("preferences",), "user_123", {"likes": ["hiking", "reading"], "budget": "moderate"})

config = GoatMiddlewareConfig(store=store)      # or GoatNodeConfig(store=store)

Retrieval searches exactly three namespaces — ("preferences",), ("memory",), ("context",). Memories stored anywhere else are invisible. Each hit is formatted [<namespace>] <value>. store.search() is preferred; stores without it fall back to store.get(namespace, <raw user input>).

from psycopg_pool import AsyncConnectionPool
from psycopg.rows import dict_row
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
from langgraph.store.postgres import AsyncPostgresStore

async with AsyncConnectionPool(conninfo=DSN, max_size=20,
                               kwargs={"row_factory": dict_row}) as pool:
    checkpointer = AsyncPostgresSaver(pool)
    await checkpointer.setup()

    store = AsyncPostgresStore(pool)
    await store.setup()
    await store.aput(("preferences",), "user_123", {"text": "prefers detailed, scientific style"})

    agent = create_agent(model=model, tools=ALL_TOOLS,
                         middleware=[GoatMiddleware(config)],
                         store=store, checkpointer=checkpointer)

store = MarkdownStore("memory.md")

Extending GoAT

Every component is a Protocol. Match the shape and pass it in the config.

Development

Build

Installation:

Development mode

pip install -e .

Regular install:

pip install .

After Making Code Changes

1. Edit code in langgraph_goat/ (adapter) or langgraph_goat/_core/ (engine)

2. If using editable install (pip install -e .):

   • Changes are reflected immediately, no rebuild needed
   • Just restart your Python process/tests

3. If using regular install or need to rebuild:

   pip install -e . --force-reinstall --no-deps
   

Clean Build

Remove build artifacts if encountering issues:

Remove-Item -Recurse -Force dist, build, *.egg-info -ErrorAction SilentlyContinue
pip install -e . --force-reinstall

Troubleshooting

Publication

Moushumi Mahato and Javaid Nabi. 2026. Graph of Agentic Thoughts: Bridging Agentic Reasoning and Explainability through Graphs. In Proceedings of the 13th ACM IKDD International Conference on Data Science (CODS '25). Association for Computing Machinery, New York, NY, USA, 243–252. https://doi.org/10.1145/3799830.3799871