AI agents are becoming an essential part of modern software systems. They can take user input, reason through goals, and interact with external services to complete real tasks. This makes them useful for building workflows, automation, and product features powered by language models.

To support this, OpenAI introduced the Agents SDK on March 11, 2025. The SDK provides a way to define agent behavior, connect to external tools, and manage the flow of actions. They ahve also extended the support for MCP recently. Tools are exposed through MCP (Model Context Protocol), a standard interface that lets agents discover and call functions from any compatible server.

Image description

Today, we will use the OpenAI Agents SDK to build a working Composio MCP agent. The goal is to show how agents can be connected to real tools using MCP, and how to run them with minimal setup.

Let’s get started!

Image description

What is OpenAI Agents SDK

The OpenAI Agents SDK is a Python framework introduced by OpenAI in March 2025. It is built to help developers create agents that use large language models to solve tasks by thinking through goals and using tools. The SDK is open source and designed to be modular, so developers can customize agent behavior as needed.

This SDK was released as part of OpenAI’s broader effort to support agent-based workflows. Instead of manually writing logic for reasoning, decision-making, and tool execution, the agent handles those steps based on the instructions and tools provided by the developer. It removes the need to build orchestration or tool routing from scratch.

The Agents SDK includes built-in support for agent memory, streaming output, tool retries, and tracing. It also supports function calling with structured inputs and outputs. These features make it possible to build agents that are reliable, debuggable, and suitable for real applications.

Agents built with the SDK can be used in local scripts, deployed as services, or integrated into product features. Whether you are prototyping or preparing for production, the SDK offers a foundation that is stable and developer-friendly.

🧩 Key Components of the OpenAI Agents SDK

The OpenAI Agents SDK is built around several core components that work together to facilitate the creation and management of AI agents. Understanding these components is crucial for effectively utilizing the SDK.

1. Agent

The Agent class defines the behavior of an AI agent. It includes:

  • Name: Identifies the agent.
  • Instructions: Guides the agent's responses and actions.
  • Tools: Specifies the functions or APIs the agent can use.
  • Handoffs: Allows the agent to delegate tasks to other agents when necessary.

This setup enables the agent to process inputs, make decisions, and execute tasks autonomously.

2. Tool

Tools are external functions or APIs that agents can invoke to perform specific actions. Each tool is defined with:

  • Name: A unique identifier.
  • Description: Explains the tool's purpose.
  • Input Schema: Specifies the expected input parameters.
  • Handler Function: The actual function that executes the desired action.

Tools can be custom-built or integrated from existing services, providing flexibility in extending agent capabilities.

3. Runner

The Runner class manages the execution of agents. It offers methods to run agents in different modes:

  • run(): Executes the agent asynchronously.
  • run_sync(): Runs the agent synchronously, suitable for simpler applications.
  • run_streamed(): Allows streaming of the agent's responses, providing real-time feedback.

The Runner handles the agent's decision-making loop, including tool selection and execution, until the task is completed.

4. ToolCall and ToolResponse

These classes represent the interaction between agents and tools:

  • ToolCall: Encapsulates the agent's request to invoke a specific tool with given parameters.
  • ToolResponse: Contains the result returned by the tool after execution.

This mechanism ensures structured communication between agents and their tools.

5. Tracing and Streaming

The SDK includes features for monitoring and debugging:

  • Tracing: Automatically records the sequence of actions taken by an agent, including tool calls and responses. This is invaluable for debugging and optimizing agent workflows.
  • Streaming: Enables agents to provide partial responses in real-time, enhancing user experience in interactive applications.

These features support the development of robust and user-friendly agent applications.

What is Composio MCP

MCP (Model Context Protocol) is a standard that defines how agents can discover and use tools through a shared interface. It describes tools using structured metadata, including names, input types, and output formats. This makes it easier for agents to interact with tools without needing hardcoded integrations.

Composio MCP is a fully managed platform built on top of this standard. It offers access to over 100 tools, each exposed as an individual MCP server with built-in schemas, execution endpoints, and secure authentication. These tools are ready to be used by any agent that understands the MCP format.

Composio MCP Server

Composio not only hosts and maintains these tools, but also handles all the complex parts of integration, OAuth flows, schema updates, version control, and monitoring. Developers don’t need to deal with external APIs, handle retries, or format payloads manually. This allows you to focus purely on agent logic while working with tools that are consistent, reliable, and production-ready.

✅ Why Use Composio MCP

  • Access 100+ Tools Instantly: Tools are pre-integrated, MCP-compliant, and immediately available for use.
  • No API Wrapping Needed: Composio handles tool setup, input validation, response formatting, and error handling.
  • Secure by Default: Authentication, authorization, and token handling are built in and fully managed.
  • Consistent Interface Across All Tools: Every tool follows the same structure, making it easier to switch or combine tools.
  • Hosted, Versioned, and Monitored: Tools are kept up to date, performance-tracked, and ready for production use.
  • Designed for Agent Frameworks: Fully compatible with the OpenAI Agents SDK and other agent runtimes that support MCP.

🛠️ How to Build MCP Agents Using the OpenAI Agents SDK

An MCP agent is an AI agent that can use tools exposed through MCP-compliant servers. These tools follow a standard format, making them accessible to any compatible agent.

Using the OpenAI Agents SDK, you can register these servers manually and let the agent discover and use the tools at runtime. Below are the steps to build and run such an agent from scratch.

✅ Step 1: Prepare Your Environment

You’ll need the following:

  • Python 3.8 or higher
  • An OpenAI API key

✅ Step 2: Set Up Your Project

Create a virtual environment

macOS / Linux:

python3 -m venv env
source env/bin/activate

Windows:

python -m venv env
.\env\Scripts\activate

Install required packages 

pip install openai-agents python-dotenv

✅ Step 3: Add Your API Key

Create a .env file in your project root:

OPENAI_API_KEY=sk-...

Load this in your script using dotenv to authenticate with OpenAI.

✅ Step 4: Connect Tools and Get MCP Server URLs

To make external tools accessible to your agent, you’ll need to set them up using the Composio CLI. This process creates MCP-compliant servers for each tool.

🔹 Step 4.1: Get Your MCP Server URL

Once your tool is connected:

  1. Go to mcp.composio.dev
  2. Navigate to the tool you want to connect
  3. Copy the MCP server URL (it will look like https://mcp.composio.dev//)

✅ Step 5: Build and Run the Agent

Create a file called main.py and use the following structure:

import asyncio
import os
from dotenv import load_dotenv
import openai
from agents import Agent, Runner
from agents.mcp import MCPServerSse

# Load environment
load_dotenv()

# Set API key
openai.api_key = os.getenv("OPENAI_API_KEY")

# MCP tool URL (replace with actual URL you got from step 4.3)
TOOL_URL = "https://mcp.composio.dev//"

async def main():
    mcp_server = MCPServerSse({"url": TOOL_URL})

    try:
        await mcp_server.connect()

        # Create an agent and register the connected tool
        # ✅ Replace "MCP Agent" with a descriptive name if desired
        # ✅ Update instructions to guide the agent's behavior
        agent = Agent(
            name="MCP Agent",
            instructions="You help the user complete tasks using the connected tool.",
            mcp_servers=[mcp_server]
        )

        # 🔁 Replace this task with your actual prompt or goal
        task = "Perform a task using the connected tool."

        result = await Runner.run(agent, task)

        print(result.final_output)

    finally:
        await mcp_server.cleanup()

# Run the async main function
if __name__ == "__main__":
    asyncio.run(main())

⚙️ Execution Examples: Using MCP Agents with Real Tools

The following examples show how to use the OpenAI Agents SDK to run MCP agents connected to real tools via Composio.

Before running these examples, make sure you’ve completed all the setup steps from the previous section:

  • Set up your environment and project
  • Added and authorized the tool using composio add
  • Retrieved the MCP server URL from mcp.composio.dev

You’ll use the MCP URLs directly in your agent code to link to specific tools like GitHub and Notion.

🐙 Example 1: Manage GitHub Repositories with an Agent

In this example, we use the OpenAI Agents SDK to build an agent that connects to GitHub through Composio’s MCP integration. The agent interprets natural language instructions and performs actions like creating issues in a repository.

Once the GitHub tool is connected and authenticated through Composio, this agent can:

  • 🐞 Create GitHub issues based on user input
  • 📌 Update repository descriptions or metadata
  • 🔁 Assist with pull requests and dev workflows
  • ⚙️ Automate project planning and bug tracking

In this example, the agent will create a new issue in a GitHub repository using a plain English task description.

✅ Make sure you have:

  • Run composio add github and completed the authentication in the browser as in the step 4.2
  • Copied the MCP server URL from https://mcp.composio.dev/

✅ GitHub Agent Code 

import asyncio
import os
from dotenv import load_dotenv
import openai
from agents import Agent, Runner
from agents.mcp import MCPServerSse

# Load environment variables
load_dotenv()

# Set OpenAI API key from .env
openai.api_key = os.getenv("OPENAI_API_KEY")

# MCP tool URL (replace with your actual GitHub tool URL from step 4.3)
GITHUB_MCP_URL = "https://mcp.composio.dev/github/"

async def main():
    github_server = MCPServerSse({"url": GITHUB_MCP_URL})
    try:
        await github_server.connect()

        agent = Agent(
            name="GitHub Agent",
            instructions="You help the user manage GitHub by creating issues, updating repos, and handling PRs using the connected GitHub tool.",
            mcp_servers=[github_server]
        )
# 🔁 Replace 'your-username/your-repo-name' with your actual GitHub repository
        task = "Create an issue in the repository 'your-username/your-repo-name' with the title 'Bug: Login not working' and body 'The login button throws a 500 error when clicked.'"
        result = await Runner.run(agent, task)
        print(result.final_output)

    finally:
        await github_server.cleanup()

if __name__ == "__main__":
    asyncio.run(main())

Output

This is just one example of using an AI agent with GitHub. You could expand it to create milestones, assign tasks, or even generate changelogs based on merged pull requests.

📘 Example 2: Manage Notion Pages and Tasks with an Agent

In this example, we use the OpenAI Agents SDK to build an agent that connects to Notion via Composio’s MCP integration. This agent can automate task planning, content creation, meeting notes, and more directly inside your Notion workspace.

Once the Notion tool is connected and authenticated through Composio, this agent can:

  • ✍️ Create pages with titles, content, and custom layouts
  • ✅ Add tasks or project outlines into a workspace
  • 🧠 Automate status updates or team checklists
  • 📅 Plan events, sprints, or meeting agendas

In this example, the agent will create a simple task planning page in Notion using a plain language command.

✅ Make sure you have:

  • Run composio add notion and completed the authentication in the browser as in step 4.2
  • Copied the MCP server URL from https://mcp.composio.dev/

✅ Notion Agent Code 

import asyncio
import os
from dotenv import load_dotenv
import openai
from agents import Agent, Runner
from agents.mcp import MCPServerSse

# Load environment variables from .env file
load_dotenv()

# Set OpenAI API key from .env
openai.api_key = os.getenv("OPENAI_API_KEY")

# MCP tool URL (replace with your actual Notion tool URL from step 4.3)
NOTION_MCP_URL = "https://mcp.composio.dev/notion/"

async def main():
    notion_server = MCPServerSse({"url": NOTION_MCP_URL})
    try:
        await notion_server.connect()

        agent = Agent(
            name="Notion Agent",
            instructions="You help the user manage their Notion workspace by creating pages, organizing content, and tracking tasks using the connected Notion tool.",
            mcp_servers=[notion_server]
        )

        # 🔁 You can change the page title and content to suit your project or workflow
        task = "Create a Notion page titled 'Weekly Sprint Plan' with the content '1. Fix login bug\n2. Update dashboard\n3. Plan Friday demo.'"
        result = await Runner.run(agent, task)
        print(result.final_output)

    finally:
        await notion_server.cleanup()

if __name__ == "__main__":
    asyncio.run(main())

🖨️ Output

This example shows how easy it is to automate your planning and documentation inside Notion using a language-model-powered agent. You can expand it to add checkboxes, format content, or integrate with GitHub and Slack for full-team workflows.

Final Verdict

AI agents are no longer just an idea for the future. They are real and useful today. With the OpenAI Agents SDK and Composio, you can build smart agents that understand tasks and use tools like GitHub, Notion, or Gmail to get real work done.

Composio gives you ready-to-use tools, so you don’t need to worry about setting up APIs or handling complex code. You just connect a tool, give your agent a task, and it takes care of the rest.

Whether you're building something on your own or working in a team, this is an easy and powerful way to create real automation using language and AI.