@devries-cameron20 / composio Mirror · read-only / commits / 06abd13c3
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 02:00 UTC

docs: add python custom tools references

Dhawal Upadhyay committed Mar 25, 2026 at 16:29 UTC 06abd13c370e2c83549d705106bfb3e9cd8b16c5
6 files changed +254 -4
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+3 -3
@@ -227,13 +227,13 @@ For more best practices, see [How to Build Tools for AI Agents: A Field Guide](h
227
228 Use `session.customTools()` / `session.customToolkits()` in TypeScript or `session.custom_tools()` / `session.custom_toolkits()` in Python to list registered tools and toolkits. Registered tool slugs include their final `LOCAL_` prefix, and toolkit-scoped tools also include the toolkit slug.
229
230 -Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python SDK Reference](/reference/sdk-reference/python)
230 +Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python ToolRouterSession](/reference/sdk-reference/python/tool-router-session)
231
232 ## Programmatic execution
233
234 Use `session.execute()` to run custom tools directly, outside of an agent loop (e.g. `session.execute("GET_USER_PROFILE")`). Custom tools execute in-process; remote tools are sent to the backend automatically.
235
236 -Reference: [Tool Router API Reference](/reference/api-reference/tool-router) · [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python SDK Reference](/reference/sdk-reference/python)
236 +Reference: [TypeScript ToolRouterSession](/reference/sdk-reference/typescript/tool-router-session) · [Python ToolRouterSession](/reference/sdk-reference/python/tool-router-session)
237
238 ## SessionContext
239
@@ -262,4 +262,4 @@ Every custom tool's `execute` function receives `(input, ctx)`. The `ctx` object
262
263 In Python, `parameters` dictionaries accept both `in` and `type`; this guide uses `in` to match the TypeScript examples.
264
265 -Reference: [TypeScript SessionContextImpl](/reference/sdk-reference/typescript/session-context-impl) · [Python SDK Reference](/reference/sdk-reference/python)
265 +Reference: [TypeScript SessionContextImpl](/reference/sdk-reference/typescript/session-context-impl) · [Python SessionContextImpl](/reference/sdk-reference/python/session-context-impl)
docs/content/reference/sdk-reference/python/index.mdx
+2
@@ -30,6 +30,8 @@ uv add composio
30 | [`ConnectedAccounts`](/reference/sdk-reference/python/connected-accounts) | Manage connected accounts. This class is used to manage connected accounts in t... |
31 | [`AuthConfigs`](/reference/sdk-reference/python/auth-configs) | Manage authentication configurations. |
32 | [`MCP`](/reference/sdk-reference/python/mcp) | MCP (Model Control Protocol) class. Provides enhanced MCP server operations Thi... |
33 +| [`ToolRouterSession`](/reference/sdk-reference/python/tool-router-session) | Tool router session containing session information and methods. Generic Paramet... |
34 +| [`SessionContextImpl`](/reference/sdk-reference/python/session-context-impl) | Concrete implementation of SessionContext. One instance is created per session ... |
35
36 ## Quick Start
37
docs/content/reference/sdk-reference/python/meta.json
+3 -1
@@ -7,6 +7,8 @@
7 "triggers",
8 "connected-accounts",
9 "auth-configs",
10 - "mcp"
10 + "mcp",
11 + "tool-router-session",
12 + "session-context-impl"
13 ]
14 }
\ No newline at end of file
docs/content/reference/sdk-reference/python/session-context-impl.mdx new
+53
@@ -0,0 +1,53 @@
1 +---
2 +title: SessionContextImpl
3 +description: Concrete implementation of SessionContext. One instance is created per session (singleton) and shared across all custom tool invocations. When ``c...
4 +---
5 +
6 +## Methods
7 +
8 +### execute()
9 +
10 +Execute any tool from within a custom tool. Routes to sibling local tools in-process when available, otherwise delegates to the backend API. Returns the same response model as ``session.execute()``.
11 +
12 +```python
13 +def execute(tool_slug: str, arguments: Dict[str, Any]) -> SessionExecuteResponse
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `tool_slug` | `str` |
21 +| `arguments` | `Dict[str, Any]` |
22 +
23 +**Returns**
24 +
25 +`SessionExecuteResponse`
26 +
27 +---
28 +
29 +### proxy_execute()
30 +
31 +Proxy API calls through Composio's auth layer. Returns the same response model as ``session.proxy_execute()``.
32 +
33 +```python
34 +def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> SessionProxyExecuteResponse
35 +```
36 +
37 +**Parameters**
38 +
39 +| Name | Type |
40 +|------|------|
41 +| `toolkit` | `str` |
42 +| `endpoint` | `str` |
43 +| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |
44 +| `body?` | `Any` |
45 +| `parameters?` | `List[Dict[str, Any \| None]]` |
46 +
47 +**Returns**
48 +
49 +`SessionProxyExecuteResponse`
50 +
51 +---
52 +
53 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/session_context.py#L87)
docs/content/reference/sdk-reference/python/tool-router-session.mdx new
+165
@@ -0,0 +1,165 @@
1 +---
2 +title: ToolRouterSession
3 +description: "Tool router session containing session information and methods. Generic Parameters: TTool: The individual tool type returned by the provider. TToo..."
4 +---
5 +
6 +## Methods
7 +
8 +### tools()
9 +
10 +Get provider-wrapped tools for execution with your AI framework. Returns tools configured for this session, wrapped in the format expected by your AI provider (OpenAI, Anthropic, LangChain, etc.). When custom tools are bound to the session, execution of COMPOSIO_MULTI_EXECUTE_TOOL is intercepted: local tools are executed in-process, remote tools are sent to the backend.
11 +
12 +```python
13 +def tools(modifiers: 'Modifiers' | None = ...) -> TToolCollection
14 +```
15 +
16 +**Parameters**
17 +
18 +| Name | Type |
19 +|------|------|
20 +| `modifiers?` | `'Modifiers' \| None` |
21 +
22 +**Returns**
23 +
24 +`TToolCollection`
25 +
26 +---
27 +
28 +### authorize()
29 +
30 +Authorize a toolkit for the user and get a connection request. Initiates the OAuth flow and returns a ConnectionRequest with redirect URL.
31 +
32 +```python
33 +def authorize(toolkit: str, callback_url: str | None = ...) -> ConnectionRequest
34 +```
35 +
36 +**Parameters**
37 +
38 +| Name | Type |
39 +|------|------|
40 +| `toolkit` | `str` |
41 +| `callback_url?` | `str \| None` |
42 +
43 +**Returns**
44 +
45 +`ConnectionRequest`
46 +
47 +---
48 +
49 +### toolkits()
50 +
51 +Get toolkit connection states for the session.
52 +
53 +```python
54 +def toolkits(toolkits: List[str | None] = ..., next_cursor: str | None = ..., limit: int | None = ..., is_connected: bool | None = ..., search: str | None = ...)
55 +```
56 +
57 +**Parameters**
58 +
59 +| Name | Type |
60 +|------|------|
61 +| `toolkits?` | `List[str \| None]` |
62 +| `next_cursor?` | `str \| None` |
63 +| `limit?` | `int \| None` |
64 +| `is_connected?` | `bool \| None` |
65 +| `search?` | `str \| None` |
66 +
67 +---
68 +
69 +### search()
70 +
71 +Search for tools by semantic use case. Returns relevant tools for the given query with schemas and guidance.
72 +
73 +```python
74 +def search(query: str, model: str | None = ...)
75 +```
76 +
77 +**Parameters**
78 +
79 +| Name | Type |
80 +|------|------|
81 +| `query` | `str` |
82 +| `model?` | `str \| None` |
83 +
84 +---
85 +
86 +### execute()
87 +
88 +Execute a tool within the session. For custom tools, accepts the original slug (e.g. "GREP") or the full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process; remote tools are sent to the Composio backend. Both paths return a ``SessionExecuteResponse`` with ``data``, ``error``, and ``log_id`` attributes.
89 +
90 +```python
91 +def execute(tool_slug: str, arguments: Dict[str, Any | None] = ...) -> SessionExecuteResponse
92 +```
93 +
94 +**Parameters**
95 +
96 +| Name | Type |
97 +|------|------|
98 +| `tool_slug` | `str` |
99 +| `arguments?` | `Dict[str, Any \| None]` |
100 +
101 +**Returns**
102 +
103 +`SessionExecuteResponse`
104 +
105 +---
106 +
107 +### custom_tools()
108 +
109 +List all custom tools registered in this session. Returns tools with their final slugs, schemas, and resolved toolkit.
110 +
111 +```python
112 +def custom_tools(toolkit: str | None = ...) -> List[RegisteredCustomTool]
113 +```
114 +
115 +**Parameters**
116 +
117 +| Name | Type |
118 +|------|------|
119 +| `toolkit?` | `str \| None` |
120 +
121 +**Returns**
122 +
123 +`List[RegisteredCustomTool]` — Array of registered custom tools
124 +
125 +---
126 +
127 +### custom_toolkits()
128 +
129 +List all custom toolkits registered in this session. Returns toolkits with their tools showing final slugs.
130 +
131 +```python
132 +def custom_toolkits() -> List[RegisteredCustomToolkit]
133 +```
134 +
135 +**Returns**
136 +
137 +`List[RegisteredCustomToolkit]`
138 +
139 +---
140 +
141 +### proxy_execute()
142 +
143 +Proxy an API call through Composio's auth layer.
144 +
145 +```python
146 +def proxy_execute(toolkit: str, endpoint: str, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], body: Any = ..., parameters: List[Dict[str, Any | None]] = ...) -> SessionProxyExecuteResponse
147 +```
148 +
149 +**Parameters**
150 +
151 +| Name | Type |
152 +|------|------|
153 +| `toolkit` | `str` |
154 +| `endpoint` | `str` |
155 +| `method` | `Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']` |
156 +| `body?` | `Any` |
157 +| `parameters?` | `List[Dict[str, Any \| None]]` |
158 +
159 +**Returns**
160 +
161 +`SessionProxyExecuteResponse` — Proxied API response
162 +
163 +---
164 +
165 +[View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/tool_router_session.py#L47)
python/scripts/generate-docs.py
+28
@@ -52,6 +52,13 @@ EXPECTED_CLASSES = {
52 "MCP": "mcp",
53 }
54
55 +# Additional public-facing classes worth documenting even though they are not
56 +# exposed as direct properties on ``Composio``.
57 +ADDITIONAL_CLASSES = {
58 + "ToolRouterSession": "core.models.tool_router_session",
59 + "SessionContextImpl": "core.models.session_context",
60 +}
61 +
62 # Modules to search for classes
63 CLASS_MODULES = [
64 "core.models.tools",
@@ -491,6 +498,27 @@ def main():
498 except (KeyError, AttributeError):
499 continue
500
501 + # Add standalone public-facing classes that are not surfaced via a direct
502 + # ``composio.<property>`` access pattern.
503 + for class_name, module_name in ADDITIONAL_CLASSES.items():
504 + try:
505 + parts = module_name.split(".")
506 + current = package
507 + for part in parts:
508 + current = current.members[part]
509 +
510 + if class_name in current.members:
511 + cls = current.members[class_name]
512 + if isinstance(cls, griffe.Class):
513 + classes_to_doc[class_name] = {
514 + "cls": cls,
515 + "access": None,
516 + "prop": None,
517 + }
518 + print(f" Found {class_name}")
519 + except (KeyError, AttributeError):
520 + continue
521 +
522 # Generate docs for each class
523 documented_classes = []
524