docs(aws-serverless): Backport improved troubleshooting execution guide#160
Merged
krokoko merged 2 commits intoMay 15, 2026
Merged
Conversation
vishalsatam
requested review from
a team,
krokoko,
scottschreckengaust and
theagenticguy
vishalsatam
force-pushed
the
backport/improve-troubleshooting-steering
branch
4 times, most recently
from
5e2f55c to
42cf189
Compare
bchampp
approved these changes
May 8, 2026
bchampp
reviewed
May 8, 2026
bchampp
left a comment
bchampp
left a comment
There was a problem hiding this comment.
I think we might consider adding a little more explicit instructions in the "Identify the root cause". From the original GitHub issue:
Key events to look for:
- CallbackTimedOut — timeout fired but may not have been caught
- ContextFailed — child context threw an unhandled error
- ExecutionFailed — entire execution crashed
- CallbackStarted with Timeout field — confirms timeout was registered
What do you think? Right now we're relying on the agents ability to interpret these history events but I think we can provide clearer guidance.
vishalsatam
force-pushed
the
backport/improve-troubleshooting-steering
branch
from
42cf189 to
039881e
Compare
Contributor
Author
I updated the commit to include details for the failure type of events. |
Backport changes from aws/aws-durable-execution-docs#161 to the agent-plugins repo. Improvements include: - ARN-based workflow instead of separate function name + execution ID - Alias resolution and list executions step - Console link generation for visual debugging - Structured output format with clear diagnosis summaries - CloudWatch Logs querying when execution history is insufficient - Additional usage examples covering failure scenarios - Better error handling guidance (execution not found, permissions) - Expanded trigger keywords in SKILL.md for better routing Closes aws/aws-durable-execution-docs#162
vishalsatam
force-pushed
the
backport/improve-troubleshooting-steering
branch
from
039881e to
2478a8b
Compare
bchampp
approved these changes
May 12, 2026
Contributor
Author
|
@scottschreckengaust @theagenticguy @krokoko , can you please review this pull request? If you approve, please merge as well since I don't have permissions. |
krokoko
approved these changes
May 15, 2026
bchampp
pushed a commit
to aws/aws-durable-execution-docs
that referenced
this pull request
May 15, 2026
Add detailed event type documentation to step 2b of the troubleshooting guide, providing explicit guidance on key execution history events: - Execution-level failures (ExecutionFailed, ExecutionTimedOut, ExecutionStopped) - Context and step failures (ContextFailed, StepFailed with RetryDetails) - Callback issues (CallbackStarted, CallbackTimedOut, CallbackFailed) - Chained invocation failures (ChainedInvokeFailed/TimedOut/Stopped) - Other signals (WaitCancelled, InvocationCompleted with Error) This gives agents clearer guidance for interpreting execution history events rather than relying on implicit knowledge. Syncs with awslabs/agent-plugins#160.
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
4 participants
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.
Backport changes from aws/aws-durable-execution-docs#161 to the agent-plugins repo.
Improvements include:
Closes aws/aws-durable-execution-docs#162
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.