> ## 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

    Each connection requirement block supports two fields:

    `required_app_ids` — All listed connections must be present and configured for the agent to run.
    `required_one_of` — A list of groups, where at least one connection from each group must be present and configured. Use this when your agent supports multiple alternative providers (for example, different LLM APIs).

    You can use either or both fields in the same connection requirement block.

    **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:
        - my_database_app        # always required
      required_one_of:
        - [groq_api, openai_api] # at least one LLM provider required

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

    ### How `required_one_of` works

    `required_one_of` takes a list of groups. Each group is itself a list of app IDs. The agent requires at least one app ID from each group to be configured, groups are independent of each other. If no connection in a required group is configured when the agent is invoked, the agent returns an error.

    A group can be written in two equivalent YAML styles:

    Flow style (inline):

    ```yaml YAML theme={null}
    required_one_of:
      - [groq_api, openai_api, gemini_api]
    ```

    Block style (expanded):

    ```yaml YAML theme={null}
    required_one_of:
      - - groq_api
        - openai_api
        - gemini_api
    ```

    Both are equivalent. Use whichever is more readable for your use case.

    Flow style (inline):

    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).

    * **Non-existent `required_one_of` Connections**: The system only creates connections for `required_one_of` app IDs that already exist. Alternatives that are not yet registered are not auto-created.

    * **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).