Repository navigation
.NET: Agents used as Executors are displayed as cryptic GUIDs instead of names in workflow visualizations #1495
Description
Summary
When AI agents (e.g., ChatClientAgent) are used as executors in workflows, the workflow visualization tools (ToMermaidString(), ToDotString()) display them using cryptic internal GUIDs instead of the meaningful names provided during agent creation. This makes workflow diagrams difficult to read, debug, and share with stakeholders.
The issue specifically affects agents used as executors in workflow graphs. Custom executors (e.g., ReflectingExecutor subclasses) display their names correctly, but agents added via AddFanOutEdge or similar methods appear as GUIDs.
This significantly impacts the developer experience when debugging multi-agent workflows and makes the visualization feature nearly unusable for complex workflows.
Current Behavior
Agents with explicit names are converted to executors internally and render as GUIDs in workflow diagrams:
// Create agents with meaningful names
ChatClientAgent physicist = new ChatClientAgent(
chatClient,
name: "Physicist", // ❌ Name is ignored in visualizations
instructions: "You are an expert in physics."
);
ChatClientAgent chemist = new ChatClientAgent(
chatClient,
name: "Chemist", // ❌ Name is ignored in visualizations
instructions: "You are an expert in chemistry."
);
// Build workflow - agents are implicitly converted to executors
var workflow = new WorkflowBuilder(startExecutor)
.AddFanOutEdge(startExecutor, targets: [physicist, chemist])
.AddFanInEdge(aggregationExecutor, sources: [physicist, chemist])
.Build();
// Generate visualization
Console.WriteLine(workflow.ToMermaidString());
Actual Output (Mermaid):
flowchart TD
ConcurrentStartExecutor["ConcurrentStartExecutor (Start)"];
9cd24477cd214320807e3a444e3ea7ef["9cd24477cd214320807e3a444e3ea7ef"];
a98a1b5c1da9406891aeaac42fa34e69["a98a1b5c1da9406891aeaac42fa34e69"];
Sample08AggregationExecutor["Sample08AggregationExecutor"];
ConcurrentStartExecutor --> 9cd24477cd214320807e3a444e3ea7ef;
ConcurrentStartExecutor --> a98a1b5c1da9406891aeaac42fa34e69;
9cd24477cd214320807e3a444e3ea7ef --> Sample08AggregationExecutor;
a98a1b5c1da9406891aeaac42fa34e69 --> Sample08AggregationExecutor;
Which when rendered is not really that useful...
Issues:
• 9cd24477cd214320807e3a444e3ea7ef should display as "Physicist"
• a98a1b5c1da9406891aeaac42fa34e69 should display as "Chemist"
• Custom executors (e.g., Sample08AggregationExecutor) display correctly ✅
• Only agents-as-executors are affected by this visualization issue ❌
• Also when we add an Agent in an implicit way, what if we want to reference this same executor in other part of the workflow. Are we creating another Executor or reusing the previously created one? We have no control over that and no visibility on what is happening.
Expected Behavior
Agents used as executors should display using their .Name property in all visualization outputs, and/or an id concatenated as we could add the same Agent several times and that would become a different executor. If the Agent is added implicitly then it should retain its name on the Executor bounding it so it is clearly identifiable.
flowchart TD
ConcurrentStartExecutor["ConcurrentStartExecutor (Start)"];
Physicist["Physicist"];
Chemist["Chemist"];
Sample08AggregationExecutor["Sample08AggregationExecutor"];
ConcurrentStartExecutor --> Physicist;
ConcurrentStartExecutor --> Chemist;
Physicist --> Sample08AggregationExecutor;
Chemist --> Sample08AggregationExecutor;
or
flowchart TD
ConcurrentStartExecutor["ConcurrentStartExecutor (Start)"];
Physicist["Physicist_7744477"];
Chemist["Chemist_354345345"];
Sample08AggregationExecutor["Sample08AggregationExecutor"];
ConcurrentStartExecutor --> Physicist_7744477;
ConcurrentStartExecutor --> Chemist_354345345;
Physicist_7744477 --> Sample08AggregationExecutor;
Chemist_354345345--> Sample08AggregationExecutor;
With a proposed .AsExecutor() extension method (or similar API), developers should be able to explicitly convert agents to executors with readable names:
// Create agents with meaningful names
ChatClientAgent physicist = new ChatClientAgent(
chatClient,
name: "Physicist",
instructions: "You are an expert in physics."
);
ChatClientAgent chemist = new ChatClientAgent(
chatClient,
name: "Chemist",
instructions: "You are an expert in chemistry."
);
**// ✅ OPTION 1: Implicit conversion preserves agent names (minimal API change)
var workflow = new WorkflowBuilder(startExecutor)
.AddFanOutEdge(startExecutor, targets: [physicist, chemist])
.AddFanInEdge(aggregationExecutor, sources: [physicist, chemist])
.Build();**
// When visualized, agents should display as "Physicist" and "Chemist"
Console.WriteLine(workflow.ToMermaidString());
// ✅ OPTION 2: Explicit conversion with .AsExecutor() (more control, discoverable)
**ExecutorIsh physicistExecutor = physicist.AsExecutor(); // Uses agent.Name
ExecutorIsh chemistExecutor = chemist.AsExecutor(); // Uses agent.Name**
var workflow = new WorkflowBuilder(startExecutor)
.AddFanOutEdge(startExecutor, targets: [physicistExecutor, chemistExecutor])
.AddFanInEdge(aggregationExecutor, sources: [physicistExecutor, chemistExecutor])
.Build();
// Agents now display with their meaningful names in visualizations
Console.WriteLine(workflow.ToMermaidString());
Reproduction Steps
- Create a workflow with named agents used as executors:
ChatClientAgent physicist = new ChatClientAgent(
chatClient,
name: "Physicist",
instructions: "You are an expert in physics."
);
var workflow = new WorkflowBuilder(startExecutor)
.AddFanOutEdge(startExecutor, targets: [physicist])
.Build();
- Generate visualization:
string mermaid = workflow.ToMermaidString();
Console.WriteLine(mermaid);
- Observe: Agent appears as GUID (e.g., 9cd24477cd214320807e3a444e3ea7ef) instead of "Physicist"
- Compare: Custom executors in the same workflow display their names correctly
Root Cause Analysis (Hypothesis)
When agents are added to workflows, they are internally converted to executors. During this conversion:
- The agent's .Name property is not propagated to the executor wrapper
- The executor wrapper uses a GUID-based ID as the display name
- The visualization renderer uses the executor's ID instead of a semantic name
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity