Feature Request: Visualize Agent Planning Graph for Better Readability and Maintainability

[anton-zom-ra]

Feature Request: Visualize Agent Planning Graph for Better Readability and Maintainability

Problem

Embabel's GOAP/planning model is powerful, but as an agent grows, it becomes difficult for someone who did not originally write the code to understand the overall behavior of the agent.

A significant part of the control flow is implicit and distributed across:

• @Action input/output types
• pre
• post
• @Condition
• Goals
• Blackboard state
• Planner decisions and replanning

For example:

@Action(
    cost = 0.10d,
    post = {"fraudSuspected", "fraudCleared"}
)
public FraudScore assessFraud(...) {
    ...
}

@Condition(name = "fraudSuspected")
public boolean fraudSuspectedCondition(FraudScore fraudScore) {
    return fraudScore.probability() > 0.65;
}

@Action(pre = {"fraudSuspected"})
public Investigation investigate(FraudScore fraudScore) {
    ...
}

The relationship is conceptually simple:

assessFraud
    |
    v
FraudScore
    |
    v
fraudSuspected
    |
    v
investigate

However, this relationship is not obvious from any single place in the source code.

The @Condition may be defined in one class, referenced as a post condition by another action, and consumed as a pre condition by another action elsewhere.

The same issue also exists for dependencies inferred from Java method parameters and return types.

As a result, Embabel provides good local readability at the individual Action level, but the global readability of an Agent can become difficult as complexity increases.

Why this matters

For the original author, the implicit planning model is usually understandable because they already know the intended graph.

For other developers, however, understanding an Agent may require:

1. Finding all @Action methods
2. Finding all @Condition methods
3. Searching for every pre / post reference
4. Inferring dependencies from method argument and return types
5. Finding Goals
6. Mentally reconstructing the resulting planning graph

This becomes particularly difficult during:

• code reviews
• onboarding new developers
• debugging unexpected planner behavior
• maintaining large Agents
• understanding why an Action is reachable or unreachable
• identifying possible planning paths

Proposal

It would be very useful if Embabel could expose a static Agent Planning Graph derived from the registered Agent metadata.

For example:

Claim
 |
 v
assessFraud
 |
 v
FraudScore
 |
 +-------------------+
 |                   |
 v                   v
fraudSuspected   fraudCleared
 |                   |
 v                   v
investigate        approve
 |                   |
 +---------+---------+
           |
           v
          Goal

Ideally the graph could include:

• Actions
• Action cost
• Action inputs
• Action outputs
• Preconditions
• Postconditions
• Conditions
• Goals
• Domain types

Possible Outputs

Even a simple machine-readable or text-based representation would be useful.

For example:

Mermaid

flowchart LR

Claim --> AssessFraud
AssessFraud --> FraudScore

FraudScore --> FraudSuspected
FraudScore --> FraudCleared

FraudSuspected --> Investigation
FraudCleared --> Approval

Loading

Graphviz DOT

digraph Agent {
    Claim -> AssessFraud;
    AssessFraud -> FraudScore;
    FraudScore -> FraudSuspected;
    FraudScore -> FraudCleared;
    FraudSuspected -> Investigation;
    FraudCleared -> Approval;
}

Possible APIs could be something similar to:

agent.getPlanningGraph();

or

planningSystem.exportGraph(GraphFormat.MERMAID);

or an actuator/dev endpoint such as:

/actuator/embabel/agents/{agentName}/graph

A UI would be great, but even exporting the underlying graph model would allow IDE plugins and external visualization tools to be built.

Runtime View

A second, complementary feature could visualize the current plan during execution.

For example:

fraudSuspected = true
fraudCleared   = false

assessFraud ✓
     |
     v
fraudSuspected ✓
     |
     v
investigate
     |
     v
manualReview

This would be different from the static Agent graph:

• Static graph: What paths can this Agent theoretically take?
• Current plan: What path is the Planner currently considering?
• Execution trace: What path did this execution actually take?

Embabel already has strong concepts around planning and replanning, so exposing these three views could significantly improve observability and developer experience.

Summary

The planning abstraction is one of Embabel's strengths, but it also moves control flow away from explicit Java code.

As Agents become larger, I think having a first-class way to inspect or visualize the resulting planning graph would make Embabel significantly easier to:

• understand
• debug
• review
• maintain
• onboard developers onto

Would a planning graph/introspection API be something that fits the project's roadmap?

[igordayen]

@anton-zom-ra, @johnsonr - thank you.

Anton, good idea. I would rather frame it as a discussion than an issue. Discussions will go through the planning phase.
Let me know if you are OK to convert it into a discussion.
Thanks

[anton-zom-ra]

@anton-zom-ra, @johnsonr - thank you.

Anton, good idea. I would rather frame it as a discussion than an issue. Discussions will go through the planning phase. Let me know if you are OK to convert it into a discussion. Thanks

yes，that's ok, please

[igordayen]

@anton-zom-ra - converted into a discussion as agreed.