# Connections

## Implementing Connections

**Connections** enable you to connect to third-party tools and services in your custom Book. To implement a connection, define a Python function in your Book class and decorate it with the [**@connect**](/legacy/legacy-experience/books/custom-books/api-reference/decorators/connect-decorator.md) decorator. This decorated function serves as the connection handler and defines the syntax for writing a [connection command](/legacy/legacy-experience/books/connections.md).

{% hint style="warning" %}
**Note:** Implementing an **OAuth** connection in a custom BDK Book is not supported at this time.
{% endhint %}

### Multiple Connections

You can define multiple connections within a Book, each with its own handler method. Use the `noun_phrase` keyword argument in the [**@connect**](/legacy/legacy-experience/books/custom-books/api-reference/decorators/connect-decorator.md) decorator to assign a unique label to each connection and differentiate between authentication methods.

### Method Docstrings

In your connection method docstring, include the following sections in addition to a brief summary:

#### 1. Arguments

Specify the Python function's parameters.

#### 2. Labels

Define labels for the connection arguments (e.g., API key, credentials) that will be used in your [connection command](/legacy/legacy-experience/books/connections.md). Labels correspond to parameters in your function's definition.

When a label is provided in the docstring, the lowercase form is used in a connection command. When *not* provided, the label will be inferred from the Python variable name.

**Example**

```python
@connect(noun_phrase="api keys")
def connect(self, api_key: str):
    """
    Authenticate to Open Weather API using the specified API key. You can obtain your own API key by visiting
    Open Weather's website at https://openweathermap.org/appid.

    Arguments:
        api_key: The API key to be used for connecting

    Labels:
        api_key: API Key
    """

    api_key = os.getenv("API_KEY", api_key)
    test_url = f"{self._base_url}?appid={api_key}&q=London"
    response = requests.get(test_url, timeout=self._timeout)
    if response.status_code == 401:
        response_data = response.json()
        if "Invalid API key" in response_data.get("message", ""):
            raise ValueError("Invalid API key")

    self._api_key = api_key
```

In this example, `API Key` is the label for the `api_key` connection argument. The lowercase version of the label is used in a connection command (`api key`):

```
connect openweather via some api keys method with
    the api key is "aBcDefg1234"
```

**Additional Examples**

1. `api_key: ApI kEy`

In this example, the connection command uses the lowercase form of `ApI kEy`:

```
connect openweather via some api keys method with
    the api key is "aBcDefg1234"
```

2. `api_key: aPi_KeY`

In this example, the connection command uses the lowercase version of `aPi_KeY`:

```
connect openweather via some api keys method with
    the api_key is "aBcDefg1234"
```

3. No Label

If a label is not provided in the docstring, it is inferred from the Python variable name, `api_key`:

```
connect openweather via some api keys method with
    the api key is "aBcDefg1234"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/connections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.