feat: add ProviderTokenCountError for native token counting failures

[opieter-aws]

Description

Add ProviderTokenCountError to the Python SDK, matching the typed error introduced in the TypeScript SDK (sdk-typescript#886). This error is thrown when a model provider's native token counting API returns an unexpected null result, and is used as internal control flow within provider count_tokens() overrides.

TypeScript port of

• TypeScript PR: feat: override countTokens with native token counting for supported providers sdk-typescript#886

Related Issues

#2179

Documentation PR

Will update as part of proactive compression doc updated

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare
• Existing TestCountTokens tests for Bedrock and Gemini (including test_fallback_on_none_total_tokens, test_fallback_on_api_error, test_fallback_on_generic_exception) continue to pass — 188
  tests, 0 failures

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Assessment: Approve

Clean, well-scoped PR that introduces a typed exception for null token count responses, replacing a generic ValueError in Gemini and adding null-safety to Bedrock. The change is purely internal (not exported in the public API), follows existing exception patterns, and has good test coverage.

Review Details

• Consistency: The new exception is only adopted in Bedrock and Gemini — the other providers with count_tokens overrides (Anthropic, OpenAI Responses, llama.cpp) don't use it. Worth considering whether those should be audited for null-safety as a follow-up.
• Design: Using an exception for internal control flow (null API response → fallback) is a valid pattern here since it keeps the try/except fallback path uniform across all failure modes, and aligns with the TypeScript SDK.

Solid incremental improvement to the token counting robustness. 👍

[github-actions]

Assessment: Approve

Clean, well-scoped PR that introduces a typed internal exception for null token count responses — replacing a generic ValueError in Gemini and adding null-safety to Bedrock's previously unsafe direct dict access. No public API surface change.

Review Details

• Terminology: The docstring uses "Thrown" instead of "Raised", breaking the consistent pattern used by every other exception in exceptions.py.
• Cross-provider consistency: Only Bedrock and Gemini adopt ProviderTokenCountError. Anthropic and OpenAI Responses access response.input_tokens without null guards, though their SDK types declare int (not Optional[int]), making this lower risk. Acceptable scope for this PR.