Graph Export

Draw an Agent, Team, or Flow before it runs — Mermaid or JSON, no LLM call

Graph Export draws the shape of your agents before anything runs, so you can review it without paying for an LLM call.

python
from praisonaiagents import Agent
from praisonaiagents.workflows.diagram import to_graph, graph_to_mermaid

agent = Agent(name="Writer", instructions="Write a short poem.")
print(graph_to_mermaid(to_graph(agent)))
Diagram

Graph Export

📋 Definition

🧩 to_graph

🖼️ Mermaid

📦 JSON

Quick Start

  1. Team to Mermaid

    Print a team’s diagram with team.to_mermaid().

    python
    from praisonaiagents import Agent, Task, AgentTeam
    
    researcher = Agent(name="Researcher", instructions="Find facts.")
    writer = Agent(name="Writer", instructions="Draft a blog post.")
    
    team = AgentTeam(
        agents=[researcher, writer],
        tasks=[
            Task(name="research", description="Research AI agents", agent=researcher, expected_output="Notes"),
            Task(name="write", description="Write a blog post", agent=writer, expected_output="Post"),
        ],
    )
    
    print(team.to_mermaid())
  2. Flow to Mermaid

    Print a flow’s diagram with flow.to_mermaid() — the output is unchanged from earlier versions (see Workflow Diagram).

    python
    from praisonaiagents import Agent, AgentFlow
    
    researcher = Agent(name="Researcher", instructions="Find facts.")
    writer = Agent(name="Writer", instructions="Draft a blog post.")
    
    flow = AgentFlow(name="blog", steps=[researcher, writer])
    print(flow.to_mermaid())
  3. Graph data (JSON)

    Get the same structure as a plain dict with .to_graph().

    python
    import json
    from praisonaiagents import Agent, AgentFlow
    
    flow = AgentFlow(name="blog", steps=[Agent(name="Writer", instructions="Draft a blog post.")])
    graph = flow.to_graph()
    
    print(graph["schema"])                 # praisonai.graph/1
    print(json.dumps(graph, indent=2))

How It Works

The builder walks your definition and emits nodes and edges with stable ids.

Diagram
Mermaid / JSONto_graphAgentTeamYouMermaid / JSONto_graphAgentTeamYoudefine agents + tasksto_graph() / to_mermaid()walk definitionnodes + edges (no LLM call)diagram or dict

The graph dict has six keys: schema, kind (agent, team or flow), name, process, nodes and edges.

Node kindId formExample
Agentagent:<name>agent:Researcher
Tasktask:<name or index>task:research
Stepstep:<name>step:draft
Tooltool:<agent>/<tool>tool:Researcher/search_web
Human reviewhuman:youfixed
Managermanager:Managerfixed (hierarchical process)
Start / Endstart:begin / end:donefixed
Duplicate names<base>#2, <base>#3step:draft#2

Ids come from names and positions only, so they are identical across processes and runs. Flow patterns Route, Parallel, Loop, Repeat, If, Include and Discussion are drawn as groups.


Reference

Function / MethodReturnsNotes
to_graph(obj)dictWorks on Agent, AgentTeam, AgentFlow
graph_to_mermaid(graph)strRenders a graph dict as Mermaid graph TD
GRAPH_SCHEMA"praisonai.graph/1"Schema version constant
AgentTeam.to_graph()dictTeam graph data
AgentTeam.to_mermaid()strTeam diagram
AgentFlow.to_graph()dictFlow graph data
AgentFlow.to_mermaid()strFlow diagram, same output as before

to_graph, graph_to_mermaid and GRAPH_SCHEMA import from praisonaiagents.workflows.diagram.


Common Patterns

Review before a run

Check the shape of a team before the first LLM call.

python
from praisonaiagents import Agent, Task, AgentTeam

writer = Agent(name="Writer", instructions="Draft a blog post.")
team = AgentTeam(agents=[writer], tasks=[Task(description="Write a post", agent=writer, expected_output="Post")])

print(team.to_mermaid())   # review, then team.start()

Embed in a README

GitHub renders Mermaid inline, so wrap the output in a mermaid code fence.

python
from praisonaiagents import Agent, AgentFlow

flow = AgentFlow(name="blog", steps=[Agent(name="Writer", instructions="Draft a blog post.")])

fence = "`" * 3

with open("FLOW.md", "w") as f:
    f.write(f"{fence}mermaid\n{flow.to_mermaid()}\n{fence}\n")

Line up replay events with graph nodes

Replay events carry a node_id that matches a graph node id.

python
from praisonaiagents import Agent, Task, AgentTeam
from praisonai.replay import ContextTraceReader

writer = Agent(name="Writer", instructions="Draft a blog post.")
team = AgentTeam(agents=[writer], tasks=[Task(name="write", description="Write a post", agent=writer, expected_output="Post")])

by_id = {node["id"]: node for node in team.to_graph()["nodes"]}

for event in ContextTraceReader("my-session"):
    if event.node_id in by_id:
        print(event.event_type.value, "→", by_id[event.node_id]["label"])

Feed another renderer

Export JSON and draw it with any graph tool.

python
import json
from praisonaiagents import Agent
from praisonaiagents.workflows.diagram import to_graph

agent = Agent(name="Writer", instructions="Write a short poem.")

with open("graph.json", "w") as f:
    json.dump(to_graph(agent), f, indent=2)

Best Practices

Preview before you pay

Call .to_mermaid() to check a team or flow before the first LLM call.

Persist node ids freely

Node ids are stable across runs, so your own tooling can store and reuse them.

Start custom rendering from the dict

Use .to_graph() for custom views — it carries agents, tools and pattern groups the Mermaid string may not show.

Name your tasks and steps

Named tasks give readable ids like task:research; unnamed ones fall back to their position.


Related