[PaulAsjes]

Summary

Agent configs refer to tools, tests, knowledge-base documents and other agents by ID only, so a reviewer can't tell which agents a change to tool_configs/x.json affects, or who hands off to whom. agents graph follows those references across every agent and branch in agents.json and draws each agent with what it connects to, in the terminal or as Mermaid. --uses answers the reverse question ("which agents use this tool?") one tab-separated line per reference, for scripts and CI. Local files only, like agents workflow diagram.

Stacked on #179 (it reuses that PR's loading code and Mermaid rendering); retarget to main once #179 merges.

Example

elevenlabs agents graph "Acme Concierge" (a mock agent with a 13-node workflow, three handoffs and dashboard-only tools and tests):

                                                            │          Billing          │
                                                            │  Billing (branch 'beta')  │
                                                            │       Tech Support        │
                                                            │ agent_01…7m2x9 (external) │
                                                        ┏━━►└───────────────────────────┘
                                                        ┃
                                                        ┃
                                                        ┃
                                                        ┃   ┌───────────────────────────┐
                                                        ┃   ║         Tools (5)         ║
                                                        ┃   ║      check_inventory      ║
                                                        ┃   ║       create_ticket       ║
                                 ┌──────────────────┐━━━┛   ║       issue_refund        ║
                                 │      Agent       │   ┌──►║       lookup_order        ║
┌─────────────────────────┐      │  Acme Concierge  │───┘   ║ tool_720…g8n4t (external) ║
│   Handed off from (2)   │      │ 2 hand off to it │       └───────────────────────────┘
│ Billing (branch 'beta') │━━━━━►│    4 handoffs    │
│      Tech Support       │      │     5 tools      │───┐
└─────────────────────────┘      │     3 tests      │   │
                                 │   4 documents    │   └──►╭───────────────────────────╮
                                 └──────────────────┘────┐  │         Tests (3)         │
                                                         │  │ Greets the caller by name │
                                                         │  │ Refunds only after lookup │
                                                         │  │ test_950…qm516 (external) │
                                                         │  ╰───────────────────────────╯
                                                         │
                                                         │
                                                         │
                                                         └───►┌─────────────────────┐
                                                              (    Documents (4)    )
                                                              (   Pricing & plans   )
                                                              (   Returns policy    )
                                                              (   Shipping times    )
                                                              ( Troubleshooting FAQ )
                                                              └─────────────────────┘

elevenlabs agents graph --uses lookup_order:

agent_7801k5concierge2b8n5	Acme Concierge	prompt.tool_ids
agent_7801k5concierge2b8n5	Acme Concierge	workflow node 'lookup'

elevenlabs agents graph --format mermaid on the test fixture project renders as:

flowchart LR
    n_Agent_agent_billing["Agent · Billing"]
    n_Agent_agent_support["Agent · Support"]
    n_Agent_agent_support_agtbrch_beta["Agent · Support (branch 'beta')"]
    n_Tool_tool_from_dashboard[["Tool (external) · tool_from_dashboard"]]
    n_Tool_tool_lookup[["Tool · lookup_order"]]
    n_Tool_tool_refund[["Tool · issue_refund"]]
    n_Test_test_greets(["Test · Greets the caller"])
    n_Document_doc_pricing[("Document · Pricing FAQ")]
    n_Agent_agent_billing --> n_Tool_tool_refund
    n_Agent_agent_billing --> n_Document_doc_pricing
    n_Agent_agent_support ==> n_Agent_agent_billing
    n_Agent_agent_support --> n_Tool_tool_from_dashboard
    n_Agent_agent_support --> n_Tool_tool_lookup
    n_Agent_agent_support --> n_Test_test_greets
    n_Agent_agent_support --> n_Document_doc_pricing
    n_Agent_agent_support_agtbrch_beta ==>|"via 'to_billing'"| n_Agent_agent_billing
    n_Agent_agent_support_agtbrch_beta --> n_Tool_tool_lookup
    n_Agent_agent_support_agtbrch_beta -->|"via 'refunds'"| n_Tool_tool_refund
    n_Agent_agent_support_agtbrch_beta --> n_Test_test_greets
    classDef t_tool fill:#fef3c7,stroke:#d97706,color:#78350f
    class n_Tool_tool_lookup,n_Tool_tool_refund t_tool
    classDef t_state fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
    class n_Test_test_greets t_state
    classDef t_subagent fill:#f1f5f9,stroke:#475569,color:#0f172a
    class n_Agent_agent_billing,n_Agent_agent_support,n_Agent_agent_support_agtbrch_beta t_subagent
    classDef t_unknown fill:#f3f4f6,stroke:#6b7280,stroke-dasharray:4 2,color:#111827
    class n_Tool_tool_from_dashboard t_unknown
    classDef t_doc fill:#ecfccb,stroke:#65a30d,color:#365314
    class n_Document_doc_pricing t_doc

Loading

Details

• References followed: prompt.tool_ids, workflow tool nodes and additional_tool_ids; handoffs in the transfer_to_agent tool and standalone_agent nodes (a handoff naming a registered branch points at that branch); platform_settings.testing.attached_tests; knowledge-base documents in prompt.knowledge_base and additional_knowledge_base. References inside a workflow node's prompt override count too, and the Mermaid output labels those edges with the node they come from.
• Documents have no local registry, so they're shown by ID and the name the config gives them.
• External IDs (a tool made in the dashboard, a handoff to an agent outside the repo) are drawn as external nodes, not dropped.
• Terminal layout. One drawing per agent: a summary card in the middle, agents that hand off to it in one box on the left, and one box per kind (handoffs, tools, tests, documents) on the right. Earlier versions with a node per resource were unreadable on real agents, because mmdflux crosses and merges lines in dense graphs. The card is tall enough that each line leaves from its own row, and the right-hand boxes are ordered by drawing every order (at most 24) and keeping the one with the fewest crossing or merging line characters. Every agent in the fixture project, the mock project and a real production agent draws with none.
• Narrow terminals. When the drawing is wider than the terminal (or COLUMNS), long IDs are shortened to their start and end, kept unique within the drawing. If it still doesn't fit, a note on stderr points at --format mermaid.
• --format mermaid (or mermaid-md, fenced) is the whole project as one flowchart LR, sorted by ID so it diffs cleanly; handoffs are thick arrows.
• Refactor: the Mermaid helpers shared with workflow diagram (IDs, escaping, shapes, colours, mmdflux drawing, terminal width, tangle counting) move from diagram.rs into mermaid.rs, with no change to diagram output. agents graph takes the same --format ascii|mermaid|mermaid-md values as workflow diagram. find_agent, the agents.json entry listing and a config's local name are shared too.
• Not included: the GitHub Action, and using --uses in it to comment "this PR changes a tool used by agents X and Y".

Testing

• cargo test: all suites pass, including 13 unit tests in graph.rs (each reference path, branch handoffs, external IDs, merged edges, --uses by ID and name, order independence, ID shortening) and 8 integration tests in tests/agents_graph_test.rs against a fixture project, with no API key. The terminal test fails if any drawing has a crossing or merging line.
• Ran mermaid 11.4.1's parser over the --format mermaid output for the fixture and mock projects: both parse.
• Drew a real production agent pulled into a temporary directory: 82 columns, no crossings.
• cargo clippy --all-targets: no new warnings.
• Not verified: how the colours look in light and dark terminal themes.

🤖 Generated with Claude Code

[kraenhansen]

I find the left to right diagrams a bit harder to read than the top to bottom, but I think that might just be a preference - I assume we could add a --direction option later.