3K Global Customer Service and Support Agent

This guide explains how to prepare your configuration, find the agent in the IBM Cloud catalog, provision it, and confirm that it has been deployed successfully into your own IBM watsonx Orchestrate instance. It also documents every parameter of the onboarding configuration file and explains what to place in your Cloud Object Storage bucket.

Read it end to end before you begin. Two steps — preparing your configuration file (Section 5) and your policy documents (Section 6) — must be completed before you submit the provisioning form, and they are the steps that most often cause a provisioning attempt to fail.

1. About This Guide

This guide is written for the administrator who will provision the agent in your organisation's IBM Cloud account. It assumes you can sign in to IBM Cloud and create resources, but it does not assume any prior experience with IBM watsonx Orchestrate.

What this guide covers

• What each moving part is for, and who is responsible for it — Section 3.
• Every parameter of the onboarding configuration file, with a complete worked example — Section 5.
• What policy documents are and how the agent uses them — Section 6.
• The provisioning procedure itself, from catalog to a working, tested agent — Sections 7 to 13.

Conventions used

Field names, file names, and configuration keys appear in a fixed-width amber typeface — for example client_cos_bucket.

2. About the Agent

The 3K Global Customer Service and Support Agent is an autonomous, multi-agent customer support solution built for IBM watsonx Orchestrate. It connects to your existing operational data — your order, case, and customer records — and can answer customer enquiries, verify customer identity, retrieve information, resolve issues, and escalate to a human colleague when required.

What is deployed into your watsonx Orchestrate instance

Provisioning creates seven agents, not one, together with the tools they use. All seven are named using the client_id from your configuration file.

3. How Provisioning Works

Four things work together during provisioning. Understanding what each one is for makes the rest of this guide straightforward, and explains why you are asked to create a storage bucket before you provision anything.

End-to-end sequence

• You create a Cloud Object Storage bucket in your own IBM Cloud account and upload your configuration file, plus your policy documents if you have any (Section 9).
• You select a plan (Section 10) and submit the provisioning form, giving IBM a pointer to your bucket and a read credential for it (Section 11).
• IBM calls the 3K service broker, which validates your parameters and queues an onboarding job.
• 3K reads your configuration file and policy documents from your bucket, using the API key you supplied. This access is read-only; nothing is written to your bucket.
• A dedicated canonical database is created on your own PostgreSQL server. Your source schema is discovered and mapped using your watsonx.ai project, and your data is loaded into that database.
• Your policy documents, together with the knowledge articles generated during onboarding, are indexed into a knowledge base in your watsonx Orchestrate instance.
• The seven agents and their tools are deployed into your watsonx Orchestrate instance.
• The instance status becomes Active, and you verify the result (Section 13).

Who is responsible for what

4. Prerequisites

Please confirm all of the following before you begin. A missing prerequisite is the most common cause of a failed provisioning attempt.

If you have not yet received your configuration file template, please contact us using the details in Section 16.

5. The Onboarding Configuration File

The onboarding configuration file is a YAML text file that you complete and upload to your storage bucket. It is the single source of connection and identity information for your deployment: it tells the provisioner where to deploy, what to read, what to write, and whom to notify.

3K provides a template with every value marked as a placeholder. Save it with a .yml or .yaml extension, encoded as UTF-8. The file name is yours to choose — you will enter it in the client_cos_key field during provisioning.

client — identity of this deployment

wxo — your watsonx Orchestrate instance

canonical_db — the database the agents query

source_db — where your operational data lives today

escalation — where unresolved cases go

sendgrid — delivery of customer verification codes

Before answering any question about a specific customer, the supervisor agent emails a six-digit code to that customer's own address and waits for it to be entered. Delivery uses the SendGrid HTTP API, so a SendGrid account with a verified sender identity is required.

watsonx_ai — AI used during onboarding

Complete example

The example below shows every section a typical deployment needs, using a logistics organisation as the subject. Replace each placeholder with your own value. Do not copy this example verbatim — the identifiers are illustrative.

client:
  client_id: abcdlogistics # unique, lowercase, drives all naming
  client_name: ABCD Logistics Inc.

wxo:
  service_url: https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/<INSTANCE_ID>
  api_key: <WXO_API_KEY>

canonical_db: # your PostgreSQL — agents query this
  host: <POSTGRES_HOST>
  port: 30856
  user: <POSTGRES_USER> # must be able to create databases
  password: <POSTGRES_PASSWORD>

source_db: # your operational data, via Trino
  type: trino
  host: <TRINO_HOST>
  port: 443
  catalog: iceberg_data
  schema: logistics
  user: ibmlhapikey_you@acme.com
  password: <TRINO_API_KEY>

escalation: # monitored mailbox for unresolved cases
  email: support@abcd.com

sendgrid: # delivery of customer verification codes
  api_key: <SENDGRID_API_KEY>
  from_email: no-reply@abcd.com # must be a verified SendGrid sender
  from_name: ABCD Support

watsonx_ai: # AI used for schema mapping and embeddings
  url: https://us-south.ml.cloud.ibm.com
  api_key: <WATSONX_API_KEY>
  project_id: <WATSONX_PROJECT_ID>

Handling the file securely

This file contains live credentials for your watsonx Orchestrate instance, both databases, your watsonx.ai project, and your SendGrid account. Please treat it as you would any other secret.

• Do not email it in plain text, attach it to a ticket, or commit it to a source repository.
• Upload it only to a bucket you control, and keep that bucket private.
• Once your instance reaches Active, the file is no longer needed. You may remove it from the bucket, or restrict access to it, at your discretion — it is your bucket and 3K never writes to it.
• If any credential in the file is rotated later, tell your 3K representative — the deployed agents hold the values that were current at provisioning time.

6. Policy Documents

Policy documents are optional, but they are what allow the agent to answer general questions in your own organisation's words rather than in generic terms.

What they are

A policy document sets out a rule that applies to your customers generally — the kind of policy you would publish on your website or hand to any customer who asked. They are not specific to any one person or order. Typical examples include:

• Returns and refunds — what may be returned, within what period, and in what condition.
• Shipping and delivery — service levels, delivery windows, and geographic coverage.
• Order cancellation and amendment — until what point an order may be changed.
• Damaged, lost, or delayed shipments — what you undertake to do, and what you ask the customer to do.
• Warranty terms, and your privacy or data-handling statement.

What they are not

Do not place customer-specific records in your policy documents — no order histories, addresses, contact details, or case notes. That information reaches the agent from your source database, under the identity verification rules described in Section 13. Policy documents are indexed into a knowledge base that any verified customer's question may draw upon, so personal data does not belong there.

Accepted formats and limits

Files in any other format are ignored, without failing provisioning. A knowledge base holds a maximum of 100 files, counting both your policy documents and the knowledge articles generated during onboarding. Keep each policy in its own clearly named file — one topic per file retrieves far better than a single combined handbook.

Where to put them

Upload them to a folder inside the same bucket as your configuration file — e.g. policy-docs/ — and enter that folder name in the client_name field on the provisioning form (Section 11).

How the agent uses them

During provisioning, your documents are downloaded from your bucket and indexed into a knowledge base inside your watsonx Orchestrate instance. At run time, the knowledge agent searches that knowledge base to answer general questions — and because a general question needs no identity check, a customer can ask about your returns policy without verifying who they are. If you provide no policy documents, the agent still functions, but it will have no source for policy questions.

7. Log In to IBM Cloud

• Navigate to cloud.ibm.com.
• Sign in with your IBM Cloud account credentials.

Figure 1 — The IBM Cloud sign-in page.

8. Locate the Agent in the IBM Cloud Catalog

• Select Catalog in the top navigation bar.

Figure 2 — The Catalog link in the IBM Cloud top navigation bar.

• Under the Works with filter, select watsonx Orchestrate. Alternatively, search the catalog for 3K Global Customer Service and Support Agent.

Figure 3 — Filtering the catalog by Works with, then watsonx Orchestrate.

• Select the 3K Global Customer Service and Support Agent tile.

Figure 4 — The 3K Global Customer Service and Support Agent tile in the filtered catalog results.

• The product page opens on the Create tab. Select the About tab if you would like to review the agent's capabilities in more detail before provisioning.

Figure 5 — The product page, showing the Create and About tabs and the available pricing plans.

9. Prepare Your Cloud Object Storage

Your bucket is the handover point described in Section 3. It holds your configuration file and, optionally, your policy documents. You own it and control access to it; 3K only reads from it.

• In the IBM Cloud catalog, search for Object Storage and create a Cloud Object Storage instance. The free Lite plan is sufficient for this purpose.

Figure 6 — Cloud Object Storage instances listed under Storage in the IBM Cloud resource list.

• Within that instance, create a bucket. Keep it private.
• Upload your completed configuration file to the bucket (Section 5).
• If you have policy documents, upload them to a dedicated folder inside the same bucket — e.g. policy-docs/ (Section 6).

Figure 7 — Objects in a Cloud Object Storage bucket. Your own bucket name and contents will differ.

Record these four values

You will need all four when you complete the provisioning form in Section 11.

10. Select a Plan

On the agent's product page, open the Create tab and choose a pricing plan. Three plans are offered.

Figure 8 — The Select a pricing plan panel, showing the Custom, Growth, and Starter plans.

Prices shown are for the country or location set on your account, and were correct at the time of writing. The plan panel in the console is always authoritative. You may also select Add to estimate to model costs before committing.

11. Complete the Provisioning Form

With a plan selected, scroll to Configure your resource and complete the fields below. Every value except the service name and resource group is a pointer to the bucket you prepared in Section 9.

Figure 9 — The Configure your resource section of the provisioning form.

Figure 10 — The five client_cos fields and the optional client_name field, shown in detail.

• Select the checkbox to accept the third-party terms.
• Select Create.

Figure 11 — Accepting the third-party terms enables the Create button.

12. Monitor the Provisioning Status

• Select Manage → Resource list.
• Locate your new instance under AI / Machine Learning.

Figure 12 — The provisioned instance shown with Active status in the IBM Cloud resource list.

Figure 13 — The instance details panel, showing creation date, CRN, resource group, and location.

13. Verify That Your Agent Is Working

Once the status shows Active, verify the deployment as follows.

• Open the watsonx Orchestrate instance named in your configuration file.
• Locate your agents in the agent list. All seven are prefixed with the client_id from your configuration file — e.g. <client_id>_supervisor_agent. Each should show a Live badge.

Figure 14 — The deployed agents in watsonx Orchestrate, each showing a Live badge. The prefix shown comes from that deployment's own client_id.

• Open a chat with the supervisor agent and ask a general question that does not concern a specific customer — for example, "What is your return policy?" The agent should answer from your knowledge base without asking who you are.
• Now ask about a specific order or customer record — for example, "I want to know about my order." The agent should ask for the email address on the account, send a six-digit code to that address, and continue only once you enter the correct code.

Figure 15 — A verification exchange with the supervisor agent. The customer email address has been redacted.

14. Troubleshooting

15. Current Limitations

The current release operates within the technical boundaries below. These reflect the present configuration and are expected to expand in future releases.

If any of these boundaries do not fit your environment, please raise it with us — see Section 16.

16. Support and Contact Information