From 496fdd4d634cfda39ae578febc5b65ed0ff45afa Mon Sep 17 00:00:00 2001
From: hiroTamada <88675973+hiroTamada@users.noreply.github.com>
Date: Thu, 10 Sep 2026 13:07:55 +0000
Subject: [PATCH 1/2] Document invocation failure summaries and detailed output
---
apps/status.mdx | 55 +++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 51 insertions(+), 4 deletions(-)
diff --git a/apps/status.mdx b/apps/status.mdx
index 21a81988..0e766fdc 100644
--- a/apps/status.mdx
+++ b/apps/status.mdx
@@ -65,6 +65,7 @@ func main() {
Here's an example showing how to handle streaming status updates:
+
```typescript Typescript/Javascript
const result = await kernel.invocations.retrieve(invocation.id);
const follow = await kernel.invocations.follow(result.id);
@@ -80,10 +81,7 @@ for await (const evt of follow) {
}
break;
} else if (evt.invocation.status === 'failed') {
- console.log('Invocation failed');
- if (evt.invocation.status_reason) {
- console.log('Error:', evt.invocation.status_reason);
- }
+ console.error(evt.invocation.status_reason ?? 'Invocation failed.');
break;
}
} else if (evt.event === 'error') {
@@ -93,6 +91,55 @@ for await (const evt of follow) {
}
```
+```python Python
+import json
+
+from kernel import Kernel
+
+kernel = Kernel()
+
+for evt in kernel.invocations.follow("rr33xuugxj9h0bkf1rdt2bet"):
+ if evt.event == "invocation_state":
+ invocation = evt.invocation
+ print(f"Status: {invocation.status}")
+ if invocation.status == "succeeded":
+ if invocation.output:
+ print("Result:", json.loads(invocation.output))
+ break
+ if invocation.status == "failed":
+ print(invocation.status_reason or "Invocation failed.")
+ break
+ elif evt.event == "error":
+ print("Error:", evt.error.message)
+ break
+```
+
+
+## Failure details
+
+A failed invocation has two distinct fields:
+
+- `status_reason`: A nonempty, customer-safe failure summary. It's present when `status` is `failed` and omitted for other statuses. Recognized failures, such as timeouts or startup failures, receive specific summaries. Unrecognized failures receive `"Invocation failed. See output for details."`; failures with no recorded reason receive `"Invocation failed; no failure reason was recorded."`.
+- `output`: The original action result or detailed failure output. It's optional and often JSON-encoded, but failures can contain plain text. Don't assume that every failure output can be parsed as JSON.
+
+These rules apply to streaming events, retrieval, listing, and synchronous invocation responses. The first failed `invocation_state` event includes `status_reason`. Historical invocations also receive a summary when you retrieve or stream them; no rerun is needed. During rollout, if `status_reason` is absent, inspect `output` for the recorded error.
+
+For example, a timeout returns these fields alongside the invocation's ID and other metadata:
+
+```json
+{
+ "status": "failed",
+ "status_reason": "Invocation timed out after 900 seconds.",
+ "output": "{\"error\":\"timed out after 900 seconds\"}"
+}
+```
+
+Use `status_reason` to display the failure and inspect `output` separately for diagnostics. Reason text can change; don't use it as a stable identifier for retry decisions.
+
+
+ Detailed output can contain sensitive application data, including account details or credentials. Restrict access and redact it before sharing or logging it. Failure summaries don't copy arbitrary application errors or internal traces.
+
+
## Polling Status Updates
Alternatively, you can poll the status endpoint using `retrieve` to check the invocation status periodically.
From 8a6e864fb25e51d3e38887a3c5a30d04d7460773 Mon Sep 17 00:00:00 2001
From: hiroTamada <88675973+hiroTamada@users.noreply.github.com>
Date: Thu, 10 Sep 2026 17:55:48 +0000
Subject: [PATCH 2/2] Clarify failure summaries do not establish error
provenance
---
apps/status.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/apps/status.mdx b/apps/status.mdx
index 0e766fdc..8b7f237d 100644
--- a/apps/status.mdx
+++ b/apps/status.mdx
@@ -119,7 +119,7 @@ for evt in kernel.invocations.follow("rr33xuugxj9h0bkf1rdt2bet"):
A failed invocation has two distinct fields:
-- `status_reason`: A nonempty, customer-safe failure summary. It's present when `status` is `failed` and omitted for other statuses. Recognized failures, such as timeouts or startup failures, receive specific summaries. Unrecognized failures receive `"Invocation failed. See output for details."`; failures with no recorded reason receive `"Invocation failed; no failure reason was recorded."`.
+- `status_reason`: A nonempty, customer-safe failure summary. It's present when `status` is `failed` and omitted for other statuses. Recognized messages, such as timeout or startup failure messages, receive specific summaries. Unrecognized failures receive `"Invocation failed. See output for details."`; failures with no recorded reason receive `"Invocation failed; no failure reason was recorded."`.
- `output`: The original action result or detailed failure output. It's optional and often JSON-encoded, but failures can contain plain text. Don't assume that every failure output can be parsed as JSON.
These rules apply to streaming events, retrieval, listing, and synchronous invocation responses. The first failed `invocation_state` event includes `status_reason`. Historical invocations also receive a summary when you retrieve or stream them; no rerun is needed. During rollout, if `status_reason` is absent, inspect `output` for the recorded error.
@@ -134,7 +134,7 @@ For example, a timeout returns these fields alongside the invocation's ID and ot
}
```
-Use `status_reason` to display the failure and inspect `output` separately for diagnostics. Reason text can change; don't use it as a stable identifier for retry decisions.
+Use `status_reason` to display the failure and inspect `output` separately for diagnostics. Summaries match the recorded error text, which can come from either the platform or your action code. A matching message doesn't establish where the failure originated. Reason text can change; don't use it as a stable identifier for retry decisions.
Detailed output can contain sensitive application data, including account details or credentials. Restrict access and redact it before sharing or logging it. Failure summaries don't copy arbitrary application errors or internal traces.