@devries-cameron20 / composio-1 / commits / 6bcac5beb
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(core): custom tools, toolkits, and extension tools for tool router sessions (#2877)

## Summary Add user-defined tools that execute locally (in-process) alongside Composio's remote tools in tool router sessions. Aligned with backend PR [hermes#8614](https://github.com/ComposioHQ/hermes/pull/8614). **Three ways to define custom tools:** 1. **Standalone** — no auth, no toolkit association → `LOCAL_<SLUG>` 2. **Extension** — extends a Composio toolkit, inherits its auth → `LOCAL_<TOOLKIT>_<SLUG>` 3. **Custom toolkit** — groups related no-auth tools → `LOCAL_<TOOLKIT>_<SLUG>` **Key capabilities:** - `experimental_createTool(slug, opts)` and `experimental_createToolkit(slug, opts)` factory functions - Tools indexed by backend for semantic search (BM25), returned to LLM via `COMPOSIO_SEARCH_TOOLS` - `session.execute()` routes custom tools in-process, remote tools to backend — accepts original slug, `LOCAL_`-prefixed slug, or lowercase - `COMPOSIO_MULTI_EXECUTE_TOOL` interception: splits custom/remote tools, executes in parallel, merges results - `SessionContext` injected at runtime: `userId`, `execute()` (with sibling local routing), `proxyExecute()` - Slug validation: alphanumeric/underscores/hyphens, no `LOCAL_` prefix, max 60 chars prefixed ## Usage ### Standalone tool (no auth) ```typescript import { experimental_createTool } from '@composio/core'; import { z } from 'zod/v3'; const getUserDetails = experimental_createTool('GET_USER_DETAILS', { name: 'Get user details', description: 'Retrieve user profile by ID', inputParams: z.object({ user_id: z.string() }), execute: async (input) => { return { id: input.user_id, name: 'Alice', role: 'admin' }; }, }); ``` ### Extension tool (inherits Composio toolkit auth) ```typescript const formatEmail = experimental_createTool('FORMAT_GMAIL_EMAIL', { name: 'Format Gmail email', description: 'Format an email draft with HTML formatting', extendsToolkit: 'gmail', inputParams: z.object({ to: z.string(), subject: z.string(), body: z.string() }), execute: async (input, session) => { return { formatted: true, to: input.to, html_body: input.body.replace(/\n/g, '<br>'), user_id: session.userId }; }, }); ``` ### Custom toolkit (groups no-auth tools) ```typescript import { experimental_createToolkit } from '@composio/core'; const setUserRole = experimental_createTool('SET_USER_ROLE', { name: 'Set user role', description: 'Change user role', inputParams: z.object({ user_id: z.string(), role: z.enum(['admin', 'developer', 'viewer']) }), execute: async (input) => ({ user_id: input.user_id, new_role: input.role }), }); const userManagement = experimental_createToolkit('USER_MANAGEMENT', { name: 'User Management', description: 'Tools for managing user profiles and roles', tools: [setUserRole], }); ``` ### Creating a session ```typescript const composio = new Composio({ apiKey, provider: new OpenAIAgentsProvider() }); const session = await composio.create('user_123', { toolkits: ['weathermap', 'gmail'], experimental: { customTools: [getUserDetails, formatEmail], customToolkits: [userManagement], }, }); ``` ### Executing tools ```typescript // Custom tool — runs in-process const r1 = await session.execute('GET_USER_DETAILS', { user_id: 'user-1' }); const r2 = await session.execute('LOCAL_GET_USER_DETAILS', { user_id: 'user-1' }); // prefixed const r3 = await session.execute('get_user_details', { user_id: 'user-1' }); // case-insensitive // Remote tool — identical API const weather = await session.execute('WEATHERMAP_WEATHER', { location: 'Tokyo' }); // Agent flow — SDK intercepts MULTI_EXECUTE, routes custom/remote in parallel const tools = await session.tools(); const agent = new Agent({ tools, model: 'gpt-5.2' }); ``` ## Backend API alignment Payload sent under `experimental`: - `custom_tools`: array of `{ slug, name, description, input_schema, output_schema?, extends_toolkit? }` - `custom_toolkits`: array of `{ slug, name, description, tools: [{ slug, name, description, input_schema }] }` Standalone tools omit `extends_toolkit`. Extension tools set `extends_toolkit` to a valid Composio toolkit slug. ## Files changed | File | Change | |---|---| | `types/customTool.types.ts` | `CustomToolSlugSchema`, `CreateCustomToolBaseSchema` (slug as 1st arg), `extendsToolkit`, `outputParams`, `CustomToolkit`, `CustomToolkitDefinition` | | `models/CustomTool.ts` | `createCustomTool(slug, opts)`, `createCustomToolkit(slug, opts)`, `buildCustomToolsMap(tools, toolkits?)`, `serializeCustomTools`, `serializeCustomToolkits` | | `types/toolRouter.types.ts` | `customTools`/`customToolkits` under `experimental`, `SessionProxyExecuteParams`, `proxyExecute` on Session | | `models/ToolRouter.ts` | Read from `experimental.customTools/customToolkits`, unified `experimental` payload | | `models/ToolRouterSession.ts` | Multi-execute interception, `session.execute()` routing, `proxyExecute()` | | `models/SessionContext.ts` | `proxyExecute()` implementation, sibling local tool routing | | `models/customToolExecution.ts` | Extracted `findCustomTool()`, `executeCustomTool()` | | `models/proxyParamsTransform.ts` | Transform SDK proxy params to backend format | | `index.ts` | `experimental_createTool`, `experimental_createToolkit` exports | | `experimental/index.ts` | `createCustomToolkit`, `CustomToolkit`, `CreateCustomToolkitParams` | | `docs/api/tool-router.md` | Custom tools section, `execute`/`search`/`proxyExecute` docs | | `examples/tool-router/src/custom-tools-agent.ts` | Full agent example with all 3 tool types | ## Test plan ### Unit tests (79 across 2 files) - `createCustomTool()`: slug validation (regex, no LOCAL_, invalid chars), `extendsToolkit`, `outputParams`, Zod to JSON Schema, execute signatures - `createCustomToolkit()`: validation, rejects tools with `extendsToolkit` - `buildCustomToolsMap()`: 3 prefix patterns, length validation, cross-group collision detection - `serializeCustomTools()`: `extends_toolkit` mapping, omit for standalone, `output_schema` - `serializeCustomToolkits()`: nested tool serialization - `SessionContextImpl`: userId, remote delegation, proxyExecute, sibling routing - `ToolRouter.create()`: payload under `experimental`, `extends_toolkit`, omit when empty - `session.execute()`: original/prefixed slug, case-insensitive, remote fallback, error handling, Zod defaults - `MULTI_EXECUTE split/merge`: all-local/all-remote/mixed batches, parallel execution, error merging, edge cases ### E2E tests - Node.js fixture (`ts/e2e-tests/runtimes/node/custom-tools/`) against live API - Focused E2E script: 18 tests covering all 3 tool types, search indexing, state mutations, error handling - Agent example (`ts/examples/tool-router/src/custom-tools-agent.ts`) verified against staging backend — standalone + extension + custom toolkit + remote tools in a single agent run 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Dhawal Upadhyay committed Mar 18, 2026 at 13:38 UTC 6bcac5beb80270732674e9cd23d1f3ace67c1ba9

No changes.