feat: add reasoning decorator to browser toolkit

[YunfeiZHAO]

Description

#3494
A decorator that enhances toolkit functions with reasoning capabilities by automatically adding a reason parameter and field to function signatures and return values, it will also update the function docstring for Args and Returns.
Enables agents to provide explanations for their tool usage, improving transparency and debuggability of agent actions.

Features

• Automatic Signature Modification: Adds an reason: str = "" keyword-only parameter to the decorated function
• Dynamic Documentation: Automatically updates the function's docstring to include:
  • reason parameter in the Args section
  • reason field in the Returns section
• Return Value Enhancement: Wraps the original function to inject the reason value into the returned dictionary
• Type Safety: Only applies to functions with Dict return type annotations; gracefully skips non-dict functions with a log message

Usage

@add_reason_field
async def some_tool_function() -> Dict[str, Any]:
    return {"status": "success"}

# After decoration:
# - Signature includes: reason: str = ""
# - Return value will include: {"status": "success", "reason": "..."}

example

examples/toolkits/browser_toolkit_with_reasoning.ipynb

Checklist

Go over all the following points, and put an x in all the boxes that apply.

• I have read the CONTRIBUTION guide (required)
• I have linked this PR to an issue using the Development section on the right sidebar or by adding Fixes #issue-number in the PR description (required)
• I have checked if any dependencies need to be added or updated in pyproject.toml and uv lock
• I have updated the tests accordingly (required for a bug fix or a new feature)
• I have updated the documentation if needed:
• I have added examples if this is a new feature

If you are unsure about any of these, don't hesitate to ask. We are here to help!

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/browser_toolkit_reasoning_decorator

---

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.}

[fengju0213]

@YunfeiZHAO thanks！ when this pr ready，feel free re-open it and we will review it！

[lightaime]

Thanks @YunfeiZHAO for the PR. A few comments:

1. Should we put reason to be the first arg since reason shoud generate before the agent action?
2. Why do we need reason in the return? It is already in the context as an input arg. If we also add it to the return it would double to token consumption without information gain.

c.c. @Wendong-Fan @nitpicker55555

[Wendong-Fan]

discussed with @nitpicker55555 , this is a testing PR, we can close this

cc @YunfeiZHAO