Quickstart

Execute your first tool from Composio

This guide demonstrates a core Composio feature, executing authenticated tool calls without wrapping complex API calls into LLM tools yourself.

We’ll connect to GitHub and fetch your username using a simple script.

Setup

First, let’s get your environment ready. You only need to do this once.

This command will open a browser window for you to authenticate and generate your API key.

$composio login

Make sure to set the retrieved COMPOSIO_API_KEY as an environment variable in your development environment (e.g., in a .env file or by exporting it).

Composio handles the OAuth flow. This command links your GitHub account to your default Composio Entity (user profile).

$composio add github

Follow the prompts in your terminal and browser to authorize Composio.

1from composio_openai import ComposioToolSet, Action
2from openai import OpenAI
3
4# Initialize Composio ToolSet
5# It automatically picks up COMPOSIO_API_KEY from env vars
6# Uses the 'default' entity_id if not specified
7toolset = ComposioToolSet()
8client = OpenAI()

With setup done, let’s write the code.

Tool-calling with Composio

The code below shows how to give tools to an LLM and letting Composio handle the execution when the LLM decides to use a tool.

1# Directly execute the action to get the authenticated user's info
2# Composio uses the connection linked via 'composio add github'
3tools = toolset.get_tools(actions=[Action.GITHUB_GET_THE_AUTHENTICATED_USER])
4
5task = "Get my GitHub username."
6messages = [
7 {"role": "system", "content": "You are a helpful assistant that can use tools."},
8 {"role": "user", "content": task},
9]
10
11response = client.chat.completions.create(
12 model="gpt-4o-mini", # Or another capable model
13 messages=messages,
14 tools=tools, # The tools we prepared earlier
15 tool_choice="auto", # Let the LLM decide whether to use a tool
16)
17
18result = toolset.handle_tool_calls(response)
19
20print(result)

After running the script, you should see your GitHub username printed!

What just happened?

  1. Tool Discovery: You asked Composio for tools (toolset.get_tools). Composio provided LLM-ready definitions for GitHub actions.
  2. LLM Reasoning: The LLM received your task (“Get my GitHub username”) and the available tools. It determined the GITHUB_GET_THE_AUTHENTICATED_USER tool was appropriate.
  3. Tool Request: The LLM responded asking to call that specific tool.
  4. Composio Execution: toolset.handle_tool_calls intercepted this request. It found your linked GitHub credentials, made the actual API call, and returned the result.

You focused on the prompt and handling the final outcome, while Composio managed the tool schemas, authentication, and API interaction.

1from composio_openai import ComposioToolSet, Action
2from openai import OpenAI
3
4toolset = ComposioToolSet()
5client = OpenAI()
6
7tools = toolset.get_tools(actions=[Action.GITHUB_GET_THE_AUTHENTICATED_USER])
8task = "Get my GitHub username."
9messages = [
10 {"role": "system", "content": "You are a helpful assistant that can use tools."},
11 {"role": "user", "content": task},
12]
13response = client.chat.completions.create(
14 model="gpt-4o-mini",
15 messages=messages,
16 tools=tools,
17 tool_choice="auto",
18)
19result = toolset.handle_tool_calls(response)
20print(result)