azure.ai.agents - improve contributor guidance and add AGENTS.md#7111
Open
azure.ai.agents - improve contributor guidance and add AGENTS.md#7111
Conversation
…functions - Add Cause field and Unwrap() methods to azdext.LocalError and azdext.ServiceError to support Go error chain traversal (errors.Is/errors.As) - Add XxxWrap() variants to all exterrors factory functions (ValidationWrap, DependencyWrap, AuthWrap, etc.) that preserve the cause error - Update ServiceFromAzure and FromAiService to preserve cause via InternalWrap - Add comprehensive tests for error chain scenarios - Add detailed package-level documentation to exterrors explaining when to use structured vs plain errors and error chain precedence - Add replace directive to extension go.mod for local development Co-authored-by: JeffreyCA <9157833+JeffreyCA@users.noreply.github.com>
- Create comprehensive AGENTS.md with extension structure, build/test instructions, error handling guidelines, and coding conventions - Add detailed error handling section to extensions-style-guide.md covering structured error types, telemetry classification, the two-layer pattern, error chain precedence, and display/UX behavior Co-authored-by: JeffreyCA <9157833+JeffreyCA@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
JeffreyCA
March 13, 2026 00:15
View session
Remove all code changes (Cause field, Unwrap methods, Wrap factory functions, replace directive, new tests) and keep only documentation improvements: - AGENTS.md for azure.ai.agents extension - Error handling section in extensions-style-guide.md - Doc comments on existing exterrors functions and codes - Package-level documentation for exterrors The Cause/Unwrap support will be tracked as a separate GitHub issue. Co-authored-by: JeffreyCA <9157833+JeffreyCA@users.noreply.github.com>
Co-authored-by: JeffreyCA <9157833+JeffreyCA@users.noreply.github.com>
Co-authored-by: JeffreyCA <9157833+JeffreyCA@users.noreply.github.com>
JeffreyCA
changed the title
JeffreyCA
changed the title
JeffreyCA
requested review from
hemarina,
rajeshkamal5050,
tg-msft,
vhvb1989,
wbreza and
weikanglim
as code owners
JeffreyCA
requested review from
therealjohn,
trangevi and
trrwilson
as code owners
JeffreyCA
force-pushed
the
copilot/improve-error-categorization-guide
branch
from
35d3226 to
8e7a35d
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves contributor guidance for the azure.ai.agents extension by expanding structured error-handling documentation and adding extension-specific agent instructions.
Changes:
- Added/expanded documentation describing extension error serialization, telemetry classification, and recommended layering.
- Added
azure.ai.agents-specificAGENTS.mdwith build workflow and error-handling guidance. - Refined
internal/exterrorspackage comments and error-code documentation for clarity.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| cli/azd/extensions/azure.ai.agents/internal/exterrors/errors.go | Adds package-level guidance and section headers clarifying structured error usage and gRPC/Azure conversion helpers. |
| cli/azd/extensions/azure.ai.agents/internal/exterrors/codes.go | Clarifies intent/usage of error-code groups and improves inline documentation. |
| cli/azd/extensions/azure.ai.agents/AGENTS.md | Introduces extension-specific contributor/agent instructions (build, workflow, error handling, conventions). |
| cli/azd/docs/extensions/extensions-style-guide.md | Adds a new section documenting structured extension error types, host serialization behavior, and telemetry classification patterns. |
cli/azd/extensions/azure.ai.agents/internal/exterrors/errors.go
Outdated
Show resolved
Hide resolved
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR improves contributor guidance for the
azure.ai.agentsextension and makes the tenant selection behavior correct for prompted subscriptions.AGENTS.mdforcli/azd/extensions/azure.ai.agentsexterrorsversus plain Go errors without changing the underlying error modelinternal/exterrorspackage and code comments with the current azd host error serialization behaviorreplaceWhy
Recent error categorization work improved telemetry, but it also made it less obvious where structured errors should be created, when plain Go errors are still preferred, and how wrapping interacts with extension error reporting.
📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.