Custom Tools

You can create custom tools for Composio apps. One might need this to call API endpoints in third party applications which are private or those which aren’t supported by the Composio’s Toolset at the moment.

The key concept is that you define an execute_request callable that handles authenticated API calls.

This callable uses Composio’s authentication to make API requests to third-party services.

The callable can be configured to use your own custom authentication parameters as well

This allows you to securely make authenticated API calls while leveraging Composio’s authentication handling.

Creating a custom tool

1
import typing as t
2
from composio_openai import ComposioToolSet, action
3
4
toolset = ComposioToolSet()
5
6
7
@action(toolname="github")
8
def my_custom_action(
9
    param_1: str,
10
    param_2: str,
11
    execute_request: t.Callable,
12
) -> dict:
13
    """
14
    Action Description
15
16
    :param param_1: Parameter 1 description
17
    :param param_2: Parameter 2 description
18
    :return content: Return content description
19
    """
20
    response = execute_request(
21
        endpoint="/user",
22
        method="GET",
23
        body={},
24
        parameters=[],  # custom authentication parameters
25
    )
26
    return response
27
28
29
tools = toolset.get_tools(actions=[my_custom_action])

Create a custom tool with custom auth

Composio tools can also be executed when rolling your own auth. The parameters field in execute_request supports providing the key, value as well as the placement of the auth parameter through the in_ field.

The following table shows the supported parameter placements:

For example, to add an Authorization Bearer token in the headers, you would specify the parameters as:

1
import typing as t
2
from composio_openai import ComposioToolSet, action
3
4
toolset = ComposioToolSet()
5
6
7
@action(toolname="github")
8
def my_custom_action(
9
    param_1: str,
10
    param_2: str,
11
    execute_request: t.Callable,
12
) -> dict:
13
    """
14
    Action Description
15
16
    :param param_1: Parameter 1 description
17
    :param param_2: Parameter 2 description
18
    :return content: Return content description
19
    """
20
    response = execute_request(
21
        endpoint="/user",
22
        method="GET",
23
        body={},
24
        parameters=[
25
            {"name": "Authorization", "value": "Bearer <bearer_token>", "in_": "header"}
26
]
27
    )
28
    return response
29
30
31
tools = toolset.get_tools(actions=[my_custom_action])

OpenAPI based Apps and Tools

Composio supports installing custom apps and tools based on an OpenAPI specification.

Make sure to have info section in your OpenAPI Specification. In the info section, you should have the following fields:

• title: Name of the tool
• version: Version of the tool/spec

Integration YAML Configuration

This README provides an overview of the integration.yaml file structure used for configuring app integrations, with a focus on custom fields.

YAML Structure

The integration.yaml file typically includes the following key sections:

1. Basic Information

   • name: App name
   • unique_key: Unique identifier for the app
   • description: Brief description of the app
   • logo: URL to the app’s logo
   • categories: List of categories the app belongs to. Examples include:
     • productivity
     • marketing
     • social
     • crm
   • docs: Link to the app’s documentation

2. Authentication Schemes

   • auth_schemes: List of authentication methods supported
     • name: Name of the auth scheme
     • auth_mode: Authentication mode (Supported modes: OAUTH2, BASIC, API_KEY, OAUTH1)
     • For OAuth2:
       • authorization_url: OAuth authorization URL
       • token_url: Token endpoint URL
       • default_scopes: Default OAuth scopes
       • available_scopes: List of all available scopes
       • authorization_params: Additional parameters for authorization (e.g., response_type, user_scopes)
     • For OAuth1:
       • authorization_url: OAuth authorization URL
       • request_url: Request token URL
       • token_url: Access token URL
       • signature_method: Signature method (e.g., HMAC-SHA1)
       • default_scopes: Default OAuth scopes
       • scope_separator: Character used to separate scopes
     • For API Key:

       1
       proxy:
       2
         base_url: "{{base_url}}"
       3
         headers:
       4
           Authorization: "{{api_key}}"

     • For Basic Auth: username and password fields are required. You can use them in the proxy/header section directly like:

       1
       proxy:
       2
         headers:
       3
           username: "{{username}}"
       4
           password: "{{password}}"

3. Endpoints

   • get_current_user_endpoint: Endpoint for retrieving current user info. This is used to check if the auth is valid and refresh the token if it is expired.

4. Custom Fields Custom fields are defined within the auth_schemes section and provide additional configuration options for the integration. They are typically found under the fields key of an auth scheme.

   Common attributes for custom fields include:

   • name: Unique identifier for the field
   • display_name: Human-readable name for the field
   • description: Detailed explanation of the field’s purpose
   • type: Data type of the field (e.g., string, boolean)
   • required: Whether the field is mandatory
   • expected_from_customer: Indicates if the end customer needs to provide this information
   • default: Default value for the field (if applicable)

   Examples of custom fields:

   a. API Key field:

   1
   fields:
   2
     - name: api_key
   3
       display_name: API Key
   4
       description: "Your API key for authentication."
   5
       type: string
   6
       required: true
   7
       expected_from_customer: true

   b. Instance URL field (e.g., for Salesforce):

   1
   fields:
   2
     - name: instanceUrl
   3
       display_name: Instance URL
   4
       description: "The base URL for your instance, used for API requests."
   5
       type: string
   6
       required: true
   7
       expected_from_customer: true

   c. Subdomain field (e.g., for PostHog):

   1
   fields:
   2
     - name: subdomain
   3
       display_name: Sub Domain
   4
       description: "Your PostHog subdomain (e.g., 'app' for app.posthog.com)."
   5
       type: string
   6
       required: true
   7
       default: "app"

5. Additional Configuration

   • callback_url: URL for OAuth callback
   • token_response_metadata: List of metadata fields expected in the token response
   • proxy: Configuration for API request proxying. This section defines the data to be used in the request. It can use the fields defined via jinja templating {{field_name}}. It can include:
     • base_url: The base URL for API requests
     • headers: Custom headers to be included in the request
     • query_params: Custom query parameters to be included in the request
     • path_params: Custom path parameters to be included in the request

   Example of a proxy configuration:

   1
   proxy:
   2
     base_url: "https://api.example.com/v1"
   3
     headers:
   4
       Authorization: "Bearer {{access_token}}"
   5
       Content-Type: "application/json"
   6
     query_params:
   7
       api_key: "{{api_key}}"

   In this example, {{access_token}} and {{api_key}} are placeholders that will be replaced with actual values from the authentication process or custom fields.

Usage of Custom Fields

Custom fields are used to gather necessary information from users or provide default configurations for the integration. They can be referenced in other parts of the configuration using placeholders, typically in the format {{field_name}}.