Add new tool calling capability #822

filintod · 2025-07-29T02:32:47Z

Description

Implement conversation new alpha2 version with tool calling. As new protos are more complex, added DevEx helpers and tests.

Issue reference

Part of 1.16 dapr/dapr#8553

Please reference the issue this PR will close: #[issue number]

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

Code compiles correctly
Created/updated tests
Extended the documentation

Signed-off-by: Filinto Duran <[email protected]>

dapr/clients/base.py

Signed-off-by: Filinto Duran <[email protected]>

filintod · 2025-08-06T15:35:30Z

@elena-kolevska not sure if you are still working on this to review? I kind of redid the proto changes you had before, there has also been some changes on dapr master about it

dapr/aio/clients/grpc/client.py

dapr/clients/grpc/_helpers.py

dapr/proto/runtime/v1/dapr_pb2.py

dapr/proto/runtime/v1/dapr_pb2_grpc.py

examples/conversation/conversation_alpha2.py

tests/clients/test_conversation.py

elena-kolevska

Thanks for the contribution @filintod :)

I left few initial comments, will try to do a deeper review of the actual implementation as soon as possible.

examples/conversation/conversation_alpha2.py

pyproject.toml

examples/conversation/README.md

Signed-off-by: Filinto Duran <[email protected]>

filintod · 2025-08-12T14:00:31Z

@elena-kolevska @acroca , as I was closing the feedback items, I was wondering if leaving all those converstation-specific classes in _request.py is ok or should I refactor the conversation ones to a _conversation.py file?

lmk

elena-kolevska · 2025-08-12T15:07:31Z

@elena-kolevska @acroca , as I was closing the feedback items, I was wondering if leaving all those converstation-specific classes in _request.py is ok or should I refactor the conversation ones to a _conversation.py file?

lmk

We already started separating domain-specific stuff in their own files (crypto, jobs, streaming subscriptions...), and I think it's a good practice we should continue. Thanks for suggesting it, Filinto! 🙏

elena-kolevska · 2025-08-12T15:08:11Z

@filintod there are some test and lint failures, pls ping me when they're fixed so I can rerun them.

Signed-off-by: Filinto Duran <[email protected]>

tox.ini

Signed-off-by: Filinto Duran <[email protected]>

filintod · 2025-08-14T17:12:38Z

@acroca @elena-kolevska this should be ready now

Some example README refactor/lint Signed-off-by: Filinto Duran <[email protected]>

Signed-off-by: Filinto Duran <[email protected]>

filintod · 2025-08-30T21:49:31Z

ran tox -e ruff to fix the format count mismatch shown on the lint error. I thought tox -e flake8 green meant that it was ok, but now I know.

codecov · 2025-09-03T10:07:38Z

Codecov Report

❌ Patch coverage is 91.83246% with 78 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.33%. Comparing base (bffb749) to head (bc3dcf0).
⚠️ Report is 40 commits behind head on main.

Files with missing lines	Patch %	Lines
dapr/clients/grpc/_conversation_helpers.py	85.29%	75 Missing ⚠️
dapr/clients/grpc/conversation.py	99.03%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #822      +/-   ##
==========================================
+ Coverage   86.63%   87.33%   +0.70%     
==========================================
  Files          84       93       +9     
  Lines        4473     6143    +1670     
==========================================
+ Hits         3875     5365    +1490     
- Misses        598      778     +180

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

elena-kolevska

Last change request.. Small, but I believe it's really important

elena-kolevska · 2025-09-03T10:26:00Z

dapr/clients/grpc/conversation.py

+def execute_registered_tool(name: str, params: Union[Params, str] = None) -> Any:
+    """Execute a registered tool."""
+    if isinstance(params, str):
+        params = json.loads(params)


This is a vulnerable part of our code, so we need to add at least some basic validation, and probably consider sanitisation for the future

Also, let's please add a detailed docstring explaining the vulnerability and giving some suggestions to developers on writing safe functions that validate the LLM input.
I know you said you'd be sending a docs PR, but I think it's important to have this here as well.

elena-kolevska · 2025-09-03T10:42:40Z

Is this planned to be included in 1.16? If so, we would need to cherrypick it in the 1.16 branch.

…rs that codecov pointed out Signed-off-by: Filinto Duran <[email protected]>

…ts for them to validate Signed-off-by: Filinto Duran <[email protected]>

filintod · 2025-09-03T17:41:21Z

@elena-kolevska ptal, thanks

elena-kolevska · 2025-09-03T21:45:56Z

tests/clients/test_conversation_helpers_more.py

Why do we need two files for this? Let's either merge them or try to find a more descriptive name than one ending in _more

ok, it was just getting too big. I'll merge and check the error on python 3.13 shown in CI

ok please take another look

Signed-off-by: Filinto Duran <[email protected]>

Signed-off-by: Elena Kolevska <[email protected]>

elena-kolevska

I did a quick fix of the linter, but there are still some typing errors

Signed-off-by: Filinto Duran <[email protected]>

filintod · 2025-09-04T14:15:41Z

sorry @elena-kolevska , I did changed something to fix an issue in a test breaking on 3.13, but looks like it broke 3.9. I need to have pre-commit for the future. It "must" be good now.

elena-kolevska · 2025-09-04T17:31:00Z

Merged! 🎉 Thanks for your contribution and your patience @filintod :)

* initial Signed-off-by: Filinto Duran <[email protected]> * fixes after proto change upstream Signed-off-by: Filinto Duran <[email protected]> * minor name changes and cleanup unused function Signed-off-by: Filinto Duran <[email protected]> * refactors, updates to readme, linting Signed-off-by: Filinto Duran <[email protected]> * feedback Signed-off-by: Filinto Duran <[email protected]> * feedback, updates Signed-off-by: Filinto Duran <[email protected]> * fix import in examples Signed-off-by: Filinto Duran <[email protected]> * cleanup, import, lint, more conversation helpers Signed-off-by: Filinto Duran <[email protected]> * clarify README, minor test import changes, copyright Signed-off-by: Filinto Duran <[email protected]> * feedback DRY test_conversation file Signed-off-by: Filinto Duran <[email protected]> * lint Signed-off-by: Filinto Duran <[email protected]> * move conversation classes in _response module to conversation module. Some example README refactor/lint Signed-off-by: Filinto Duran <[email protected]> * minor readme change Signed-off-by: Filinto Duran <[email protected]> * Update daprdocs/content/en/python-sdk-docs/python-client.md Co-authored-by: Albert Callarisa <[email protected]> Signed-off-by: Filinto Duran <[email protected]> * lint Signed-off-by: Filinto Duran <[email protected]> * updates to fix issue with tool calling helper when dealing with classes instead of dataclasses, and also with serializatin output of the tool back to the LLM Signed-off-by: Filinto Duran <[email protected]> * coalesce conv helper tests, fix typing lint Signed-off-by: Filinto Duran <[email protected]> * make indent line method doc more dev friendly Co-authored-by: Elena Kolevska <[email protected]> Signed-off-by: Filinto Duran <[email protected]> * tackle some feedback, still missing unit tests Signed-off-by: Filinto Duran <[email protected]> * add unit test to convert_value_to_struct Signed-off-by: Filinto Duran <[email protected]> * more unit tests per feedback Signed-off-by: Filinto Duran <[email protected]> * make async version of unit test conversation Signed-off-by: Filinto Duran <[email protected]> * add some information how to run markdown tests with a different runtime Signed-off-by: Filinto Duran <[email protected]> * ran tox -e ruff, even though tox -e flake8 was fine Signed-off-by: Filinto Duran <[email protected]> * add tests to increase coverage in conversation and conversation_helpers that codecov pointed out Signed-off-by: Filinto Duran <[email protected]> * add more information on execute registered tools, also added more tests for them to validate Signed-off-by: Filinto Duran <[email protected]> * fix test failing on py 1.13. Merge two unit test files per feedback Signed-off-by: Filinto Duran <[email protected]> * Linter Signed-off-by: Elena Kolevska <[email protected]> * fix typing issue with UnionType in py3.9 Signed-off-by: Filinto Duran <[email protected]> --------- Signed-off-by: Filinto Duran <[email protected]> Signed-off-by: Elena Kolevska <[email protected]> Co-authored-by: Albert Callarisa <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> Co-authored-by: Elena Kolevska <[email protected]>

) * initial * fixes after proto change upstream * minor name changes and cleanup unused function * refactors, updates to readme, linting * feedback * feedback, updates * fix import in examples * cleanup, import, lint, more conversation helpers * clarify README, minor test import changes, copyright * feedback DRY test_conversation file * lint * move conversation classes in _response module to conversation module. Some example README refactor/lint * minor readme change * Update daprdocs/content/en/python-sdk-docs/python-client.md * lint * updates to fix issue with tool calling helper when dealing with classes instead of dataclasses, and also with serializatin output of the tool back to the LLM * coalesce conv helper tests, fix typing lint * make indent line method doc more dev friendly * tackle some feedback, still missing unit tests * add unit test to convert_value_to_struct * more unit tests per feedback * make async version of unit test conversation * add some information how to run markdown tests with a different runtime * ran tox -e ruff, even though tox -e flake8 was fine * add tests to increase coverage in conversation and conversation_helpers that codecov pointed out * add more information on execute registered tools, also added more tests for them to validate * fix test failing on py 1.13. Merge two unit test files per feedback * Linter * fix typing issue with UnionType in py3.9 --------- Signed-off-by: Filinto Duran <[email protected]> Signed-off-by: Elena Kolevska <[email protected]> Co-authored-by: Albert Callarisa <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> Co-authored-by: Elena Kolevska <[email protected]>

* 1.16.0-rc1 Signed-off-by: Elena Kolevska <[email protected]> * [Conversation API - Alpha2] Add new tool calling capability (#822) (#832) * initial * fixes after proto change upstream * minor name changes and cleanup unused function * refactors, updates to readme, linting * feedback * feedback, updates * fix import in examples * cleanup, import, lint, more conversation helpers * clarify README, minor test import changes, copyright * feedback DRY test_conversation file * lint * move conversation classes in _response module to conversation module. Some example README refactor/lint * minor readme change * Update daprdocs/content/en/python-sdk-docs/python-client.md * lint * updates to fix issue with tool calling helper when dealing with classes instead of dataclasses, and also with serializatin output of the tool back to the LLM * coalesce conv helper tests, fix typing lint * make indent line method doc more dev friendly * tackle some feedback, still missing unit tests * add unit test to convert_value_to_struct * more unit tests per feedback * make async version of unit test conversation * add some information how to run markdown tests with a different runtime * ran tox -e ruff, even though tox -e flake8 was fine * add tests to increase coverage in conversation and conversation_helpers that codecov pointed out * add more information on execute registered tools, also added more tests for them to validate * fix test failing on py 1.13. Merge two unit test files per feedback * Linter * fix typing issue with UnionType in py3.9 --------- Signed-off-by: Filinto Duran <[email protected]> Signed-off-by: Elena Kolevska <[email protected]> Co-authored-by: Albert Callarisa <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> * update docs with tool calling helpers info (#838) Signed-off-by: Filinto Duran <[email protected]> * 1.16.0rc2 Signed-off-by: Elena Kolevska <[email protected]> * use latest durabletask (#840) Signed-off-by: Cassandra Coyle <[email protected]> * 1.16.0 Signed-off-by: Elena Kolevska <[email protected]> * Adds support for interceptors and concurrency_options arguments in the workflow engine (#841) Signed-off-by: Albert Callarisa <[email protected]> * Implement multi-app workflows (#844) * feat: Adds support for cross-app calls. Signed-off-by: Albert Callarisa <[email protected]> * Use durabletask alpha.9 Signed-off-by: Albert Callarisa <[email protected]> * Added examples for error scenarios in multi-app workflow Signed-off-by: Albert Callarisa <[email protected]> * Remove unnecessary hardcoded ports Signed-off-by: Albert Callarisa <[email protected]> --------- Signed-off-by: Albert Callarisa <[email protected]> * chore: Rename wait_until_ready to wait_for_sidecar (#843) Signed-off-by: Albert Callarisa <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> * 1.16.1rc1 (#846) Signed-off-by: Albert Callarisa <[email protected]> --------- Signed-off-by: Elena Kolevska <[email protected]> Signed-off-by: Filinto Duran <[email protected]> Signed-off-by: Cassandra Coyle <[email protected]> Signed-off-by: Albert Callarisa <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> Co-authored-by: Filinto Duran <[email protected]> Co-authored-by: Albert Callarisa <[email protected]> Co-authored-by: Elena Kolevska <[email protected]> Co-authored-by: Albert Callarisa <[email protected]>

marcduiker · 2025-11-18T11:35:50Z

@holopin-bot @filintod Thank you! Here's a digital badge as a small token of appreciation.

holopin-bot · 2025-11-18T11:35:53Z

Congratulations @filintod, the maintainer of this repository has issued you a badge! Here it is: https://holopin.io/claim/cmi4hz7rd000djs04wn4tt3ro

This badge can only be claimed by you, so make sure that your GitHub account is linked to your Holopin account. You can manage those preferences here: https://holopin.io/account.
Or if you're new to Holopin, you can simply sign up with GitHub, which will do the trick!

filintod added 2 commits July 28, 2025 21:32

initial

fdff6cf

Signed-off-by: Filinto Duran <[email protected]>

fixes after proto change upstream

bbf381c

Signed-off-by: Filinto Duran <[email protected]>

filintod marked this pull request as ready for review August 1, 2025 00:04

filintod requested review from a team as code owners August 1, 2025 00:04

filintod commented Aug 1, 2025

View reviewed changes

dapr/clients/base.py Show resolved Hide resolved

filintod added 2 commits July 31, 2025 20:09

minor name changes and cleanup unused function

dbf6f56

Signed-off-by: Filinto Duran <[email protected]>

refactors, updates to readme, linting

7a9a6cf

Signed-off-by: Filinto Duran <[email protected]>

acroca reviewed Aug 7, 2025

View reviewed changes

elena-kolevska requested changes Aug 7, 2025

View reviewed changes

examples/conversation/conversation_alpha2.py Show resolved Hide resolved

pyproject.toml Outdated Show resolved Hide resolved

examples/conversation/README.md Show resolved Hide resolved

filintod added 3 commits August 7, 2025 11:35

Merge branch 'main' into filinto/tool-calling

e412740

Merge branch 'main' into filinto/tool-calling

08fdcab

feedback

287d4b7

Signed-off-by: Filinto Duran <[email protected]>

filintod added 2 commits August 13, 2025 20:08

feedback, updates

b548c00

Signed-off-by: Filinto Duran <[email protected]>

fix import in examples

975df5d

Signed-off-by: Filinto Duran <[email protected]>

filintod commented Aug 14, 2025

View reviewed changes

tox.ini Show resolved Hide resolved

filintod added 4 commits August 14, 2025 08:15

cleanup, import, lint, more conversation helpers

6bbb0f5

Signed-off-by: Filinto Duran <[email protected]>

clarify README, minor test import changes, copyright

8697b8e

Signed-off-by: Filinto Duran <[email protected]>

feedback DRY test_conversation file

5d16fb5

Signed-off-by: Filinto Duran <[email protected]>

lint

d0703ae

Signed-off-by: Filinto Duran <[email protected]>

filintod requested a review from elena-kolevska August 14, 2025 17:12

filintod requested a review from acroca August 14, 2025 17:13

filintod added 2 commits August 16, 2025 09:11

move conversation classes in _response module to conversation module.

e10d2d8

Some example README refactor/lint Signed-off-by: Filinto Duran <[email protected]>

minor readme change

3854bbd

Signed-off-by: Filinto Duran <[email protected]>

filintod mentioned this pull request Aug 17, 2025

update for Dapr 1.16 conversation SDK Python quickstart dapr/quickstarts#1215

Merged

4 tasks

elena-kolevska requested changes Sep 3, 2025

View reviewed changes

Merge branch 'main' into filinto/tool-calling

6ae63f4

elena-kolevska added this to the v1.16 milestone Sep 3, 2025

filintod changed the base branch from main to release-1.16 September 3, 2025 14:23

filintod changed the base branch from release-1.16 to main September 3, 2025 14:24

filintod added 2 commits September 3, 2025 12:08

add tests to increase coverage in conversation and conversation_helpe…

1e3baec

…rs that codecov pointed out Signed-off-by: Filinto Duran <[email protected]>

add more information on execute registered tools, also added more tes…

924541c

…ts for them to validate Signed-off-by: Filinto Duran <[email protected]>

filintod requested a review from elena-kolevska September 3, 2025 17:40

elena-kolevska reviewed Sep 3, 2025

View reviewed changes

fix test failing on py 1.13. Merge two unit test files per feedback

9dd3bbf

Signed-off-by: Filinto Duran <[email protected]>

filintod requested a review from elena-kolevska September 4, 2025 00:53

Linter

5e1bab3

Signed-off-by: Elena Kolevska <[email protected]>

elena-kolevska requested changes Sep 4, 2025

View reviewed changes

fix typing issue with UnionType in py3.9

bc3dcf0

Signed-off-by: Filinto Duran <[email protected]>

filintod requested a review from elena-kolevska September 4, 2025 14:14

elena-kolevska approved these changes Sep 4, 2025

View reviewed changes

elena-kolevska merged commit 41f44c5 into dapr:main Sep 4, 2025
19 of 20 checks passed

filintod mentioned this pull request Sep 4, 2025

tool calling cherry-pick of PR 822 for tool calling in 1.16 #832

Merged

3 tasks

Add new tool calling capability #822

Add new tool calling capability #822

Uh oh!

Conversation

filintod commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issue reference

Checklist

Uh oh!

Uh oh!

filintod commented Aug 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elena-kolevska left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

filintod commented Aug 12, 2025

Uh oh!

elena-kolevska commented Aug 12, 2025

Uh oh!

elena-kolevska commented Aug 12, 2025

Uh oh!

Uh oh!

filintod commented Aug 14, 2025

Uh oh!

filintod commented Aug 30, 2025

Uh oh!

codecov bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

elena-kolevska left a comment

Choose a reason for hiding this comment

Uh oh!

elena-kolevska Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

elena-kolevska Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

elena-kolevska commented Sep 3, 2025

Uh oh!

filintod commented Sep 3, 2025

Uh oh!

elena-kolevska Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

filintod Sep 3, 2025

Choose a reason for hiding this comment

Uh oh!

filintod Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

elena-kolevska left a comment

Choose a reason for hiding this comment

Uh oh!

filintod commented Sep 4, 2025

Uh oh!

Uh oh!

elena-kolevska commented Sep 4, 2025

Uh oh!

marcduiker commented Nov 18, 2025

Uh oh!

holopin-bot bot commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

filintod commented Jul 29, 2025 •

edited

Loading

codecov bot commented Sep 3, 2025 •

edited

Loading