@devries-cameron20 / composio Mirror · read-only / commits / ab602172e
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, 05:45 UTC

docs: rewrite tool type generator cookbook with session paradigm

Replace fragmented inline code snippets with a standalone example script using region markers and <include> tags. The script exposes three commands: list-tools, toolkit-info, and export. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Feb 25, 2026 at 19:16 UTC ab602172e5271339d50469eafc2462d39df0c4b2
2 files changed +151 -236
docs/content/cookbooks/tool-generator.mdx
+44 -236
@@ -1,273 +1,81 @@
1 ---
2 title: Tool Type Generator
3 -description: Build your own platform using raw tool definitions
3 +description: Build a platform on top of Composio using raw tool definitions and toolkit metadata
4 ---
5
6 -This is a bit of a checky tutorial as it is dogfooding the `docs` tool generation process.
6 +[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/tool-generator)
7
8 -To motivate this example clearly, in our tools section — we have details about let's say [`Github`](/toolkits/github) tool, that shows its auth scheme, actions and their params.
8 +This cookbook shows how to access the raw tool definitions and toolkit metadata that Composio exposes. If you are building a platform on top of Composio, say a workflow builder or an IDE plugin, you will need to display tool schemas, auth requirements, and input/output parameters to your users. This is how you get that data.
9
10 -Now why would anyone outside of Composio want to do this? Well if you are building a platform on top of Composio, perchance a Workflow builder like langflow. You would want to show some or all of this information to your users.
10 +## Prerequisites
11
12 -This is a non standard use case, that we support and love users building on top of us but if this is uninteresting to you, you can skip this tutorial.
12 +* Python 3.10+
13 +* [UV](https://docs.astral.sh/uv/getting-started/installation/)
14 +* [Composio API key](https://platform.composio.dev/settings)
15
14 -## How does one build a tool type generator?
16 +## Project setup
17
16 -In composio, we have two internal states for tools
17 -
18 -1. Raw tool definition
19 -2. Provider tool definition
20 -
21 -The raw tool definition is an generic input output schema definition that we internally for tools, we expose it for customers if they want to build on top of it but it is not the primary way tools are normally used.
22 -
23 -The provider tool definition, translates this raw tool definition to the specific schema of a provider (by default `openai`).
24 -
25 -For building something like this, we need to use the raw tool definition.
26 -
27 -
28 -## Getting the raw tool definition
29 -
30 -Of course, you need to initiate the `Composio` sdk first and use a `COMPOSIO_API_KEY` environment variable.
18 +Create a new project and install dependencies:
19
20 +```bash
21 +mkdir composio-tool-generator && cd composio-tool-generator
22 +uv init && uv add composio
23 +```
24
33 -```python Python {2} title="tool_doc_generator/main.py" maxLines=40 wordWrap
25 +Add your API key to a `.env` file:
26
35 - def __init__(self, include_local: bool = False):
36 - """
27 +```bash title=".env"
28 +COMPOSIO_API_KEY=your_composio_api_key
29 ```
30
31 +## Setting up the client
32
40 -Let us see an example output for a raw `GMAIL` toolkit, with all of its tools.
41 -
42 -this is just a taste but you can see the full output [here](https://github.com/composio-dev/composio/blob/next/fern/pages/src/examples/tool-generator/output.json).
43 -
44 -```json JSON title="output.json" maxLines=40
45 -[
46 - {
47 - "deprecated": {
48 - "available_versions": [
49 - "0_1",
50 - "latest",
51 - "latest:base"
52 - ],
53 - "display_name": "Modify email labels",
54 - "is_deprecated": false,
55 - "toolkit": {
56 - "logo": "https://cdn.jsdelivr.net/gh/ComposioHQ/open-logos@master/gmail.svg"
57 - },
58 - "version": "0_1",
59 - "displayName": "Modify email labels"
60 - },
61 - "description": "Adds and/or removes specified gmail labels for a message; ensure `message id` and all `label ids` are valid (use 'listlabels' for custom label ids).",
62 - "input_parameters": {
63 - "properties": {
64 - "add_label_ids": {
65 - "default": [],
66 - "description": "Label IDs to add. For custom labels, obtain IDs via 'listLabels'. System labels (e.g., 'INBOX', 'SPAM') can also be used.",
67 - "examples": [
68 - "STARRED",
69 - "IMPORTANT",
70 - "Label_123"
71 - ],
72 - "items": {
73 - "type": "string"
74 - },
75 - "title": "Add Label Ids",
76 - "type": "array"
77 - },
78 - "message_id": {
79 - "description": "Immutable ID of the message to modify (e.g., from 'fetchEmails' or 'fetchMessagesByThreadId').",
80 - "examples": [
81 - "17f1b2b9c1b2a3d4"
82 - ],
83 - "title": "Message Id",
84 - "type": "string"
85 - },
86 - "remove_label_ids": {
87 - "default": [],
88 - "description": "Label IDs to remove. For custom labels, obtain IDs via 'listLabels'. System labels can also be used.",
89 - "examples": [
90 - "UNREAD",
91 - "Label_456"
92 - ],
93 - "items": {
94 - "type": "string"
95 - },
96 - "title": "Remove Label Ids",
97 - "type": "array"
98 - },
99 - "user_id": {
100 - "default": "me",
101 - "description": "User's email address or 'me' for the authenticated user.",
102 - "examples": [
103 - "me",
104 - "user@example.com"
105 - ],
106 - "title": "User Id",
107 - "type": "string"
108 - }
109 - },
110 - "required": [
111 - "message_id"
112 - ],
113 - "title": "AddLabelToEmailRequest",
114 - "type": "object"
115 - },
116 - "name": "Modify email labels",
117 - "no_auth": false,
118 - "output_parameters": {
119 - "properties": {
120 - "data": {
121 - "description": "Data from the action execution",
122 - "properties": {
123 - "response_data": {
124 - "description": "Full `Message` resource with updated labels.",
125 - "title": "Response Data",
126 - "type": "object"
127 - }
128 - },
129 - "required": [
130 - "response_data"
131 - ],
132 - "title": "Data",
133 - "type": "object"
134 - },
135 - "error": {
136 - "anyOf": [
137 - {
138 - "type": "string"
139 - },
140 - {
141 - "type": "null"
142 - }
143 - ],
144 - "default": null,
145 -```
33 +No provider is needed here. We are reading tool metadata directly from the Composio API, not passing tools to an AI framework.
34
147 -```sh
148 -jq '.[0] | keys' pages/src/examples/tool-generator/output.json
149 -[
150 - "available_versions",
151 - "deprecated",
152 - "description",
153 - "input_parameters",
154 - "name",
155 - "no_auth",
156 - "output_parameters",
157 - "scopes",
158 - "slug",
159 - "tags",
160 - "toolkit",
161 - "version"
162 -]
163 -```
35 +<include>../../examples/tool-generator/main.py#setup</include>
36
165 -There is a bunch of useful information here, around the `input_parameters` and `output_parameters` for this example but `scopes` is very valuable to know what permissions are required for this tool.
37 +## Raw tool definitions
38
167 -Now from these `input_parameters` and `output_parameters` you can showcase the tool definitions.
39 +Composio has two internal representations for tools: **raw definitions** and **provider definitions**. Raw definitions are framework-agnostic JSON schemas with `input_parameters`, `output_parameters`, scopes, and tags. Provider definitions translate these into the format a specific framework expects (OpenAI, Anthropic, etc.).
40
41 +For building platform UIs, the raw definitions are what you want. `composio.tools.get_raw_composio_tools()` returns them for an entire toolkit. Each tool has a standard JSON Schema for its inputs and outputs, so you can render forms, validate user input, or generate types from it.
42
170 -```python Python title="tool_doc_generator/main.py" maxLines=40
171 - fields = []
172 - _, field_config = field
43 +<include>../../examples/tool-generator/main.py#list-tools</include>
44
174 - for field_list, required in [
175 - (getattr(field_config, "required", []), True),
176 - (getattr(field_config, "optional", []), False),
177 - ]:
178 - for f in field_list:
179 - if hasattr(f, "name"):
180 - fields.append(self._create_param_from_field(f, required))
181 -```
45 +## Toolkit metadata
46
183 -There is a bunch of other processing things happening here that are super generally relevant, so not going to call them out here that said there is another thing i want to showcase
47 +A toolkit groups related tools under one integration. `composio.toolkits.get()` returns metadata about the toolkit itself, including its supported auth schemes. Each auth scheme lists the fields required for two stages: creating an auth config (platform setup) and initiating a connected account (end-user connection). This is useful if you need to build your own auth configuration UI.
48
185 -## Toolkit Information
49 +<include>../../examples/tool-generator/main.py#toolkit-info</include>
50
187 -Toolkis are what we call apps or integrations, for us they are a collection of tools. `GMAIL` has `GMAIL_SEND_EMAIL` as a tool.
51 +## Exporting to JSON
52
189 -Now for building something out like this, you might also want information about the toolkit itself.
53 +For code generation or static analysis, you can export the full raw schemas to a JSON file. Each entry includes the `input_parameters` and `output_parameters` as standard JSON Schema objects, which you can feed into tools like `json-schema-to-typescript` or `datamodel-code-generator` to produce typed interfaces.
54
191 -A toolkit has information like `categories` or `auth_schemes`
55 +<include>../../examples/tool-generator/main.py#export</include>
56
193 -```python Python title="tool_doc_generator/main.py" maxLines=40
194 - """
195 - Initialize the tool documentation generator.
57 +## Complete script
58
197 - Args:
198 -```
59 +Here is everything together:
60
200 -`auth_schemes` here are `OAUTH2`, `API_KEY` or `BASIC_AUTH`, etc — essentially the types of how one could authenticate with the toolkit.
61 +<include>../../examples/tool-generator/main.py</include>
62
202 -```python Python title="tool_doc_generator/main.py" maxLines=40
203 - # Initialize composio client
204 - self.composio = Composio()
205 - self.include_local = include_local
63 +## Running the script
64
207 - # For tracking generated tools
208 - self.generated_tools = []
209 - self.problematic_actions = []
65 +List all tools in a toolkit:
66
211 - def generate_docs(
212 - self, output_path: Path, max_workers: int | None = None, limit: int | None = None
67 +```bash
68 +uv run --env-file .env python main.py list-tools gmail
69 ```
70
215 -Here is a way to parse the `auth_scheme` data
216 -
217 -
218 -these are `tuple` objects as they have different schema for specific conditions like `auth_config_creation` or `connected_account_initiation`
219 -
220 -they also have `required` and `optional` fields.
221 -
222 -the context here is there are some fields you need while creating an auth config and some you need while connecting an account. this separation is done by the `tuple` here
223 -
224 -```python Python title="tool_doc_generator/main.py" maxLines=40
225 - auth_schemes: t.Optional[t.List[toolkit_retrieve_response.AuthConfigDetail]] = None,
226 - ) -> None:
227 - schemes = ", ".join(
228 - self._get_auth_type(s) for s in (auth_schemes or []) if self._extract_auth_fields(s)
229 - )
230 - self._blocks.extend(
231 - [
232 - f"""## Connecting to {app_name}
233 -### Create an auth config
234 -Use the dashboard to create an auth config for the {app_name} toolkit. This allows you to connect multiple {app_name} accounts to Composio for agents to use.
235 -
236 -<Steps>
237 - <Step title="Select App">
238 - Navigate to **[{app_name}](https://platform.composio.dev?next_page=/marketplace/{app_name})**.
239 - </Step>
240 - <Step title="Configure Auth Config Settings">
241 - Select among the supported auth schemes of and configure them here.
242 - </Step>
243 - <Step title="Create and Get auth config ID">
244 - Click **"Create {app_name} Auth Config"**. After creation, **copy the displayed ID starting with `ac_`**. This is your auth config ID. This is _not_ a sensitive ID -- you can save it in environment variables or a database.
245 - **This ID will be used to create connections to the toolkit for a given user.**
246 - </Step>
247 -</Steps>
248 -"""
249 - ],
250 - )
251 -
252 - # Add auth code snippets
253 - self._add_auth_section(app_name, app_slug, auth_schemes)
254 -
255 - def _add_auth_section(
256 - self,
257 - app_name: str,
258 - app_slug: str,
259 - auth_schemes: t.List[toolkit_retrieve_response.AuthConfigDetail] = None,
260 - ) -> None:
261 - """Add code snippets for each auth scheme using direct template processing"""
262 - if not auth_schemes:
263 - return
264 -
265 - self._blocks.append("### Connect Your Account")
266 -
267 - # Group auth schemes by type to avoid duplicates
268 - seen_auth_types = set()
269 -
71 +Inspect a toolkit's auth schemes:
72 +
73 +```bash
74 +uv run --env-file .env python main.py toolkit-info gmail
75 ```
76
77 +Export raw tool schemas to a JSON file:
78
273 -This is a fairly minimal explanation for the amount of code, as most of it is not super related to composio but it will be a good example on seeing behind the scenes of how composio is working and how to leverage the platform further.
\ No newline at end of file
79 +```bash
80 +uv run --env-file .env python main.py export gmail tools.json
81 +```
docs/examples/tool-generator/main.py new
+107
@@ -0,0 +1,107 @@
1 +import json
2 +import sys
3 +
4 +# region setup
5 +from composio import Composio
6 +
7 +composio = Composio()
8 +# endregion setup
9 +
10 +
11 +# region list-tools
12 +def list_tools(toolkit_slug: str):
13 + """Fetch raw tool definitions for a toolkit and print them."""
14 + tools = composio.tools.get_raw_composio_tools(toolkits=[toolkit_slug])
15 +
16 + for tool in tools:
17 + print(f"\n--- {tool.slug} ---")
18 + print(f"Name: {tool.name}")
19 + print(f"Description: {tool.description}")
20 +
21 + required = tool.input_parameters.get("required", [])
22 + for name, schema in tool.input_parameters.get("properties", {}).items():
23 + tag = "required" if name in required else "optional"
24 + print(f" [{tag}] {name}: {schema.get('type', 'any')} - {schema.get('description', '')}")
25 +# endregion list-tools
26 +
27 +
28 +# region toolkit-info
29 +def toolkit_info(toolkit_slug: str):
30 + """Fetch toolkit metadata including auth schemes."""
31 + toolkit = composio.toolkits.get(toolkit_slug)
32 +
33 + print(f"Name: {toolkit.name}")
34 + print(f"Slug: {toolkit.slug}")
35 +
36 + if not toolkit.auth_config_details:
37 + print("Auth: none (no auth required)")
38 + return
39 +
40 + for scheme in toolkit.auth_config_details:
41 + print(f"\nAuth scheme: {scheme.mode}")
42 +
43 + creation_fields = scheme.fields.auth_config_creation
44 + print(" Auth config creation:")
45 + for field in creation_fields.required:
46 + print(f" [required] {field.name}: {field.description}")
47 + for field in creation_fields.optional:
48 + print(f" [optional] {field.name}: {field.description}")
49 +
50 + connection_fields = scheme.fields.connected_account_initiation
51 + print(" Account connection:")
52 + for field in connection_fields.required:
53 + print(f" [required] {field.name}: {field.description}")
54 + for field in connection_fields.optional:
55 + print(f" [optional] {field.name}: {field.description}")
56 +# endregion toolkit-info
57 +
58 +
59 +# region export
60 +def export(toolkit_slug: str, output_file: str):
61 + """Export raw tool definitions to a JSON file."""
62 + tools = composio.tools.get_raw_composio_tools(toolkits=[toolkit_slug])
63 +
64 + data = []
65 + for tool in tools:
66 + data.append({
67 + "slug": tool.slug,
68 + "name": tool.name,
69 + "description": tool.description,
70 + "input_parameters": tool.input_parameters,
71 + "output_parameters": tool.output_parameters,
72 + "scopes": getattr(tool, "scopes", []),
73 + "tags": getattr(tool, "tags", []),
74 + "no_auth": getattr(tool, "no_auth", False),
75 + })
76 +
77 + with open(output_file, "w") as f:
78 + json.dump(data, f, indent=2, default=str)
79 +
80 + print(f"Exported {len(data)} tools to {output_file}")
81 +# endregion export
82 +
83 +
84 +if __name__ == "__main__":
85 + if len(sys.argv) < 2:
86 + print("Usage:")
87 + print(" python main.py list-tools <toolkit>")
88 + print(" python main.py toolkit-info <toolkit>")
89 + print(" python main.py export <toolkit> <output.json>")
90 + sys.exit(1)
91 +
92 + command = sys.argv[1]
93 +
94 + if command == "list-tools":
95 + slug = sys.argv[2] if len(sys.argv) > 2 else "gmail"
96 + list_tools(slug)
97 + elif command == "toolkit-info":
98 + slug = sys.argv[2] if len(sys.argv) > 2 else "gmail"
99 + toolkit_info(slug)
100 + elif command == "export":
101 + slug = sys.argv[2] if len(sys.argv) > 2 else "gmail"
102 + out = sys.argv[3] if len(sys.argv) > 3 else "output.json"
103 + export(slug, out)
104 + else:
105 + print(f"Unknown command: {command}")
106 + print("Use 'list-tools', 'toolkit-info', or 'export'.")
107 + sys.exit(1)