Associating connections to Custom agents - IBM watsonx Orchestrate ADK

Automatic Connection
Manual 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:

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.
Duplication: If multiple tools require the same connection, it appears only once in error messages.

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

orchestrate agents connect -n <custom agent name> -a <connection app-id>

Show Command Flags

--name / -n

string

required

Name of the agent to add connections to.

--app-id / -a

string

required

Connection app-id to associate with the agent. Multiple can be specified: --app-id conn1 --app-id conn2.

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

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.

​Connection Credential Format

Connection Credential Format