Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | /** |
| 2 | * Custom Tools — local tools + proxy execute with OpenAI Agents |
| 3 | * |
| 4 | * Shows how to create custom tools that run in-process alongside |
| 5 | * remote Composio tools. Includes a tool that calls the Gmail API |
| 6 | * directly via ctx.proxyExecute(). |
| 7 | * |
| 8 | * Usage: |
| 9 | * COMPOSIO_API_KEY=... OPENAI_API_KEY=... bun src/custom-tools.ts |
| 10 | */ |
| 11 | import "dotenv/config"; |
| 12 | import { Composio, experimental_createTool, experimental_createToolkit } from "@composio/core"; |
| 13 | import { OpenAIAgentsProvider } from "@composio/openai-agents"; |
| 14 | import { Agent, run } from "@openai/agents"; |
| 15 | import { z } from "zod/v3"; |
| 16 | |
| 17 | // ── Custom tools ──────────────────────────────────────────────── |
| 18 | |
| 19 | /** Standalone tool (no auth needed) */ |
| 20 | const getUser = experimental_createTool("GET_USER", { |
| 21 | name: "Get user", |
| 22 | description: "Look up an internal user by ID", |
| 23 | inputParams: z.object({ |
| 24 | user_id: z.string().describe("User ID (e.g. user-1)"), |
| 25 | }), |
| 26 | execute: async ({ user_id }) => { |
| 27 | const users: Record<string, Record<string, string>> = { |
| 28 | "user-1": { name: "Alice Johnson", email: "alice@acme.com", role: "admin" }, |
| 29 | "user-2": { name: "Bob Smith", email: "bob@acme.com", role: "developer" }, |
| 30 | }; |
| 31 | const user = users[user_id]; |
| 32 | if (!user) throw new Error(`User "${user_id}" not found`); |
| 33 | return user; |
| 34 | }, |
| 35 | }); |
| 36 | |
| 37 | /** Extension tool — inherits Gmail auth, calls the real API via proxy */ |
| 38 | const createDraft = experimental_createTool("CREATE_DRAFT", { |
| 39 | name: "Create Gmail draft", |
| 40 | description: "Create a real Gmail draft via the Gmail API. Appears in the user's drafts folder.", |
| 41 | extendsToolkit: "gmail", |
| 42 | inputParams: z.object({ |
| 43 | to: z.string().describe("Recipient email address"), |
| 44 | subject: z.string().describe("Email subject"), |
| 45 | body: z.string().describe("Email body (plain text)"), |
| 46 | }), |
| 47 | execute: async (input, ctx) => { |
| 48 | const raw = Buffer.from( |
| 49 | `To: ${input.to}\r\nSubject: ${input.subject}\r\nContent-Type: text/plain; charset=UTF-8\r\n\r\n${input.body}` |
| 50 | ) |
| 51 | .toString("base64") |
| 52 | .replace(/\+/g, "-") |
| 53 | .replace(/\//g, "_") |
| 54 | .replace(/=+$/, ""); |
| 55 | |
| 56 | const res = await ctx.proxyExecute({ |
| 57 | toolkit: "gmail", |
| 58 | endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/drafts", |
| 59 | method: "POST", |
| 60 | body: { message: { raw } }, |
| 61 | }); |
| 62 | |
| 63 | // A session hook can block the request; it then has no HTTP response. |
| 64 | if (res.resultType === "blocked") throw new Error(res.message); |
| 65 | if (res.status !== 200) throw new Error(`Gmail API error ${res.status}`); |
| 66 | const data = res.data as { id: string; message: { id: string } }; |
| 67 | return { draft_id: data.id, message_id: data.message.id, to: input.to, subject: input.subject }; |
| 68 | }, |
| 69 | }); |
| 70 | |
| 71 | /** Custom toolkit — groups related tools under one namespace */ |
| 72 | const roleManager = experimental_createToolkit("ROLE_MANAGER", { |
| 73 | name: "Role Manager", |
| 74 | description: "Manage user roles", |
| 75 | tools: [ |
| 76 | experimental_createTool("SET_ROLE", { |
| 77 | name: "Set role", |
| 78 | description: "Set a user's role", |
| 79 | inputParams: z.object({ |
| 80 | user_id: z.string().describe("User ID"), |
| 81 | role: z.enum(["admin", "developer", "viewer"]).describe("New role"), |
| 82 | }), |
| 83 | execute: async ({ user_id, role }) => ({ user_id, role, updated: true }), |
| 84 | }), |
| 85 | ], |
| 86 | }); |
| 87 | |
| 88 | // ── Agent ──────────────────────────────────────────────────────── |
| 89 | |
| 90 | const composio = new Composio({ |
| 91 | provider: new OpenAIAgentsProvider(), |
| 92 | }); |
| 93 | |
| 94 | const session = await composio.create("default", { |
| 95 | toolkits: ["gmail"], |
| 96 | experimental: { |
| 97 | localTools: [getUser, createDraft], |
| 98 | localToolkits: [roleManager], |
| 99 | }, |
| 100 | }); |
| 101 | |
| 102 | const tools = await session.tools(); |
| 103 | |
| 104 | const agent = new Agent({ |
| 105 | name: "Assistant", |
| 106 | instructions: |
| 107 | "You are a helpful assistant. Use Composio tools to execute tasks. " + |
| 108 | "In MULTI_EXECUTE, always pass arguments inside the arguments field.", |
| 109 | model: "gpt-4.1", |
| 110 | tools, |
| 111 | }); |
| 112 | |
| 113 | const prompt = process.argv[2] ?? "Get user-1's info and draft an email to them saying hello"; |
| 114 | |
| 115 | console.log(`> ${prompt}\n`); |
| 116 | const result = await run(agent, prompt); |
| 117 | console.log(result.finalOutput); |