feat: add intent= to ha_call_service for HA media intents (closes #899)

[Patch76]

What does this PR do?

Extends ha_call_service with an optional intent= parameter that routes to
POST /api/intent/handle instead of the standard service endpoint.

This covers the remaining use cases from #899 that have no direct service-call
equivalent — specifically media intents (HassMediaSearch, HassMediaPause,
HassMediaUnpause) where the intent layer provides semantic resolution that plain
service calls don't offer.

What's already covered by existing tools (not in scope):

Use case	Covered by
Date / time	ha_eval_template
Basic device control	ha_call_service + ha_search_entities
Area-based control	ha_call_service with area_id

New usage:

ha_call_service(intent="HassMediaSearch",
                data={"media_type": "music", "search_term": "jazz"})
ha_call_service(intent="HassMediaPause")

When intent= is set, domain and service are ignored. Requires the
conversation integration (enabled by default since HA 2023.2).

Design note: domain="intent" was rejected — custom integrations could
register an intent service domain. The intent= parameter avoids namespace
collision while keeping the feature in ha_call_service per #899 direction.

Closes #899

Type of change

• 🐛 Bug fix
• ✨ New feature
• 🖼️ Documentation
• 🔧 Maintenance/refactor
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Checklist

• I have updated documentation if needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces support for Home Assistant intents within the ha_call_service tool. By allowing users to specify an intent parameter, the tool can now handle complex media operations and other tasks that lack direct service-call equivalents, leveraging the Home Assistant conversation integration for semantic resolution.

Highlights

• Intent Support: Added an optional intent parameter to ha_call_service to route requests to the Home Assistant /api/intent/handle endpoint.
• API Client Update: Implemented call_intent in the REST client to facilitate communication with the intent handling API.
• Test Coverage: Added comprehensive unit tests to verify correct routing between standard service calls and new intent-based calls.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for Home Assistant intents within the ha_call_service tool. It adds a call_intent method to the REST client and updates the tool logic to route requests to the intent handler when the new intent parameter is provided. To improve the implementation, the JSON parsing for intent data should be wrapped in a try...except block to return structured validation errors in accordance with the repository's error-handling guidelines. Furthermore, since domain and service are now optional, a validation check is needed to ensure they are present when an intent is not specified, preventing potential runtime errors during normal service routing.

[Patch76]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces intent handling to the ha_call_service tool, allowing users to trigger Home Assistant intents via the REST API. The changes include a new call_intent method in the REST client, updated tool logic to route requests based on the presence of an intent parameter, and comprehensive unit tests. I have provided feedback regarding the need for more specific exception handling to improve debuggability and consistency with repository standards.

[Patch76]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for Home Assistant intents within the ha_call_service tool by adding a call_intent method to the REST client and implementing routing logic to handle intent-based requests. The changes include updated parameter validation, specialized error handling for intents, and a new suite of unit tests to verify the routing behavior. Feedback suggests refactoring the intent processing logic into a dedicated helper function to improve the maintainability and focus of the ha_call_service tool.