Normalize model rate limits into AG-UI run errors

[zoeshawwang]

Keep the change inside the SDK error-to-AG-UI boundary: detect structured 429/rate-limit signals, preserve RATE_LIMITED retry metadata on RUN_ERROR, and keep non-rate errors on their existing codes.

Constraint: Aone 83566999 requires model limit errors to end the AG-UI stream with RUN_ERROR rather than client-delivered text.

Rejected: funagent-core/front-end rewrite | downstream AG-UI frames are already pass-through and the SDK owns event semantics.

Rejected: broad generic error framework | current need is a small rate-limit normalizer.

Confidence: high

Scope-risk: narrow

Directive: Keep RUN_ERROR payload extensions whitelisted and preserve SSE event framing when adding fields.

Tested: uv run --extra server pytest tests/unittests/server/test_invoker.py tests/unittests/server/test_agui_protocol.py tests/unittests/integration/test_langgraph_events.py -q => 101 passed, 1 warning

Tested: uv run --extra server pytest tests/unittests/integration/test_langgraph_to_agent_event.py -q => 32 passed

Tested: git diff --check && uv run ruff check agentrun/server/error_utils.py agentrun/server/invoker.py agentrun/server/agui_protocol.py agentrun/integration/langgraph/agent_converter.py => passed

Tested: UltraQA dynamic AG-UI harness UQA-1..UQA-4 => passed

Change-Id: Ice926e2c21201071713ac39faeed736078fc5823
Co-developed-by: Codex noreply@openai.com
Not-tested: full repository test suite and remote CI pending

Thank you for creating a pull request to contribute to Serverless Devs agentrun-sdk-python code! Before you open the request please answer the following questions to help it be more easily integrated. Please check the boxes "[ ]" with "[x]" when done too.
Please select one of the PR types below to complete

---

Fix bugs

Bug detail

The specific manifestation of the bug or the associated issue.

Pull request tasks

• Add test cases for the changes
• Passed the CI test

---

Update docs

Reason for update

Why do you need to update your documentation?

Pull request tasks

• Update Chinese documentation
• Update English documentation

---

Add contributor

Contributed content

• Code
• Document

Content detail

if content_type == 'code' || content_type == 'document':
    please tell us `PR url`，like: https://github.com/Serverless-Devs/agentrun-sdk-python/pull/1
else:
    please describe your contribution in detail

---

Others

Reason for update

Why do you need to update your documentation?

[Copilot]

Pull request overview

This PR normalizes model rate-limit (HTTP 429 / throttling) errors into structured AG-UI RUN_ERROR events, ensuring rate-limit failures terminate the AG-UI stream with RUN_ERROR (and include retry metadata) while non-rate errors keep their existing error codes/messages.

Changes:

• Introduces agentrun/server/error_utils.py to detect rate-limit signals and build normalized ERROR payloads (RATE_LIMITED, retryable, retryAfterMs, optional traceId).
• Routes invoker and LangGraph conversion error handling through the shared normalizer to keep semantics consistent across boundaries.
• Updates AG-UI encoding to whitelist/preserve specific RUN_ERROR extension fields, with added unit/integration tests covering positives and false-positives.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
agentrun/server/error_utils.py	New shared helper to detect rate-limit errors and build normalized ERROR payloads.
agentrun/server/invoker.py	Uses the shared helper to normalize ERROR events emitted by the invoker.
agentrun/server/agui_protocol.py	Whitelists and preserves selected extra fields when encoding RUN_ERROR SSE payloads.
agentrun/integration/langgraph/agent_converter.py	Reuses the shared helper to normalize LangGraph-derived error events.
tests/unittests/server/test_invoker.py	Adds invoker-level tests for structured rate-limit detection and false-positive avoidance.
tests/unittests/server/test_agui_protocol.py	Adds AG-UI stream tests ensuring RUN_ERROR payload shape/fields and no RUN_FINISHED on rate limits.
tests/unittests/integration/test_langgraph_to_agent_event.py	Adds integration coverage for rate-limited vs non-rate LLM errors in conversion.
tests/unittests/integration/test_langgraph_events.py	Mirrors integration coverage for LangGraph event conversion behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.