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, 13:15 UTC
docs(openai-agents): Complete page restructure with MCP code
- Add MCP Python and TypeScript code examples - Add Direct tool usage and Direct MCP usage accordions - Remove old content section - Change headings to bold text to clean up TOC Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 23, 2026 at 17:58 UTC
993a7c385780fd9a830f56676938d79b58751724
1 file changed
+171
-302
docs/content/docs/providers/openai-agents.mdx
+171
-302
@@ -9,7 +9,7 @@ keywords: [agents sdk]
9
<ToolTypeOption id="native" name="Native Tools" icon="native">
10
<Steps>
11
<Step>
12
-### Install
12
+**Install**
13
14
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
15
<Tab value="Python">
@@ -26,7 +26,7 @@ npm install dotenv @composio/core @composio/openai-agents @openai/agents
26
</Step>
27
28
<Step>
29
-### Configure API Keys
29
+**Configure API Keys**
30
31
<Callout type="info">
32
Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `OPENAI_API_KEY` with your [OpenAI API key](https://platform.openai.com/api-keys).
@@ -39,7 +39,7 @@ OPENAI_API_KEY=xxxxxxxxx
39
</Step>
40
41
<Step>
42
-### Create session and run agent
42
+**Create session and run agent**
43
44
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
45
<Tab value="Python">
@@ -131,7 +131,7 @@ if (result.finalOutput) {
131
<ToolTypeOption id="mcp" name="MCP" icon="mcp">
132
<Steps>
133
<Step>
134
-### Install
134
+**Install**
135
136
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
137
<Tab value="Python">
@@ -141,14 +141,14 @@ pip install composio openai-agents
141
</Tab>
142
<Tab value="TypeScript">
143
```bash
144
-npm install @composio/core @openai/agents
144
+npm install dotenv @composio/core @openai/agents
145
```
146
</Tab>
147
</Tabs>
148
</Step>
149
150
<Step>
151
-### Configure API Keys
151
+**Configure API Keys**
152
153
<Callout type="info">
154
Set `COMPOSIO_API_KEY` with your API key from [Settings](https://platform.composio.dev/?next_page=/settings) and `OPENAI_API_KEY` with your [OpenAI API key](https://platform.openai.com/api-keys).
@@ -161,392 +161,258 @@ OPENAI_API_KEY=xxxxxxxxx
161
</Step>
162
163
<Step>
164
-### Create session and run agent
165
-
166
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
167
-<Tab value="Python">
168
-```python
169
-# TODO: MCP Python code
170
-```
171
-</Tab>
172
-<Tab value="TypeScript">
173
-```typescript
174
-// TODO: MCP TypeScript code
175
-```
176
-</Tab>
177
-</Tabs>
178
-</Step>
179
-</Steps>
180
-</ToolTypeOption>
181
-
182
-</ToolTypeFlow>
183
-
184
-<Accordions>
185
-<Accordion title="Direct tool usage">
186
-TODO: Direct tool usage content
187
-</Accordion>
188
-
189
-<Accordion title="Direct MCP usage">
190
-TODO: Direct MCP usage content
191
-</Accordion>
192
-</Accordions>
193
-
194
----
195
-
196
-## Old Content (to be removed)
197
-
198
-The OpenAI Agents Provider is a provider that formats the Composio tools into an object compatible with OpenAI's Agents API.
199
-
200
-OpenAI Agents SDK is different from the OpenAI SDK. It helps build agentic AI apps in a lightweight, easy-to-use package with very few abstractions.
201
-
202
-## Usage with Tools
203
-
204
-Use Composio Tool Router as a native tool with the OpenAI Agents SDK.
205
-
206
-### Installation
207
-
208
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
209
-<Tab value="Python">
210
-```bash
211
-pip install python-dotenv composio composio-openai-agents openai-agents
212
-```
213
-</Tab>
214
-<Tab value="TypeScript">
215
-```bash
216
-npm install @composio/core @composio/openai-agents @openai/agents
217
-```
218
-</Tab>
219
-</Tabs>
220
-
221
-### Usage
222
-
223
-Create a Tool Router session and use it as a native tool with OpenAI Agents SDK:
224
-
225
-<Callout type="info">
226
-- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
227
-- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
228
-</Callout>
164
+**Create session and run agent**
165
166
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
167
<Tab value="Python">
168
```python
169
+import asyncio
170
from dotenv import load_dotenv
171
+load_dotenv()
172
+
173
from composio import Composio
235
-from agents import Agent, Runner, SQLiteSession
236
-from composio_openai_agents import OpenAIAgentsProvider
174
+from agents import Agent, Runner, HostedMCPTool
175
238
-load_dotenv()
176
+# Initialize Composio
177
+composio = Composio()
178
240
-# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
241
-composio = Composio(provider=OpenAIAgentsProvider())
179
+external_user_id = "user_2nFh83Hde"
180
+recipient_email = "soham.g@composio.dev"
181
243
-# Unique identifier of the user
244
-user_id = "user_123"
182
+# Create a session
183
+session = composio.create(user_id=external_user_id)
184
246
-# Create a session and get native tools for the user
247
-session = composio.create(user_id=user_id)
248
-tools = session.tools()
185
+# Create MCP tool
186
+composio_mcp = HostedMCPTool(
187
+ tool_config={
188
+ "type": "mcp",
189
+ "server_label": "composio",
190
+ "server_url": session.mcp.url,
191
+ "require_approval": "never",
192
+ "headers": session.mcp.headers,
193
+ }
194
+)
195
250
-# Configure OpenAI agent with Composio tools
196
+# Create agent with MCP tool
197
agent = Agent(
252
- name="Personal Assistant",
253
- instructions="You are a helpful personal assistant. Use Composio tools to take action.",
254
- model="gpt-5.2",
255
- tools=tools,
198
+ name="Email Manager",
199
+ instructions="You are a helpful assistant.",
200
+ tools=[composio_mcp],
201
)
202
258
-# Memory for multi-turn conversation
259
-memory = SQLiteSession("conversation")
260
-
261
-# Execute an initial task
262
-print("Fetching GitHub issues from the Composio repository...\n")
263
-try:
264
- result = Runner.run_sync(
203
+# Run the agent
204
+async def main():
205
+ result = await Runner.run(
206
starting_agent=agent,
266
- input="Fetch all the open GitHub issues on the @ComposioHQ/composio repository and group them by bugs/features/docs.",
267
- session=memory,
207
+ input=f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'",
208
)
269
- print(f"{result.final_output}\n")
270
-except Exception as e:
271
- print(f"[Error]: {e}")
272
-
273
-# Continue with interactive conversation
274
-print("\nWhat else would you like me to do? (Type 'exit' to exit)")
275
-
276
-while True:
277
- user_input = input("You: ").strip()
278
- if user_input.lower() == "exit":
279
- break
280
-
281
- print("Assistant: ", end="", flush=True)
282
- try:
283
- result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
284
- print(f"{result.final_output}\n")
285
- except Exception as e:
286
- print(f"\n[Error]: {e}")
209
+ print(result.final_output)
210
+
211
+asyncio.run(main())
212
```
213
</Tab>
214
<Tab value="TypeScript">
215
```typescript
216
import "dotenv/config";
217
import { Composio } from "@composio/core";
293
-import { Agent, run, MemorySession } from "@openai/agents";
294
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
295
-import { createInterface } from "readline/promises";
218
+import { Agent, run, hostedMcpTool } from "@openai/agents";
219
297
-// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
298
-const composio = new Composio({ provider: new OpenAIAgentsProvider() });
220
+// Initialize Composio
221
+const composio = new Composio();
222
300
-// Unique identifier of the user
301
-const userId = "user_123";
223
+const externalUserId = "user_2nFh83Hde";
224
+const recipientEmail = "soham.g@composio.dev";
225
303
-// Create a session and get native tools for the user
304
-const session = await composio.create(userId);
305
-const tools = await session.tools();
226
+// Create a session
227
+const session = await composio.create(externalUserId);
228
229
+// Create agent with MCP tool
230
const agent = new Agent({
308
- name: "Personal Assistant",
309
- instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
310
- model: "gpt-5.2",
311
- tools,
231
+ name: "Email Manager",
232
+ instructions: "You are a helpful assistant.",
233
+ tools: [
234
+ hostedMcpTool({
235
+ serverLabel: "composio",
236
+ serverUrl: session.mcp.url,
237
+ headers: session.mcp.headers,
238
+ }),
239
+ ],
240
});
241
314
-// Create a memory session for persistent multi-turn conversation
315
-const memory = new MemorySession();
316
-
317
-// Execute an initial task
318
-console.log("Fetching GitHub issues from the Composio repository...\n");
319
-try {
320
- const initialResult = await run(
321
- agent,
322
- "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
323
- { session: memory }
324
- );
325
- console.log(`${initialResult.finalOutput}\n`);
326
-} catch (error) {
327
- console.error("[Error]:", error instanceof Error ? error.message : error);
328
-}
329
-
330
-// Continue with interactive conversation
331
-const readline = createInterface({ input: process.stdin, output: process.stdout });
332
-
333
-console.log(`
334
-What else would you like me to do?
335
-(Type 'exit' to exit)
336
-`);
337
-
338
-
339
-while (true) {
340
- const input = (await readline.question("You: ")).trim();
341
- if (input.toLowerCase() === "exit") break;
342
-
343
- console.log("Assistant: ");
242
+// Run the agent
243
+console.log("Running agent...");
244
+const result = await run(
245
+ agent,
246
+ `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`
247
+);
248
345
- try {
346
- const result = await run(agent, input, { session: memory });
347
- console.log(`${result.finalOutput}\n`);
348
- } catch (error) {
349
- console.error("\n[Error]:", error instanceof Error ? error.message : error);
350
- }
249
+console.log("Received response from agent");
250
+if (result.finalOutput) {
251
+ console.log(result.finalOutput);
252
}
352
-readline.close();
253
```
254
</Tab>
255
</Tabs>
256
+</Step>
257
+</Steps>
258
+</ToolTypeOption>
259
357
-## Usage with MCP
260
+</ToolTypeFlow>
261
359
-Use Composio Tool Router with the OpenAI Agents SDK for a fully managed MCP experience.
262
+<Accordions>
263
+<Accordion title="Direct tool usage">
264
+<Callout type="info">
265
+Only use this if you want to use a single, direct tool with your AI Agent.
266
+</Callout>
267
361
-### Installation
268
+**Install**
269
363
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
270
+<Tabs items={["Python", "TypeScript"]}>
271
<Tab value="Python">
272
```bash
366
-pip install python-dotenv composio openai-agents
273
+pip install composio openai-agents composio-openai-agents
274
```
275
</Tab>
276
<Tab value="TypeScript">
277
```bash
371
-npm install dotenv @composio/core @openai/agents zod@3
278
+npm install @composio/core @openai/agents @composio/openai-agents
279
```
280
</Tab>
281
</Tabs>
282
376
-### Usage
377
-
378
-Create a Tool Router session and execute tasks with OpenAI agents:
283
+**Usage**
284
380
-<Callout type="info">
381
-- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
382
-- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
383
-</Callout>
384
-
385
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
285
+<Tabs items={["Python", "TypeScript"]}>
286
<Tab value="Python">
287
```python
388
-from dotenv import load_dotenv
288
+import asyncio
289
from composio import Composio
390
-from agents import Agent, Runner, HostedMCPTool
290
+from agents import Agent, Runner
291
+from composio_openai_agents import OpenAIAgentsProvider
292
392
-load_dotenv()
293
+composio = Composio(provider=OpenAIAgentsProvider())
294
394
-# Initialize Composio (API key from env var COMPOSIO_API_KEY)
395
-composio = Composio()
396
-# Unique identifier of the user
397
-user_id = "user_123"
295
+external_user_id = "user_2nFh83Hde"
296
+recipient_email = "soham.g@composio.dev"
297
399
-# Create a Tool Router session for the user
400
-session = composio.create(user_id=user_id)
298
+# Get a specific tool
299
+tools = composio.tools.get(user_id=external_user_id, tools=["GMAIL_SEND_EMAIL"])
300
402
-# Configure OpenAI agent with Composio MCP server
301
agent = Agent(
404
- name="Personal Assistant",
405
- instructions="You are a helpful personal assistant. Use Composio tools to take action.",
406
- model="gpt-5.2",
407
- tools=[
408
- HostedMCPTool(
409
- tool_config={
410
- "type": "mcp",
411
- "server_label": "composio",
412
- "server_url": session.mcp.url,
413
- "require_approval": "never",
414
- "headers": session.mcp.headers,
415
- }
416
- )
417
- ],
302
+ name="Email Manager",
303
+ instructions="You are a helpful assistant.",
304
+ tools=tools,
305
)
306
420
-# Execute the task
421
-print("Fetching GitHub issues from the Composio repository @ComposioHQ/composio...\n")
422
-try:
423
- result = Runner.run_sync(
307
+async def main():
308
+ result = await Runner.run(
309
starting_agent=agent,
425
- input="Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
310
+ input=f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'",
311
)
312
print(result.final_output)
428
-except Exception as e:
429
- print(f"[Error]: {e}")
313
431
-print("\n\n---")
432
-print("Tip: If prompted to authenticate, complete the auth flow and run again.")
314
+asyncio.run(main())
315
```
316
</Tab>
317
<Tab value="TypeScript">
318
```typescript
437
-import "dotenv/config";
319
import { Composio } from "@composio/core";
439
-import { Agent, hostedMcpTool, run, MemorySession } from "@openai/agents";
440
-import { createInterface } from "readline/promises";
320
+import { Agent, run } from "@openai/agents";
321
+import { OpenAIAgentsProvider } from "@composio/openai-agents";
322
442
-// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
443
-const composio = new Composio();
323
+const composio = new Composio({
324
+ provider: new OpenAIAgentsProvider(),
325
+});
326
445
-// Unique identifier of the user
446
-const userId = "user_123";
327
+const externalUserId = "user_2nFh83Hde";
328
+const recipientEmail = "soham.g@composio.dev";
329
448
-// Create a tool router session for the user
449
-const session = await composio.create(userId);
330
+// Get a specific tool
331
+const tools = await composio.tools.get(externalUserId, {
332
+ tools: ["GMAIL_SEND_EMAIL"],
333
+});
334
335
const agent = new Agent({
452
- name: "Personal Assistant",
453
- instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
454
- model: "gpt-5.2",
455
- tools: [
456
- hostedMcpTool({
457
- serverLabel: "composio",
458
- serverUrl: session.mcp.url,
459
- headers: session.mcp.headers, // Authentication headers for the Composio MCP server
460
- }),
461
- ],
336
+ name: "Email Manager",
337
+ instructions: "You are a helpful assistant.",
338
+ tools: tools,
339
});
340
464
-// Create a memory session for persistent multi-turn conversation
465
-const memory = new MemorySession();
466
-
467
-// Execute an initial task
468
-console.log("Fetching GitHub issues from the Composio repository...\n");
469
-try {
470
- const initialResult = await run(
471
- agent,
472
- "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
473
- { session: memory }
474
- );
475
- console.log(`${initialResult.finalOutput}\n`);
476
-} catch (error) {
477
- console.error("[Error]:", error instanceof Error ? error.message : error);
478
-}
479
-
480
-// Continue with interactive conversation
481
-const readline = createInterface({ input: process.stdin, output: process.stdout });
482
-
483
-console.log(`
484
-What else would you like me to do?
485
-(Type 'exit' to exit)
486
-`);
487
-
488
-while (true) {
489
- const input = (await readline.question("You: ")).trim();
490
- if (input.toLowerCase() === "exit") break;
491
-
492
- console.log("Assistant: ");
341
+console.log("Running agent...");
342
+const result = await run(
343
+ agent,
344
+ `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`
345
+);
346
494
- try {
495
- const result = await run(agent, input, { session: memory });
496
- console.log(`${result.finalOutput}\n`);
497
- } catch (error) {
498
- console.error("\n[Error]:", error instanceof Error ? error.message : error);
499
- }
347
+console.log("Received response from agent");
348
+if (result.finalOutput) {
349
+ console.log(result.finalOutput);
350
}
501
-readline.close();
351
```
352
</Tab>
353
</Tabs>
354
+</Accordion>
355
506
-## Usage with direct tools
356
+<Accordion title="Direct MCP usage">
357
+<Callout type="info">
358
+Only use this if you want to use Composio's MCP server directly without the session abstraction.
359
+</Callout>
360
508
-### Setup
361
+**Install**
362
363
<Tabs items={["Python", "TypeScript"]}>
364
<Tab value="Python">
365
```bash
513
-pip install composio openai-agents composio-openai-agents
366
+pip install composio openai-agents
367
```
368
</Tab>
369
<Tab value="TypeScript">
370
```bash
518
-npm install @composio/core @openai/agents @composio/openai-agents
371
+npm install dotenv @composio/core @openai/agents
372
```
373
</Tab>
374
</Tabs>
375
523
-### Usage
376
+**Usage**
377
378
<Tabs items={["Python", "TypeScript"]}>
379
<Tab value="Python">
380
```python
381
import asyncio
382
+from dotenv import load_dotenv
383
+load_dotenv()
384
+
385
from composio import Composio
530
-from agents import Agent, Runner
531
-from composio_openai_agents import OpenAIAgentsProvider
386
+from agents import Agent, Runner, HostedMCPTool
387
533
-composio = Composio(api_key="your-api-key", provider=OpenAIAgentsProvider())
388
+composio = Composio()
389
535
-# Create a connected account for the user for the gmail toolkit and replace with your own user id
536
-externalUserId = "your-user-id"
390
+external_user_id = "user_2nFh83Hde"
391
+recipient_email = "soham.g@composio.dev"
392
538
-# Get Gmail tools that are pre-configured
539
-tools = composio.tools.get(user_id=externalUserId, tools=["GMAIL_SEND_EMAIL"])
393
+# Get MCP URL directly
394
+mcp = composio.mcp.get(user_id=external_user_id)
395
396
agent = Agent(
542
- name="Email Manager", instructions="You are a helpful assistant", tools=tools
397
+ name="Email Manager",
398
+ instructions="You are a helpful assistant.",
399
+ tools=[
400
+ HostedMCPTool(
401
+ tool_config={
402
+ "type": "mcp",
403
+ "server_label": "composio",
404
+ "server_url": mcp.url,
405
+ "require_approval": "never",
406
+ "headers": mcp.headers,
407
+ }
408
+ )
409
+ ],
410
)
411
545
-# Run the agent
412
async def main():
413
result = await Runner.run(
414
starting_agent=agent,
549
- input="Send an email to soham.g@composio.dev with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'",
415
+ input=f"Send an email to {recipient_email} with the subject 'Hello from Composio' and the body 'This is a test email!'",
416
)
417
print(result.final_output)
418
@@ -555,39 +421,42 @@ asyncio.run(main())
421
</Tab>
422
<Tab value="TypeScript">
423
```typescript
424
+import "dotenv/config";
425
import { Composio } from "@composio/core";
559
-import { Agent, run } from "@openai/agents";
560
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
426
+import { Agent, run, hostedMcpTool } from "@openai/agents";
427
562
-// add OPENAI_API_KEY in your .env file
563
-const composio = new Composio({
564
- apiKey: "your-api-key",
565
- provider: new OpenAIAgentsProvider(),
566
-});
428
+const composio = new Composio();
429
568
-// Create a connected account for the user for the gmail toolkit and replace with your own user id
569
-const externalUserId = "your-user-id";
430
+const externalUserId = "user_2nFh83Hde";
431
+const recipientEmail = "soham.g@composio.dev";
432
571
-// Fetch tools for GMAIL toolkit on behalf of the user
572
-const tools = await composio.tools.get(externalUserId, {
573
- tools: ["GMAIL_SEND_EMAIL"],
574
- });
433
+// Get MCP URL directly
434
+const mcp = await composio.mcp.get(externalUserId);
435
436
const agent = new Agent({
577
- name: "Email Manager",
578
- tools: tools,
437
+ name: "Email Manager",
438
+ instructions: "You are a helpful assistant.",
439
+ tools: [
440
+ hostedMcpTool({
441
+ serverLabel: "composio",
442
+ serverUrl: mcp.url,
443
+ headers: mcp.headers,
444
+ }),
445
+ ],
446
});
447
581
-console.log(`Running agent...`);
448
+console.log("Running agent...");
449
const result = await run(
583
- agent,
584
- "Send an email to soham.g@composio.dev with the subject 'Hello from composio' and the body 'Congratulations on sending your first email using AI Agents and Composio!'"
450
+ agent,
451
+ `Send an email to ${recipientEmail} with the subject 'Hello from Composio' and the body 'This is a test email!'`
452
);
453
587
-console.log(`Received response from agent`);
454
+console.log("Received response from agent");
455
if (result.finalOutput) {
589
- console.log(JSON.stringify(result.finalOutput, null, 2));
456
+ console.log(result.finalOutput);
457
}
458
```
459
</Tab>
460
</Tabs>
461
+</Accordion>
462
+</Accordions>