@devries-cameron20 / composio-1 / commits / 127e97688
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(python): custom tools decorator API for tool router sessions (#2973)

## Summary Port of the TypeScript custom tools feature (PR #2877) to the Python SDK with a Pythonic decorator API. Custom tools run in-process alongside remote Composio tools within a tool router session. ### API ```python from pydantic import BaseModel, Field from composio import Composio composio = Composio() class UserInput(BaseModel): user_id: str = Field(description="User ID") # 1. Standalone — slug/name/description inferred from function @composio.experimental.tool() def get_user(input: UserInput, ctx): """Look up an internal user by ID.""" return {"name": "Alice"} # slug=GET_USER, name=Get User, description from docstring # 2. With overrides @composio.experimental.tool(slug="GREET_V2", name="Greeting Generator") def greet(input: GreetInput, ctx): """Generate a greeting.""" return {"message": f"Hello {input.name}!"} # 3. Extension — inherits Gmail auth via ctx.proxy_execute() @composio.experimental.tool(extends_toolkit="gmail") def create_draft(input: DraftInput, ctx): """Create a Gmail draft.""" return ctx.proxy_execute(toolkit="gmail", endpoint="...", method="POST", body={...}) # 4. Toolkit — groups tools under a namespace role_manager = composio.experimental.Toolkit( slug="ROLE_MANAGER", name="Role Manager", description="Manage roles", ) @role_manager.tool() def set_role(input: SetRoleInput, ctx): """Set a user's role.""" return {"updated": True} @role_manager.tool(name="List All Roles") def list_roles(input: UserInput, ctx): """List available roles.""" return {"roles": ["admin", "developer", "viewer"]} # Session session = composio.create( user_id="default", toolkits=["gmail"], experimental={ "custom_tools": [get_user, greet, create_draft], "custom_toolkits": [role_manager], }, ) ``` ### Inference rules - **slug**: `fn.__name__.upper()` → `get_user` becomes `GET_USER` - **name**: `fn.__name__` humanized → `get_user` becomes `Get User` - **description**: `inspect.cleandoc(fn.__doc__)` — multi-line docstrings cleaned - **input_params**: first parameter with `BaseModel` type annotation - All overridable via `@tool(slug=..., name=..., description=...)` ### Implementation - Pydantic BaseModel for input schemas (runtime validation + defaults) - SessionContext with `execute()` (sibling routing) and `proxy_execute()` (auth proxy, with client-side validation) - `COMPOSIO_MULTI_EXECUTE_TOOL` routing: splits local/remote, parallel via ThreadPoolExecutor (max 5 workers), remotes first + locals appended (matches TS) - Strict function signature validation: `(input: BaseModel)` or `(input: BaseModel, ctx)` - Consistent `session.execute()` return type (dict with data/error/log_id for both local and remote) - Bumps composio-client to 1.29.0 ### Files **New:** `custom_tool.py`, `custom_tool_types.py`, `custom_tool_execution.py`, `session_context.py`, `test_custom_tools.py`, `custom_tools_agent_test.py` **Modified:** `tool_router.py`, `tool_router_session.py`, `sdk.py`, `__init__.py` files, `pyproject.toml` ## Test plan - [x] 52 unit tests + 68 existing tests + 8 import tests (zero regressions) - [x] 7 LLM agent e2e tests (OpenAI Agents SDK): standalone, overrides, toolkit, mixed local, remote weathermap, Gmail proxy, mixed all paths

Dhawal Upadhyay committed Mar 24, 2026 at 15:54 UTC 127e976887deb211be8f41c879f8badeaec50c41

No changes.