Parallel Agent Execution

Parallel Agent Execution

Some requests are really several separate jobs. Onboarding a new customer, for example, means checking identity, assessing credit risk, running compliance checks and opening an account.

A coordinator agent splits the request into tasks and hands each one to a specialist agent. Tasks that don't depend on each other run at the same time. The coordinator then combines the results into one answer.

Why use it?

It also doesn't change how you call the agent. You turn it on with one setting on the coordinator.

Get access

This is a preview feature, turned on per instance. Your IBM contact will add you to a preview instance and send you:

• the instance URL
• an API key

1. Install the CLI

You need the Orchestrate command-line tool. See Installing the ADK for requirements. Parallel Agent Execution requires ADK version 2.19.0, so install that version:

pip install --upgrade ibm-watsonx-orchestrate==2.19.0

2. Connect to your instance

Replace the values in angle brackets. More detail is in Initiating your environment and the CLI reference.

orchestrate env add -n my-preview \
  -u https://api.<region>.watson-orchestrate.ibm.com/instances/<instance-id> \
  --type mcsp

orchestrate env activate my-preview --api-key <YOUR_API_KEY>

Quick start

Build a coordinator with two specialists. For background, see Building agents and Importing agents.

1. Create the specialist agents

   A specialist is a normal agent with its own tools. Save this as risk_agent.yaml, then create a similar compliance_agent.yaml.

   risk_agent.yaml

   Copy

   spec_version: v1
   kind: native
   name: risk_agent
   description: Assesses credit and financial risk for an applicant.
   llm: watsonx-orchestrate/frontier
   style: react_intrinsic
   instructions: |
     You are the financial risk specialist.
     Check the applicant's credit profile and report the exact score.
     Keep your answer under 150 words.
   tools:
     - check_credit_profile

   To see which models you can use, run orchestrate models list. See also Choosing an LLM.

2. Create the coordinator

   The important line is coordination: parallel.

   onboarding_coordinator.yaml

   Copy

   spec_version: v1
   kind: native
   name: onboarding_coordinator
   description: Runs risk and compliance checks and gives one decision report.
   llm: watsonx-orchestrate/frontier
   style: react_intrinsic
   coordination: parallel
   instructions: |
     You plan the work; you do not do the checks yourself.
     Always create a plan with two tasks:
       1. risk_agent
       2. compliance_agent
     Neither task depends on the other. Include the applicant ID in each task.
   collaborators:
     - risk_agent
     - compliance_agent

3. Import and deploy

   Import the specialists first, then the coordinator. Then deploy each agent to live.

   Copy

   orchestrate agents import -f risk_agent.yaml
   orchestrate agents import -f compliance_agent.yaml
   orchestrate agents import -f onboarding_coordinator.yaml
   
   orchestrate agents deploy -n risk_agent
   orchestrate agents deploy -n compliance_agent
   orchestrate agents deploy -n onboarding_coordinator

4. Ask a question

   Open the embedded chat for onboarding_coordinator (with woAPI: "v2completions") and send:

   Copy

   Process application APP-1001 for Jane Doe. Assess credit risk and run compliance checks.

   Both specialists start together and finish on their own. You get one combined answer.

Example: customer onboarding and KYC

This sample runs four checks in one parallel step and produces one decision report. The coordinator is customer_onboarding_coordinator.

Try it live: open the chat button at the bottom right of this page and send this prompt. You can also copy it into your own agent.

Process onboarding application APP-KYC-9481 for Elena Rostova. Execute government ID and
biometric verification, assess credit and banking cash flow risk, perform regulatory AML
and FATCA compliance checks, and provision core accounts with instant virtual card.

You get a report with the decision, the identity, risk and compliance results, the new account details and next steps.

Nine more samples are available: incident response, code review, travel planning, security triage, customer support, deal review, executive decisions, threat response and a multi-team program. Ask your IBM contact for the sample bundle.

Chat with your agent

1. Deploy your coordinator

   The coordinator and its specialists must be deployed to live. See step 3 in the Quick start.

2. Get the embed script

   Run this command with the name of your coordinator agent:

   Copy

   orchestrate channels webchat embed --agent-name=onboarding_coordinator

   The command prints a <script> block with the settings for your instance: orchestrationID, hostURL, agentId and agentEnvironmentId. You can also create the script from the Orchestrate user interface. See Embedded chat: getting started for this step, or Embedding the agent to web applications for the user interface route.

3. Add woAPI: "v2completions"

   Add this one line to the settings in the script. Without it, you will not get parallel execution or progress messages.

   embed script

   Copy

   window.wxOConfiguration = {
     orchestrationID: "...",
     hostURL: "...",
     rootElementID: "root",
     woAPI: "v2completions",
     chatOptions: {
       agentId: "...",
       agentEnvironmentId: "..."
     }
   };

   Keep the other values exactly as the command printed them. If the script has deploymentPlatform and crn lines, keep them only if you are embedding on IBM Cloud.

4. Put the script on a web page

   Paste the script inside the <body> of your page, and add an element with the ID root. The page must start with <!DOCTYPE html>.

   index.html

   Copy

   <!DOCTYPE html>
   <html>
     <body>
       <div id="root"></div>
       <!-- paste the embed script here -->
     </body>
   </html>

5. Open the page and send a prompt

   Open the page in your browser and send the onboarding prompt from the example. The chat on this page is set up the same way, so you can try it here first.

Show progress in your app

Call the coordinator the same way you call any agent. If you stream the response, you also receive progress messages that you can show to users.

Watch the specialists start and finish together in the chat. If the video doesn't play, download it (.mov, about 23 MB).

The messages arrive in this order:

• thread.parallel.event · parallel.agent.started
  A specialist has started. Includes the agent name and task.
• thread.parallel.event · parallel.agent.completed
  A specialist has finished, with a short result summary.
• thread.parallel.event · parallel.run.state
  The run is writing the final answer, then is complete.
• thread.message.completed
  The final combined answer is ready.

To see these messages in a chat window, use the embedded chat with woAPI: "v2completions". See Chat with your agent.

Tips for good results

Limits in the preview

Troubleshooting

Select a problem to see what to try. For general issues, see Troubleshooting in the Orchestrate documentation.

More documentation: watsonx Orchestrate ADK documentation