Associating connections to Custom agents

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

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:

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

required_one_of:
  - [groq_api, openai_api, gemini_api]

Block style (expanded):

YAML

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

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

string

required

Name of the agent to add connections to.

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.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

How `required_one_of` works

Connection Credential Format

​How required_one_of works

​Connection Credential Format

How `required_one_of` works

Connection Credential Format