feat(agents): Add ClientToolAction.from_function() for automatic action generation

[ks93]

🎯 Overview

Add ClientToolAction.from_function() method to automatically generate client tool actions from Python functions using type hints and docstrings. This significantly reduces boilerplate and improves developer experience.

🔗 Dependencies

⚠️ This PR is based on #2350 (feat/agents-actions-v2)

This PR should be merged after #2350 is merged into main.

✨ What's New

Feature: from_function() Class Method

Automatically generate action definitions from Python functions:

def add(a: float, b: float) -> float:
    """Add two numbers.
    
    Args:
        a: The first number.
        b: The second number.
    """
    return a + b

# Before: ~50 lines of manual JSON Schema definition
# After: One line!
action = ClientToolAction.from_function(add)

# Use in agent chat
response = client.agents.chat(
    agent_id="my_agent",
    messages=Message("What is 42 plus 58?"),
    actions=[action]
)

Supported Types

✅ Primitives: int, float, str, bool
✅ Lists: list[int], list[float], list[str], list[bool]
✅ Optional parameters: Parameters with = None are marked optional
✅ Custom names: Override action name via name parameter

Docstring Parsing

Supports Google-style docstrings:

• Function description becomes action description
• Parameter descriptions extracted from Args: section
• Multi-line descriptions supported

🏗️ Architecture

Refactoring: Moved to Utils Module

Following SDK best practices, introspection logic is now in a dedicated utility module:

New Files:

• cognite/client/utils/_function_introspection.py - Core introspection utilities
• tests/tests_unit/test_utils/test_function_introspection.py - 25 unit tests

Benefits:

• ✅ Reusable across SDK (not agent-specific)
• ✅ Better separation of concerns
• ✅ Easier to test and maintain
• ✅ Follows patterns like _text.py, _validation.py

No Dependencies Added

Keeps SDK lean - uses only Python stdlib:

• inspect - Function signature introspection
• typing - Type hint processing
• re - Docstring parsing

💡 Example Usage

Basic Example

def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

action = ClientToolAction.from_function(add)

With Optional Parameters

def greet(name: str, title: str | None = None) -> str:
    """Greet a person.
    
    Args:
        name: The person's name.
        title: Optional title (e.g., "Dr.", "Mr.").
    """
    if title:
        return f"Hello, {title} {name}!"
    return f"Hello, {name}!"

action = ClientToolAction.from_function(greet)
# name is required, title is optional

With Lists

def sum_numbers(numbers: list[float]) -> float:
    """Calculate sum of numbers.
    
    Args:
        numbers: List of numbers to sum.
    """
    return sum(numbers)

action = ClientToolAction.from_function(sum_numbers)

Custom Name

action = ClientToolAction.from_function(add, name="custom_add")

🔍 Design Decisions

1. Optional Parameters: Detected via = None default value
2. Missing Type Hints: Raises TypeError with clear message
3. Missing Docstring: Warns and uses function name as description
4. Unsupported Types: Raises TypeError with list of supported types
5. Bare list: Raises TypeError suggesting list[type]

🚀 Future Extensibility

The utility module is designed for easy extension:

• Add support for dict types
• Support Pydantic models
• Support other docstring formats (NumPy, Sphinx)
• Support nested types

[gemini-code-assist]

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

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.