[4643] fix(sdk): Support tool_choice in prompt templates

[fintech07]

Summary

Refs #4643.

This PR adds SDK support for OpenAI-compatible tool_choice values in Agenta prompt templates. Prompt configs can now use "required", named function choices, and allowed-tools choices, and those structured values are serialized back to plain dictionaries before they are forwarded to LiteLLM/OpenAI.

Before this change, the SDK accepted "none", "auto", or arbitrary dictionaries. That meant "required" was rejected even though it is part of OpenAI's Chat Completions tool_choice schema.

Changes

The SDK now accepts these tool_choice shapes in prompt template model configs:

"none"
"auto"
"required"
{"type": "function", "function": {"name": "get_weather"}}
{"type": "allowed_tools", "allowed_tools": {"mode": "required", "tools": [...]}}

The existing behavior is preserved where tool_choice is only sent to the provider when tools are present.

Provider behavior note: OpenAI-compatible providers may support different subsets of tool_choice. This PR keeps the SDK schema aligned with OpenAI and leaves unsupported model/provider combinations to fail at the provider or LiteLLM layer instead of adding Agenta-specific provider validation.

Demo

SDK-only terminal verification:

Testing

• Added SDK unit tests for "required", named function choices, allowed-tools choices, omission without tools, and invalid string values.
• Ran pipx run uv run pytest oss/tests/pytest/unit/test_prompt_template_extensions.py -v
• Ran pipx run uv run pytest oss/tests/pytest/unit/ -v
• Ran pipx run uv run --with ruff ruff format agenta/sdk/utils/types.py oss/tests/pytest/unit/test_prompt_template_extensions.py
• Ran pipx run uv run --with ruff ruff check --fix agenta/sdk/utils/types.py oss/tests/pytest/unit/test_prompt_template_extensions.py

QA

No manual UI QA needed. This is covered by SDK unit tests.

[vercel]

@fintech07 is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 73a8131f-a2b1-4580-8f18-259dcf956e97

📥 Commits

Reviewing files that changed from the base of the PR and between 58a5cca and e2e5cc2.

📒 Files selected for processing (2)

• sdks/python/agenta/sdk/utils/types.py
• sdks/python/oss/tests/pytest/unit/test_prompt_template_extensions.py

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Improved OpenAI chat completion tool_choice handling with stronger validation and support for multiple modes, including auto, required, named function selection, and allowed_tools.
  • Correctly serializes tool_choice configuration into provider-ready request parameters.

• Tests

  • Added unit tests covering tool_choice forwarding, omission when tools aren’t configured, supported selection modes, and validation errors for invalid values.

Walkthrough

Introduces structured Pydantic models (ChatCompletionNamedToolChoice, ChatCompletionAllowedToolChoice, and supporting types) plus a ToolChoice union alias. Updates tool_choice fields on ModelConfig and AgLLM to use Optional[ToolChoice] and adjusts PromptTemplate.to_openai_kwargs serialization to call model_dump for Pydantic instances.

Changes

Structured ToolChoice types and serialization

Layer / File(s)	Summary
ToolChoice models and type alias sdks/python/agenta/sdk/utils/types.py	Adds ChatCompletionNamedToolChoiceFunction, ChatCompletionNamedToolChoice, ChatCompletionAllowedTools, ChatCompletionAllowedToolChoice Pydantic models and the ToolChoice union type alias. Expands typing imports to include TypeAlias and Any.
ModelConfig and AgLLM field type updates sdks/python/agenta/sdk/utils/types.py	Updates tool_choice on ModelConfig and AgLLM from Optional[Union[Literal["none","auto"], Dict]] to Optional[ToolChoice].
PromptTemplate serialization for ToolChoice sdks/python/agenta/sdk/utils/types.py	Modifies PromptTemplate.to_openai_kwargs to serialize tool_choice via model_dump(by_alias=True, exclude_none=True) when the value is a Pydantic BaseModel, otherwise passes it through unchanged.
Unit tests for tool_choice forwarding and validation sdks/python/oss/tests/pytest/unit/test_prompt_template_extensions.py	Adds ValidationError import and new tests covering tool_choice forwarding for "required" string, named function selection, and allowed_tools modes; omission when tools are absent; and ValidationError on invalid string values.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Support tool_choice in Agenta prompt templates #4643: This PR directly implements the structured tool_choice support requested in that issue, adding the Pydantic models, type alias, field updates, serialization logic, and tests described there.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 60.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: adding tool_choice support in prompt templates with a clear, specific reference to the issue number.
Description check	✅ Passed	The description is comprehensive and well-related to the changeset, covering the motivation, changes made, testing performed, and expected behavior.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

✅ Thanks @fintech07! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.