microsoft / microsoft/agent-framework

Python: Review and standardize agent and workflow identity semantics

Open
#8,161 1 comment 0 reactions 1 assignee View on GitHub

@eavanvalkenburg is already working on this.

Since Sep 8, 2026.

.NET agents observability python
Dominant language
Python
Stars
13.6k
Forks
2.3k
Avg merge
2d 45m
Merged PRs (30d)
358

Description

## Summary

Review and standardize how Agent Framework uses machine-oriented IDs versus human-readable names for agents and workflows.

## Current observations

- `BaseAgent.id` is a machine identity, but defaults to a newly generated UUID when no ID is supplied.
- `BaseAgent.name` is human-readable, but workflow auto-wrapping currently uses the name as the default `AgentExecutor.id` when present.
- `Workflow.id` is runtime/instance-oriented, while `Workflow.name` is used for persistence grouping and telemetry naming.
- Workflow routing, duplicate executor detection, per-executor invocation kwargs, and checkpoint compatibility can therefore depend on human-readable names.
- Agent responses and telemetry expose both agent IDs and names, but their contract and intended stability should be made explicit.

## Request

Please review these semantics across Python and .NET and establish a consistent identity model. In particular:

1. Define when IDs versus names are used for machine identity, routing, persistence, telemetry, attribution, and display.
2. Determine whether workflow executor IDs should default to explicit stable IDs rather than human-readable agent names.
3. Clarify whether generated IDs are expected to be stable across process restarts, or whether callers must provide IDs for durable identity.
4. Document which identifiers are part of checkpoint and serialized-state compatibility.
5. Review the corresponding .NET APIs and align behavior where appropriate.
6. Add compatibility guidance and focused tests before changing any existing behavior.

## Important constraint

This should be treated as an API/design review rather than a blanket replacement of names with IDs. Names remain useful for display, message attribution, and telemetry labels; the goal is to ensure that machine-facing contracts do not accidentally depend on mutable human-readable values.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.