Mastering watsonx Orchestrate REST APIs

source ./.venv/bin/activate
orchestrate server start --env-file .env

orchestrate env activate local

grep -R "wxo_mcsp_token" ~/.cache/orchestrate/credentials.yaml

findstr "wxo_mcsp_token" %USERPROFILE%\.cache\orchestrate\credentials.yaml

auth:
  local:
    wxo_mcsp_token: YOUR_TOKEN_HERE

orchestrate agents list

import requests
import json
import time

# Configuration
token = "your_wxo_mcsp_token_here"
agent_id = "your_agent_id_here"
base_url = "http://localhost:4321/api/v1/orchestrate"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

def get_run_result(run_id, max_attempts=30, delay=2):
    """Poll for the run result until it's complete"""
    get_url = f"{base_url}/runs/{run_id}"
    
    for attempt in range(max_attempts):
        try:
            resp = requests.get(get_url, headers=headers, timeout=10)
            resp.raise_for_status()
            run_data = resp.json()
            
            status = run_data.get("status", "unknown")
            print(f"Run status (attempt {attempt + 1}): {status}")
            
            if status == "completed":
                return run_data
            elif status in ["failed", "cancelled"]:
                return {"error": f"Run {status}", "details": run_data}
            
            time.sleep(delay)
            
        except Exception as e:
            print(f"Error checking run status: {e}")
            time.sleep(delay)
    
    return {"error": "Timeout waiting for run to complete"}

def call_orchestrate(question):
    """Invoke an agent using the Runs API"""
    chat_url = f"{base_url}/runs"
    
    payload = {
        "agent_id": agent_id,
        "message": {
            "role": "user",
            "content": question
        }
    }

    print("Sending payload:", json.dumps(payload, indent=2))
    resp = requests.post(chat_url, headers=headers, json=payload, timeout=10)
    resp.raise_for_status()
    data = resp.json()
    print("Initial API response:", json.dumps(data, indent=2))
    
    # Get the actual run result
    run_id = data.get("run_id")
    if run_id:
        print(f"Waiting for run {run_id} to complete...")
        run_result = get_run_result(run_id)
        print("Final run result:", json.dumps(run_result, indent=2))
        return run_result
    else:
        return {"error": "No run_id in response", "response": data}

def parse_agent_response(response):
    """Parse the agent response to extract answer and citations"""
    try:
        result_data = response.get('result', {}).get('data', {}).get('message', {})
        content = result_data.get('content', [])
        
        if content and len(content) > 0:
            answer_text = content[0].get('text', 'No answer found')
            citations = content[0].get('citations', [])
            
            print("Agent Response:", answer_text)
            
            if citations:
                print("\nSources:")
                for i, citation in enumerate(citations, 1):
                    title = citation.get('title', 'Unknown source')
                    url = citation.get('url', '')
                    if len(url) > 60:
                        display_url = url[:60] + "..."
                    else:
                        display_url = url
                    print(f"  [{i}] {title}")
                    if display_url:
                        print(f"      {display_url}")
        else:
            print("Agent: No content found in response")
    except Exception as e:
        print(f"Agent: Error parsing response - {e}")
        print("Raw response:", response)

# Example usage
if __name__ == "__main__":
    question = "Analyze the recent sales data from our Elasticsearch database"
    response = call_orchestrate(question)
    parse_agent_response(response)

import requests
from modules import token

agent_id = "your_agent_id"
url = f"http://localhost:4321/api/v1/orchestrate/{agent_id}/chat/completions"

token = "your_wxo_mcsp_token"

payload = {
    "messages": [
        {
            "role": "human",
            "content": "Analyze the recent sales data from our Elasticsearch database"
        }
    ],
    "additional_parameters": {},
    "context": {},
    "stream": False
}

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Invoke the agent
response = requests.request("POST", url, json=payload, headers=headers)
print(f"Agent response:\n{response.text}\n")

Basic Message Structure:

{
  "message": {
    "role": "user",
    "content": [
      {
        "response_type": "conversational_search"
      }
    ],
    "mentions": [
      {
        "type": "document",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "Sales Report 2024"
      }
    ],
    "document_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "parent_message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "additional_properties": {
      "wxa_message": {},
      "display_properties": {
        "skip_render": false,
        "is_async": false
      },
      "tool_calls": [
        {}
      ],
      "tool_call_id": "tool_123",
      "tool_name": "elasticsearch_tool",
      "wxo_connection_status": {
        "connection_status": "connected",
        "connection_message": "Successfully connected to Elasticsearch"
      }
    },
    "assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "context": {
      "values": []
    },
    "step_history": [
      {}
    ],
    "message_state": {}
  }
}

Common LLM Parameters:

"llm_params": {
  "temperature": 0.7,           // Controls randomness (0.0-1.0)
  "max_new_tokens": 1000,       // Maximum response length
  "top_p": 0.9,                // Nucleus sampling parameter
  "top_k": 50,                 // Top-k sampling
  "repetition_penalty": 1.1,    // Prevents repetitive text
  "stop_sequences": ["\n\n", "END"], // Stop generation at these tokens
  "time_limit": 30,            // Maximum processing time (seconds)
  "return_options": {
    "generated_tokens": true,   // Include token-level details
    "input_tokens": true,       // Include input tokenization
    "token_logprobs": true      // Include probability scores
  }
}

Guardrails Configuration:

"guardrails": {
  "hap": {                     // Harmful content detection
    "input": {
      "enabled": true,
      "threshold": 0.8
    },
    "output": {
      "enabled": true,
      "threshold": 0.8
    }
  },
  "social_bias": {             // Bias detection
    "input": {
      "enabled": true,
      "threshold": 0.7
    },
    "output": {
      "enabled": true,
      "threshold": 0.7
    }
  },
  "pii": {                     // Personal data protection
    "input": {
      "enabled": true,
      "threshold": 0.9
    },
    "output": {
      "enabled": true,
      "threshold": 0.9
    }
  }
}

python agent_orchestrator.py

Correct (Runs API):

{
    "agent_id": "your_agent_id",
    "message": {
        "role": "user",
        "content": "Your question here"
    }
}

Incorrect (Chat Completions API):

{
    "messages": [
        {
            "role": "human",
            "content": "Your question here"
        }
    ],
    "additional_parameters": {
        "max_tokens": 1000
    }
}