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

next
mdx 190 lines 7.61 KB
Raw
1 ---
2 title: Combine your own tools with Composio
3 description: Enrich a public Hacker News profile with an internal research note using remote and local tools in one agent.
4 keywords: [local tools, custom tools, preload, direct tools, python, typescript, hackernews]
5 gallery:
6 categories: [General agents]
7 logos: [hackernews]
8 featured: true
9 order: 10
10 ---
11
12 Build an agent that retrieves a Hacker News profile and adds a note from your own application. Composio executes the public lookup remotely. Your local tool reads the internal note in your process.
13
14 This follows the [TypeScript](https://github.com/ComposioHQ/composio/blob/next/ts/examples/tool-router/src/direct-tools-preset.ts) and [Python](https://github.com/ComposioHQ/composio/blob/next/python/examples/tool_router/direct_tools_preset.py) direct-tools examples. The task needs no connected account.
15
16 ## Install and configure
17
18 Use Python 3.12 or Node.js 24.17 or newer. Install in a new project, using a virtual environment for Python:
19
20 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
21 <Tab value="Python">
22 <PackageInstall packages="composio composio-openai-agents openai-agents pydantic" ecosystem="python" />
23 </Tab>
24 <Tab value="TypeScript">
25 <PackageInstall packages="@composio/core @composio/openai-agents @openai/agents zod" />
26 </Tab>
27 </Tabs>
28
29 Set your [Composio project key](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=examples-custom-tools) and [OpenAI key](https://platform.openai.com/api-keys):
30
31 ```bash
32 export COMPOSIO_API_KEY="your-composio-api-key"
33 export OPENAI_API_KEY="your-openai-api-key"
34 ```
35
36 ## Define the local tool and run the agent
37
38 The `HN_RESEARCH` toolkit contains one local tool. The direct-tools preset puts that tool and `HACKERNEWS_GET_USER` directly in the agent's tool list.
39
40 {/* code-example: no-api reason="Local tool runs in the SDK process inside an OpenAI Agents loop" */}
41 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
42 <Tab value="Python">
43
44 Save as `research.py`:
45
46 ```python title="research.py"
47 from agents import Agent, Runner
48 from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
49 from composio_openai_agents import OpenAIAgentsProvider
50 from pydantic import BaseModel, Field
51
52 composio = Composio(provider=OpenAIAgentsProvider())
53
54
55 class UserNoteInput(BaseModel):
56 username: str = Field(description="Hacker News username, for example pg")
57
58
59 research = composio.experimental.Toolkit(
60 slug="HN_RESEARCH",
61 name="Hacker News research",
62 description="Internal research notes for Hacker News users.",
63 )
64
65
66 @research.tool(slug="GET_USER_NOTE", name="Get internal research note")
67 def get_user_note(input: UserNoteInput, ctx):
68 """Return the internal research note for a Hacker News username."""
69 notes = {"pg": "Paul Graham; YC co-founder and essayist."}
70 return {"note": notes.get(input.username.lower(), "No internal note found.")}
71
72
73 session = composio.create(
74 user_id="custom-tools-demo",
75 session_preset=SESSION_PRESET_DIRECT_TOOLS,
76 toolkits=["hackernews"],
77 tools={"hackernews": {"enable": ["HACKERNEWS_GET_USER"]}},
78 experimental={"local_toolkits": [research]},
79 )
80 try:
81 tools = session.tools()
82 print("Available tools:", [tool.name for tool in tools])
83 agent = Agent(
84 name="Research agent",
85 model="gpt-5.2",
86 instructions="Use both tools. Distinguish public facts from internal notes.",
87 tools=tools,
88 )
89 result = Runner.run_sync(
90 agent,
91 "Look up pg on Hacker News and include our internal research note.",
92 max_turns=10,
93 )
94 print(result.final_output)
95 finally:
96 session.delete()
97 ```
98
99 ```bash
100 python research.py
101 ```
102
103 </Tab>
104 <Tab value="TypeScript">
105
106 Save as `research.ts`:
107
108 ```typescript title="research.ts"
109 import {
110 Composio, SessionPreset, experimental_createTool, experimental_createToolkit,
111 } from '@composio/core';
112 import { OpenAIAgentsProvider } from '@composio/openai-agents';
113 import { Agent, run } from '@openai/agents';
114 import { z } from 'zod/v3';
115
116 const getUserNote = experimental_createTool('GET_USER_NOTE', {
117 name: 'Get internal research note',
118 description: 'Return the internal research note for a Hacker News username.',
119 inputParams: z.object({ username: z.string() }),
120 execute: async ({ username }) => {
121 const notes: Record<string, string> = {
122 pg: 'Paul Graham; YC co-founder and essayist.',
123 };
124 return { note: notes[username.toLowerCase()] ?? 'No internal note found.' };
125 },
126 });
127 const research = experimental_createToolkit('HN_RESEARCH', {
128 name: 'Hacker News research',
129 description: 'Internal research notes for Hacker News users.',
130 tools: [getUserNote],
131 });
132 const composio = new Composio({ provider: new OpenAIAgentsProvider() });
133 const session = await composio.create('custom-tools-demo', {
134 sessionPreset: SessionPreset.DIRECT_TOOLS,
135 toolkits: ['hackernews'],
136 tools: { hackernews: { enable: ['HACKERNEWS_GET_USER'] } },
137 experimental: { localToolkits: [research] },
138 });
139 try {
140 const tools = await session.tools();
141 console.log('Available tools:', tools.map(tool => tool.name));
142 const agent = new Agent({
143 name: 'Research agent',
144 model: 'gpt-5.2',
145 instructions: 'Use both tools. Distinguish public facts from internal notes.',
146 tools,
147 });
148 const result = await run(
149 agent,
150 'Look up pg on Hacker News and include our internal research note.',
151 { maxTurns: 10 },
152 );
153 console.log(result.finalOutput);
154 } finally {
155 await session.delete();
156 }
157 ```
158
159 ```bash
160 node research.ts
161 ```
162
163 </Tab>
164 </Tabs>
165
166 The tool list should include `HACKERNEWS_GET_USER` and `LOCAL_HN_RESEARCH_GET_USER_NOTE`. It should not include `COMPOSIO_SEARCH_TOOLS`: the direct-tools preset exposes the allowed tools without a discovery step.
167
168 The answer should combine live profile information with the internal note about Paul Graham. Change `pg` to another username to see the local tool return `No internal note found.`
169
170 ## Preload selected tools while keeping discovery
171
172 Use the direct-tools preset when the agent's allowed tool set is small and known ahead of time. For a larger catalog, keep the default session behavior and preload only the tools you expect to need immediately.
173
174 The repository's [TypeScript preload example](https://github.com/ComposioHQ/composio/blob/next/ts/examples/tool-router/src/preload.ts) and [Python preload example](https://github.com/ComposioHQ/composio/blob/next/python/examples/tool_router/preload.py) demonstrate that alternative:
175
176 - `preload.tools` selects remote tools to expose immediately.
177 - `preload: true` on a local tool or toolkit exposes its local tools immediately.
178 - Other allowed tools remain discoverable through search.
179
180 See [preloading tools](/docs/configuring-sessions#preloading-tools) for the configuration in both languages. Preloading controls initial visibility; use the session's tool filters to restrict what the agent can access.
181
182 ## Replace the demo note with your application data
183
184 The local callback runs in your application process. It can query your database or call an internal service. Use the callback's `ctx.userId` in TypeScript or `ctx.user_id` in Python to enforce your application's access rules before returning records. An ID supplied by the model is not proof of authorization.
185
186 Keep the SDK tool execution in your process for this pattern. The [hosted MCP endpoint](/docs/sessions-via-mcp#trade-offs) can't invoke these in-process callbacks. Tool results still become model context, so return only the fields the model needs.
187
188 <Callout>
189 Local tools and toolkits are experimental. See [local tools and toolkits](/docs/extending-sessions/local-tools-and-toolkits) for extension tools, authenticated API calls, and callback context.
190 </Callout>