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 21, 03:37 UTC
| 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> |