Configuring platform AI agents

Register platform AI agents in the hub's agent card registry to enable the Concert Home AI Chat feature. The platform includes two categories of agents: platform-level agents that provide core AI capabilities, and product-specific agents that coordinate requests for installed capability products. Register all platform-level agents during platform setup. Register a product-specific agent only for capabilities that you installed.

Platform AI agents

Platform-level agents

Provide core AI capabilities. Their endpoints are fixed platform services within the cluster:

Dashboard Agent: Generates UI dashboards that visualize role-specific or application-specific product data.
Summarize Agent: Synthesizes complex data into concise insights.
Natural Language to GraphQL Agent: Generates GraphQL queries that retrieve data across multiple products.
Fallback Agent: Screens user inputs to help ensure that requests remain relevant to the domain.

Product-specific agents

Coordinate requests for installed capability products. Their endpoints depend on the product host:

Observability Coordinator Agent: Resolves queries that are related to system observability data. Register this agent only if you installed Concert Core Observability.
Optimization Coordinator Agent: Resolves queries that are related to system performance optimization. Register this agent only if you installed Concert Optimize.
Concert Coordinator Agent: Resolves queries that are related to application CVEs, resilience, and other Concert product capabilities.
Concert Code Agent: Handles code-related requests for the Concert product.

Before you begin

Before you can register any agents, set up your watsonx.ai instance and configure the required secrets so the data layer can connect to watsonx.ai.

Each agent registration request requires the following information:

An agent card registration URL

The URL is fixed to the location where the platform hub is installed, by using the URI /platform_hub/ai/registry/agent-cards/submit. For example, if the platform hub is installed on concertplat1.example.com and runs on port 13443, the URL is https://concertplat1.example.com:13443/platform_hub/ai/registry/agent-cards/submit.

An active API key

You retrieve the API key from the itom-secrets secret in the platform namespace:

kubectl get secret itom-secrets -n $HUB_NS -o json | jq '.data | map_values(@base64d)' | grep AUTH_API_KEYS

The command returns the key and its corresponding value. The value is the API key:

"AUTH_API_KEYS": "{API_key_value}"

The agent's endpoint URL

Platform-level agents use fixed service endpoints within the cluster. A typical URL has the format https://{service-name}.<hub-namespace>.svc.cluster.local:{service-port}, where {service-name} is the AI agent service, <hub-namespace> is the namespace that you used to install the platform, and {service-port} is the port that the service uses. Product-specific agents use the host where the product is installed and the port from which the product serves requests.

A JSON request body

Contains agent metadata, the agent's endpoint URL, and security configuration details. See the following examples for the request body content for each agent.

Register AI agents

You can register agents by using any standard REST client or curl commands. Replace the variables with values that apply to your environment.

Set environment variables for the registration URL and API key.
```
export AGENT_CARD_REGISTRATION_URL="https://{HUB_HOST}:{HUB_PORT}/platform_hub/ai/registry/agent-cards/submit"
export API_KEY="{AGENT_REGISTRY_API_KEY}"
```
Replace {HUB_HOST} with the platform hub hostname, {HUB_PORT} with the platform hub port, and {AGENT_REGISTRY_API_KEY} with the API key that you retrieved from the itom-secrets secret.
Register each agent by submitting its agent card.
The following examples show the registration commands for each agent. Replace <hub-namespace> in agent URLs with the namespace where you installed the platform.
After you run the command to register an agent, look for output that is similar to the following example to confirm that registration succeeded.
```
{"success":true,"agent_name":"<agent-name-from-metadata>","cf_storage_id":"<string>","message":"Agent card registered successfully","storage":"contextforge"}
```

Dashboard Agent

DASHBOARD_AGENT_URL="https://ibm-itom-ui-dashboard-agent-svc.<hub-namespace>.svc.cluster.local:51907"

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "metadata": {
        "name": "ui-dashboard",
        "agentType": "generic",
        "author": "admin",
        "description": "A2A agent for generating ITOM dashboard definitions from natural language",
        "version": "1.0.0",
        "display_name": "UI Dashboard Agent",
        "organization": "itom",
        "category": "ui-generation"
    },
    "configuration": {
        "endpoint_url": "$DASHBOARD_AGENT_URL",
        "protocol": "a2a"
    },
    "security": {
        "access_level": "public",
        "requires_authentication": false,
        "authentication_type": "none"
    }
}
EOF

Summarize Agent

SUMMARIZE_AGENT_URL="https://ibm-itom-summarize-agent-svc.<hub-namespace>.svc.cluster.local:51908"

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "metadata": {
      "name": "ibm-itom-summarize-agent",
      "agentType": "generic",
      "author": "admin",
      "description": "Runs a list of GraphQL queries and narrates the combined results in the format the caller requests (text, Leadspace JSON, or markdown). Input is a concrete list of GraphQL operations - not free-form text, not another agent'\''s output. Never use it as a planner step except as part of the data-model-query skill. In other cases use it solely for the execution and summarization",
      "version": "1.0.0",
      "display_name": "SummarizeAgent",
      "organization": "itom",
      "category": "productivity"
    },
    "configuration": {
        "endpoint_url": "$SUMMARIZE_AGENT_URL",
        "protocol": "a2a"
    },
    "security": {
        "access_level": "public",
        "requires_authentication": false,
        "authentication_type": "none"
    }
}
EOF

Natural Language to GraphQL Agent

NL_TO_GQL_AGENT_URL="https://ibm-itom-nl-to-gql-agent-svc.<hub-namespace>.svc.cluster.local:51906"

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "metadata": {
        "name": "nl-to-gql-agent",
        "agentType": "generic",
        "author": "admin",
        "description": "Natural Language to GraphQL Agent",
        "version": "1.0.0",
        "display_name": "NL to GraphQL Agent",
        "organization": "itom",
        "category": "api-generation"
    },
    "configuration": {
        "endpoint_url": "$NL_TO_GQL_AGENT_URL",
        "protocol": "a2a"
    },
    "security": {
        "access_level": "public",
        "requires_authentication": false,
        "authentication_type": "none"
    }
}
EOF

Fallback Agent

FALLBACK_AGENT_URL="https://ibm-itom-fallback-agent-svc.<hub-namespace>.svc.cluster.local:51910"

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "metadata": {
        "name": "ibm-itom-fallback-agent",
        "agentType": "generic",
        "author": "admin",
        "description": "Fallback agent",
        "version": "1.0.0",
        "display_name": "ibm-itom-fallback-agent",
        "organization": "itom",
        "category": "general"
    },
    "configuration": {
        "endpoint_url": "$FALLBACK_AGENT_URL",
        "protocol": "a2a"
    },
    "security": {
        "access_level": "public",
        "requires_authentication": false,
        "authentication_type": "none"
    }
}
EOF

Observability Coordinator Agent

Replace {OBSERVE_HOST} with the hostname where you installed Concert Observe.

OBSERVABILITY_COORDINATOR_AGENT_URL="https://{OBSERVE_HOST}/a2a"

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "metadata": {
      "name": "observability-coordinator",
      "agentType": "generic",
      "author": "admin",
      "description": "Observability coordinator",
      "version": "1.0.0",
      "display_name": "observability-coordinator",
      "organization": "itom",
      "category": "observability"
    },
    "configuration": {
        "endpoint_url": "$OBSERVABILITY_COORDINATOR_AGENT_URL",
        "protocol": "a2a"
    },
    "security": {
        "access_level": "public",
        "requires_authentication": false,
        "authentication_type": "none"
    }
}
EOF

Optimization Coordinator Agent

Replace {OPTIMIZE_HOST} with the hostname where you installed Concert Optimize.

OPTIMIZATION_COORDINATOR_AGENT_URL="https://{OPTIMIZE_HOST}/turbonomic/turboai/a2a"

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
    "metadata": {
      "name": "optimization-coordinator",
      "agentType": "generic",
      "author": "admin",
      "description": "Optimization coordinator",
      "version": "1.0.0",
      "display_name": "optimization-coordinator",
      "organization": "itom",
      "category": "optimization"
    },
    "configuration": {
        "endpoint_url": "$OPTIMIZATION_COORDINATOR_AGENT_URL",
        "protocol": "a2a"
    },
    "security": {
        "access_level": "public",
        "requires_authentication": false,
        "authentication_type": "none"
    }
}
EOF

Concert Coordinator Agent

Replace {CONCERT_HOST} with the hostname where you installed Concert Protect and Concert Resilience.

CONCERT_COORDINATOR_AGENT_URL="https://{CONCERT_HOST}/concert/py-utils/a2a 

curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF 
{ 
    "metadata": { 
      "name": "concert-coordinator", 
      "agentType": "generic", 
      "author": "admin", 
      "description": "Concert coordinator", 
      "version": "1.0.0", 
      "display_name": "concert-coordinator", 
      "organization": "itom", 
      "category": "protect" 
    }, 
    "configuration": { 
        "endpoint_url": "$CONCERT_COORDINATOR_AGENT_URL", 
        "protocol": "a2a" 
    }, 
    "security": { 
        "access_level": "public", 
        "requires_authentication": false, 
        "authentication_type": "none" 
    } 
} 
EOF

Concert Code Agent


curl -k -X POST "$AGENT_CARD_REGISTRATION_URL" \
  -H "Secret: $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF 
{ 
      "metadata": { 
        "name": "ibm-itom-concert-code-agent", 
        "agentType": "generic", 
        "author": "", 
        "description": "", 
        "version": "1.0", 
        "display_name": "ibm-itom-concert-code-agent", 
        "organization": "itom", 
        "category": "productivity" 
     }, 
     "configuration": { 
       "endpoint_url": "https://ibm-itom-concert-code-agent-svc:51909", 
       "protocol": "a2a" 
     }, 
     "security": { 
       "access_level": "restricted", 
       "requires_authentication": true, 
       "authentication_type": "api_key" 
     } 
}
EOF

Verify registered agents

After you register the agents you need, you can verify that they are successfully registered with your platform hub deployment.

In the following examples, replace <hub-namespace> with the namespace where you installed the platform hub.

Run the following command to retrieve the required database name and database username.
```
kubectl get secret app-cfg-oob-secret -n <hub-namespace> -o json \
| jq '.data | {KC_DB_USERNAME: .KC_DB_USERNAME, KC_DB_URL_DATABASE: .KC_DB_URL_DATABASE} | map_values(@base64d)'
```
Use this output to capture the following values:
- KC_DB_USERNAME: the database username
- KC_DB_URL_DATABASE: the database name
You need the username in step 3.
Run the following command to identify the embedded database pod.
```
kubectl get pods -n <hub-namespace> | grep ibm-solis-embedded-db
```
This command lists all pods in the namespace and filters for the embedded database pod.
Query the database for registered agents.

Replace <username> with the database username that you retrieved in step 1. Replace <db-pod-name> with the pod name that you retrieved in step 2.
```
kubectl exec -it <db-pod-name> -n <hub-namespace> -- \
psql -U <username> -d solisdb \
-c "select name, endpoint_url from mcp_gateway.a2a_agents"
```
This query returns the following details for all registered agents.
- name: the agent name
- endpoint_url: the agent endpoint used by the system
Confirm that the agents you registered are listed in the output.

Next steps

After you register the AI agents, configure authentication for the platform. See Configuring authentication.