Skip to content

Part 1: Setup & Environment

Outcome: A new bobchestrate-ws project connected to the workshop watsonx Orchestrate environment.

What we will implement

You will create the participant workspace, Python environment, ADK 2.14.0 installation, Bob workshop configuration, MCP connections, and active watsonx Orchestrate environment used by the later parts.

Everything runs inside Bob IDE

All terminal commands and Command Palette actions in this workshop are performed inside IBM Bob IDE — not in a separate system terminal.

How to open a terminal in Bob IDE (same as VS Code):

  • Menu: Terminal → New Terminal
  • Keyboard: Ctrl+` (backtick) on Windows/Linux, Ctrl+` on macOS

The terminal opens at the bottom of the editor, already pointed at your project folder.

How to open the Command Palette:

  • macOS: Cmd+Shift+P
  • Windows: Ctrl+Shift+P

The Command Palette is a quick-search bar at the top of Bob IDE where you type a command name and press Enter to run it — you will use it throughout this workshop.

1. Create the participant project

Create a new empty folder called bobchestrate-ws anywhere on your machine. Do not clone the workshop repository — start from an empty folder.

You can create the folder using any method you prefer:

  • Finder (macOS) / File Explorer (Windows): right-click in the location you want and choose New Folder, then name it bobchestrate-ws.

  • Terminal / Command Prompt:

    mkdir bobchestrate-ws

Once the folder exists, open IBM Bob IDE, sign in with your IBM ID, and select File → Open Folder → bobchestrate-ws. Trust the workspace when prompted.

2. Verify prerequisites

Complete Prerequisites, then open a terminal in Bob IDE:

python --version
uv --version

python3 --version
uv --version

Python must report 3.12.x.

3. Install the ADK extension

  1. Open the Extensions panel: Cmd+Shift+X on macOS or Ctrl+Shift+X on Windows.
  2. Search for and install IBM watsonx Orchestrate ADK.

The extension must be installed before creating the virtual environment so that Bob IDE can detect it during the next step.

4. Create the virtual environment

  1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P).
  2. Type Python: Create Environment and press Enter.
  3. Choose Venv, then select the Python 3.12 interpreter.
  4. Open a new terminal in Bob IDE and confirm that (.venv) appears in its prompt.

Terminal fallback

If Python: Create Environment is unavailable, open a terminal in bobchestrate-ws and create the environment manually. Use the command for your operating system:

python -m venv .venv

python3 -m venv .venv

These commands use the Python 3.12 installation verified in Step 1. Then activate .venv using the platform command below.

If automatic activation fails:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1

.venv\Scripts\activate.bat

source .venv/bin/activate

The PowerShell change applies only to the current terminal session.

5. Install ADK 2.14.0 into the virtual environment

In the Bob IDE status bar — located in the bottom-right corner, next to the Settings (gear) icon — select the red ADK status indicator and choose to install the ADK into .venv. Then confirm the installed version in the terminal:

ADK status bar showing ADK 2.14.0 installed

orchestrate --version

Terminal fallback

If the ADK extension installation is unavailable, install the pinned package directly into .venv from a terminal in bobchestrate-ws:

.\.venv\Scripts\python.exe -m pip install ibm-watsonx-orchestrate==2.14.0

./.venv/bin/python -m pip install ibm-watsonx-orchestrate==2.14.0

Then activate .venv using the platform command in Step 4 and run orchestrate --version to confirm the installation.

The first line must show ADK Version: 2.14.0. Ask the instructor before continuing if another version is installed.

6. Initialise the workspace and MCP servers

  1. Click the Extensions icon in the left sidebar and open the watsonx Orchestrate extension.

  2. Click the Initialise Workspace button in the extension panel.

    Initialise Workspace button in the watsonx Orchestrate extension panel

  3. Open the Command Palette (Cmd+Shift+P on macOS / Ctrl+Shift+P on Windows), type watsonx Orchestrate: Install WXO MCP Servers, and press Enter.

Enter 2.14.0 when the MCP installer asks for a version.

Open Settings → MCP and confirm that both watsonx-orchestrate-adk and watsonx-orchestrate-adk-docs are green and show Connected. If either server is not green and connected, stop and ask the instructor for help before continuing.

Open Bob chat and ask:

What watsonx Orchestrate MCP servers are available?

Confirm that Bob reports both the ADK and ADK documentation servers. You can also inspect them from the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) by typing MCP Servers.

7. Configure Bob for the workshop

The custom mode gives Bob a watsonx Orchestrate role and the tools it needs. The workspace rule applies the workshop's ADK 2.14.0 conventions, safety requirements, and known pitfalls in every Bob mode.

Import the WXO Agent Architect mode

  1. Click Download the WXO Agent Architect YAML file. Your browser should save it automatically in your Downloads folder. If it opens the YAML instead, right-click the link and choose Save Link As… (or Download Linked File on macOS).
  2. Open Bob Settings (gear icon ⚙️ in the bottom-right corner) and select Modes.
  3. Click the import icon (↓ down arrow) and choose the YAML file from your Downloads folder.
  4. After the import completes, select WXO Agent Architect in Bob chat.

Install the workspace rule

Download the workshop workspace rule. The downloaded file is named wxo-dev-rule-enhanced.md.

Move it from Downloads into .bob/rules/:

New-Item -ItemType Directory -Force -Path .bob\rules
Move-Item "$env:USERPROFILE\Downloads\wxo-dev-rule-enhanced.md" `
  .bob\rules\wxo-dev-rule-enhanced.md -Force

mkdir -p .bob/rules
mv ~/Downloads/wxo-dev-rule-enhanced.md .bob/rules/

Start a new Bob task after installing the rule.

Checkpoint:

Read the workspace rule in .bob/rules/. Summarize the ADK version, folder,
naming, model, documentation-lookup, and safety conventions you will follow.
Do not create or change files.

Bob should mention ADK 2.14.0, the workshop folders, snake_case, groq/openai/gpt-oss-120b, the documentation MCP, and credential safety.

8. Connect Orchestrate environment

Use the watsonx Orchestrate instance URL and API key from your own provisioned environment. Treat the API key like a password: do not paste it into chat, save it in source files, or commit it.

  1. Click the Extensions icon in the left sidebar, then click on the watsonx Orchestrate extension under Installed.

  2. In the extension panel, open Environment Manager and select Add.

    Environment Manager showing the Add button and Activate option

  3. Enter a short environment name and the supplied instance URL.

  4. Select the environment and choose Activate.
  5. Paste the API key only into the activation prompt.

Verify the connection:

orchestrate agents list

An empty agent list is a successful result.

CLI fallback 
orchestrate env add -n <environment-name> -u <instance-url>
orchestrate env activate <environment-name> -a <api-key>
orchestrate agents list

If activation prints a warning, use orchestrate agents list to confirm authentication before proceeding.

Important

Remote authentication expires periodically. If commands later return an authentication error, reactivate the environment from Environment Manager or run orchestrate env activate <environment-name> again.

Setup checkpoint

Ask Bob to perform the non-secret checks:

Inspect this workshop workspace and verify the setup without changing files.
Use the existing .venv. Check the Python and ADK versions, active Orchestrate
environment, expected workspace folders, and access to both Orchestrate MCP
servers. Run safe list or version commands where useful. Summarize anything I
must fix, but do not ask me to paste an API key into chat.

Your project should now contain a structure similar to:

bobchestrate-ws/
├── .venv/
├── .bob/
│   ├── rules/
│   │   └── wxo-dev-rule-enhanced.md
│   ├── custom_modes.yaml
│   └── mcp.json
├── agents/
├── tools/
├── toolkits/
├── connections/
├── models/
├── knowledge_bases/
└── workspace_config.yaml

Empty folders are expected.

Before continuing, confirm:

  • orchestrate --version reports ADK 2.14.0
  • orchestrate agents list succeeds
  • WXO Agent Architect mode is selected
  • .bob/rules/wxo-dev-rule-enhanced.md exists
  • Bob can access the two Orchestrate MCP servers

Stuck?

Copy the tested configuration files for this part from the reference solution, then continue.

Troubleshooting

orchestrate: command not found

Activate .venv using the platform command in Step 4. If the ADK is still absent, reinstall it from the extension's status indicator.

Authentication failed 
orchestrate env list
orchestrate env activate <environment-name>
orchestrate agents list
Bob cannot access the MCP servers

Open Settings → MCP and confirm that both watsonx-orchestrate-adk and watsonx-orchestrate-adk-docs are green and connected. Restart any stopped server. If either server remains unhealthy, ask the instructor for help instead of continuing.

Windows MCP documentation server fails to start

Use this Windows-only fallback only if the regular MCP setup does not work. Download the Windows fallback mcp.json and replace .bob/mcp.json, then reload Bob. Do not use this fallback on macOS.

A common Windows cause is an incompatible mcp SDK selected by mcp-proxy. Because its dependency range has no upper bound, the resolver can select an SDK that causes ImportError: cannot import name 'request_ctx'. Reconfigure the documentation server with the compatible SDK pin and system certificate support. In PowerShell, use:

uvx --system-certs `
  --with mcp==1.28.0 `
  mcp-proxy `
  --transport streamablehttp `
  https://developer.watson-orchestrate.ibm.com/mcp

If the error is certificate-related, prefer the organization's CA bundle:

--verify-ssl C:\path\to\company-ca-bundle.pem

Use --verify-ssl false only as a temporary diagnostic workaround, not as the permanent configuration. The Watsonx endpoint may still be healthy; this workaround only diagnoses local certificate trust. After updating the server, return to Settings → MCP and confirm that both servers are green and connected.

Continue to Part 2: Building Your First Agent →