> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Associating connections to Custom agents

<Tabs>
  <Tab title="Automatic Connection">
    **Starting from version 2.11.0**, connections are automatically assigned to custom agents during import when you declare them in your `agent.yaml` configuration file.

    Declare connection requirements in the `connections` section of your `agent.yaml` file. The system uses a dictionary structure where:

    * **Keys** are either `"global_requirements"` (for agent-wide requirements) or **tool function names** (for tool-specific requirements)
    * **Values** are connection requirement specifications

    **Example:**

    ```yaml theme={null}
    spec_version: v1
    kind: agent
    name: my_custom_agent
    description: "Agent that requires specific connections"

    connections:
      # Agent-wide requirements
      global_requirements:
        required_app_ids:
          - salesforce_app
          - hubspot_app

      # Tool-specific requirements (tool function names)
      search_salesforce:
        required_app_ids:
          - salesforce_app
    ```

    When you import an agent with connections defined in `agent.yaml`:

    * **Existing Configured Connections**: If a connection with the specified `app_id` already exists and is configured, the system automatically assigns it to your agent.

    * **Non-existent Connections**: If a connection with the specified `app_id` doesn't exist, the system automatically creates it during import. However, you need to configure it later using the `orchestrate connections configure` command. For more information, see [Manual Connection](#manual-connection).

    * **Duplication**: If multiple tools require the same connection, it appears only once in error messages.
  </Tab>

  <Tab title="Manual Connection">
    <div id="manual-connection" />

    If you choose not to declare connections in your `agent.yaml` file, you can manually associate connections to your custom agent after import using the `orchestrate agents connect` command:

    ```bash BASH theme={null}
    orchestrate agents connect -n <custom agent name> -a <connection app-id>
    ```

    <Expandable title="Command Flags">
      <ResponseField name="--name / -n" type="string" required>
        Name of the agent to add connections to.
      </ResponseField>

      <ResponseField name="--app-id / -a" type="string" required>
        Connection app-id to associate with the agent. Multiple can be specified: `--app-id conn1 --app-id conn2`.
      </ResponseField>
    </Expandable>
  </Tab>
</Tabs>

## Connection Credential Format

watsonx Orchestrate uses your connection to set custom agent credentials. It injects your credential key at runtime. It follows the format:

```
{connection_app_id}_{credential_type}
```

**Where:**

* `connection_app_id` is the unique ID of your connection app.
* `credential_type` is the value you set with the `-k` parameter when you configure the connection.

**Example:**

```bash BASH theme={null}
orchestrate connections configure --app-id openai_api --environment draft -t team -k api_key
```

Your credential key becomes:

```
openai_api_api_key
```

For more details on creating and configuring connections, see [Creating connections](./build_connections).