@devries-cameron20 / composio-1 / commits / 993a7c385
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.

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>