[XieX]

Problem

With an Anthropic key that had no credits, a Claude Agents run returned { output: 'Credit balance is too low' } as a successful run. config().invoke tracked $ld:ai:generation:success, a caller would show the error text to a user as model output, and the trace showed an OK chat <synthetic> span.

The Claude Code CLI does not fail a run when an API call fails. Captured live from Agent SDK 0.3.220 with a rejected key (no credits takes the same path):

• an assistant message with model: "<synthetic>", error: "authentication_failed", zero usage, and the error text as content
• then a result with subtype: "success", is_error: true, api_error_status: 401, terminal_reason: "api_error", and the error text in result

The handlers checked only subtype. The agent SDK itself treats is_error as the failure signal and raises after the result, but the handler stops reading at the result and never sees that.

Fix

• assertRunSucceeded (exported from handler.ts, not from the package root) fails a run when subtype !== 'success' or is_error === true, and narrows the message to SDKResultSuccess otherwise. Both handler paths and toClaudeAgents use it.
• toClaudeAgents now gates on message.type === 'result' instead of 'result' in message. The old gate also let an error-subtype result through as an empty answer. A failed root now rejects and tracks $ld:ai:graph:invocation_failure; a failed sub-agent fails its tool call.
• An assistant message whose model is <synthetic> gets no chat span, joins no conversation, and adds no usage. It keys on model, not the error field, because the CLI also emits a synthetic message after a response stops at max_output_tokens, and that run can still succeed.
• agents.md documents the rule and drops the stale 'result' in message example.

Tests

Six new tests, each failing on main for the intended reason: an API-error result on the blocking and streaming paths, a synthetic message that shares a real response's id in a run that then succeeds, and the native graph root (API error, and error_max_turns) and sub-agent cases. A seventh pins that is_error: false stays a success.

Changed existing fixtures: two native-graph.test.ts results yielded { result, usage } with no type, which only worked through the old gate; they now carry type: 'result', subtype: 'success'.

The client package-exports snapshot test fails on main independently of this change; #137 fixes it.

Also checked end to end against the real CLI with a fake key and an empty CLAUDE_CONFIG_DIR: both paths reject with Claude agent run ended with an error result (HTTP 401): Invalid API key · Fix external API key, and the only span is invoke_agent with status ERROR.

Spec: TESTING.md §2.2 "Anthropic agents handler — run outcome from the result message" (launchdarkly/ai-sdks-monorepo#62).
Counterpart: launchdarkly/python-ai-sdk#174.

🤖 Generated with Claude Code

---

Note

Overview
Fixes a case where Claude Agent SDK runs could succeed while returning API error text (e.g. “Credit balance is too low”) because the CLI emits subtype: 'success' with is_error: true.

Run outcome: Adds exported assertRunSucceeded and uses it on blocking, streaming, and toClaudeAgents paths. Result handling now gates on message.type === 'result' instead of 'result' in message, so error subtypes without a result field and API-error “success” results both throw (generation/graph failure tracking instead of treating error text as model output).

Telemetry: Assistant messages with model: '<synthetic>' are ignored for chat spans, conversation history, and usage so CLI-injected error notices do not pollute traces or span content when a run later succeeds.

Docs in agents.md and new/updated tests cover API errors, streaming, synthetic messages, and native-graph root/sub-agent failures.

^{Reviewed by Cursor Bugbot for commit f5258bb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jeffdupont]

Matches ai-sdks-monorepo#62. assertRunSucceeded writes usage to the root before it throws and sets output attributes only after the check passes, so a failed span carries no gen_ai.output.messages. Streaming sends text only from stream_event deltas, so the synthetic message never reaches callers as a chunk. The native graph root goes to the existing invocation_failure catch, and a failed sub-agent throws from its tool executor. Tests cover every spec bullet; CI green.