### Example Instruction for GPT-OSS Models

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=models-gpt-oss-model-behavior-instruction-guidelines

This example demonstrates how to provide clear, multi-part instructions to GPT-OSS models, specifying tone, tool usage for different data types, and handling of incomplete information. Use this pattern to guide agent behavior effectively.

```text
Always respond in a professional tone. When asked for CRM data, use the salesforce_api tool. If the request involves scheduling, call the calendar_agent. If information is incomplete, ask clarifying questions before proceeding.
```

--------------------------------

### Get All Skills (On-premises)

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=api-getting-started

This example demonstrates how to call the API to get all skills for an on-premises deployment using cURL. You will need to provide your host, port, namespace, instance ID, and Zen API key.

```APIDOC
## GET /orchestrate/{namespace}/instances/{instance_id}/v1/orchestrate/digital-employees/allskills

### Description
Retrieves all available skills for digital employees in an on-premises deployment.

### Method
GET

### Endpoint
https://MYHOST:PORT//orchestrate/MY_NAMESPACE/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace for the on-premises deployment.
- **instance_id** (string) - Required - The instance ID of the deployment.

#### Query Parameters
None

#### Headers
- **Authorization** (string) - Required - ZenApiKey MY_ZEN_API_KEY
- **Accept** (string) - Required - application/json

### Request Example
```bash
curl -X GET "https://MYHOST:PORT//orchestrate/MY_NAMESPACE/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills" \
     -H "Authorization: ZenApiKey MY_ZEN_API_KEY" \
     -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **body** (object) - Contains a list of skills.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Start a Local MCP Server with Node

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=tools-mcp-servers

Use this command to start a local MCP server using Node.js. Ensure Node.js is installed and the 'time-mcp' package is available.

```bash
npx -y time-mcp
```

--------------------------------

### Example Service Instance URL

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=credentials-authentication-types-overview

An example of a service instance URL that can be used to derive the base URL for constructing the callback URL.

```text
`https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/12345678-abcd-90ef-1234-abcdef123456`
```

--------------------------------

### Example Callback URL for watsonx Orchestrate

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=credentials-authentication-types-overview

An example of a complete callback URL based on a specific watsonx Orchestrate environment URL.

```text
`https://dl.watson-orchestrate.ibm.com/mfe_connectors/api/v1/agentic/oauth/_callback`
```

--------------------------------

### Good Instruction Example for GPT-OSS Model

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=models-gpt-oss-model-behavior-instruction-guidelines

This is an example of a concise and effective instruction for a GPT-OSS model. It specifies knowledge base usage, citation requirements, word limits, and fallback behavior.

```text
Use knowledge bases as the primary source. Cite the document name when used. Limit yourself to 3 reasoning steps and less than 150 words in the final answer. If you cannot find an answer in knowledge, say so and ask one clarifying question.
```

--------------------------------

### Agent Referencing Example in GPT-OSS Instructions

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=models-gpt-oss-model-behavior-instruction-guidelines

This example demonstrates how to reference other agents within GPT-OSS instructions, emphasizing the use of `display_name` for proper delegation.

```yaml
kind: native
name: Customer_support_agent
display_name: "ACME Customer Support Agent"
description: "Handles customer inquiries"
instructions: |
  You are a helpful assistant.
  For customer support issues, delegate to 'ACME Customer Support Agent'.
```

--------------------------------

### Milvus Collection Metadata Example

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=repository-enabling-granular-access-control-milvus

Example output from describe_collection() when a user is authorized to access a specific collection, showing its metadata.

```json
{
  "collection_name": "assistant_builder_docs_en_slate_30m_v2",
  "auto_id": true,
  "num_shards": 1,
  "description": "",
  "fields": [
    {
      "field_id": 100,
      "name": "text",
      "description": "",
      "type": "<DataType.VARCHAR: 21>",
      "params": { "max_length": 65535 }
    }
  ]
}
```

--------------------------------

### Example JSON Entry for Bulk User Addition

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=users-managing-aws

This is an example entry for a JSON template used to add members in bulk. It specifies the email address and the assigned role for a user.

```json
{
  "email": "user@example.com",
  "role": "Builder"
}
```

--------------------------------

### Get Install Status in ServiceNow

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=tools-it-operations

Retrieves the installation or deployment status of assets or configuration items in ServiceNow.

```APIDOC
## Get Install Status in ServiceNow

### Description
Retrieves installation/Deployment status of assets or configuration items (for example, In use, Pending install, Retired).

### Method
GET

### Endpoint
/api/v1/servicenow/install-status
```

--------------------------------

### Initialize a List with Variables

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=releases-release-notes-2024

Illustrates initializing a list with variables. All variables must be of the same type.

```text
{example_variable_1,example_variable_2}
```

--------------------------------

### Combined Instruction Example for GPT-OSS Agents

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=models-gpt-oss-model-behavior-instruction-guidelines

A compact template for creating agents using specific GPT-OSS models, combining behavior, reasoning, formatting, and error handling instructions.

```text
Behavior and sources:
- Identify as an agent operating within watsonx Orchestrate. 
- Always use available tools to retrieve information before relying on your internal knowledge. 
- If tools don't contain the answer, explicitly state "The available tools don't contain the answer", state that clearly and ask one clarifying question. Reasoning and brevity controls: 
- Use concise reasoning with at most 3 reasoning steps before responding. 
- Keep chit-chat to one sentence, then proceed. 
- Limit final answers to ≤150 words unless the user requests detail. 
Formatting: - When generating hyperlinks, use the correct Markdown syntax: [link](url). 
Error handling: - If a tool call or retrieval fails, briefly describe the failure and propose the next best step or ask for a missing input.
```

--------------------------------

### Get All Skills (AWS)

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=api-getting-started

This example shows how to fetch all skills using cURL for an AWS deployment. Replace REGION_CODE, MY_INSTANCE_ID, and MY_JWT_TOKEN with your specific credentials.

```APIDOC
## GET /instances/{instance_id}/v1/orchestrate/digital-employees/allskills

### Description
Retrieves all available skills for digital employees in an AWS environment.

### Method
GET

### Endpoint
https://api.REGION_CODE.watson-orchestrate.ibm.com/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills

### Parameters
#### Query Parameters
None

#### Headers
- **Authorization** (string) - Required - Bearer MY_JWT_TOKEN
- **Accept** (string) - Required - application/json

### Request Example
```bash
curl -X GET "https://api.REGION_CODE.watson-orchestrate.ibm.com/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills" \
     -H "Authorization: Bearer MY_JWT_TOKEN" \
     -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **body** (object) - Contains a list of skills.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Initialize a List with Mixed Simple Types and Variables

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=releases-release-notes-2024

Provides an example of initializing a list with a mix of simple values and variables. Ensure type compatibility.

```text
{1, example_variable_1}
```

--------------------------------

### Connect and Send Message (Python)

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=overview-building-custom-client-by-using-api

Use this snippet to create a service object, send an initial empty message to start a conversation, and process the response. Ensure the 'ibm-watson' SDK is installed.

```python
# Example 1: Creates service object, sends initial message, and
# receives response.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Start conversation with empty message.
result = assistant.message_stateless(
    assistant_id,
).get_result()

# Print responses from actions, if any. Supports only text responses.
if result['output']['generic']:
    for response in result['output']['generic']:
        if response['response_type'] == 'text':
            print(response['text'])
```

--------------------------------

### Connect and Send Message (Node.js)

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=overview-building-custom-client-by-using-api

Use this snippet to create a service object, send an initial empty message to start a conversation, and process the response. Ensure the 'ibm-watson' SDK is installed.

```javascript
// Example 1: Creates service object, sends initial message, and
// receives response.

const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {
  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type == 'text') {
          console.log(response.text);
        }
      });
    }
  }
}
```

--------------------------------

### Get All Skills (IBM Cloud)

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=api-getting-started

This example demonstrates how to retrieve all skills using cURL for an IBM Cloud deployment. Ensure you have the correct region code, instance ID, and IAM token.

```APIDOC
## GET /instances/{instance_id}/v1/orchestrate/digital-employees/allskills

### Description
Retrieves all available skills for digital employees.

### Method
GET

### Endpoint
https://api.REGION_CODE.watson.cloud.ibm.com/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills

### Parameters
#### Query Parameters
None

#### Headers
- **Authorization** (string) - Required - Bearer MY_IAM_TOKEN
- **Accept** (string) - Required - application/json

### Request Example
```bash
curl -X GET "https://api.REGION_CODE.watson.cloud.ibm.com/instances/MY_INSTANCE_ID/v1/orchestrate/digital-employees/allskills" \
     -H "Authorization: Bearer MY_IAM_TOKEN" \
     -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **body** (object) - Contains a list of skills.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Define a Guided Customer Journey

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=developing-guiding-customers-journeys

This JSON defines a guided journey for disputing a charge, incorporating text, image, and video responses to guide the user through the process.

```json
{
  "generic": [
    {
      "response_type": "user_defined",
      "user_defined": {
        "card_title": "Let’s dispute a charge!",
        "card_description": "Follow along with this guided journey to learn how to find and dispute charges.",
        "user_defined_type": "IBM_BETA_JOURNEYS_TOUR",
        "steps": [
          {
            "response_type": "text",
            "text": "Charges are listed on the Transactions page. **Click your profile photo** in the top right corner of your screen, and then **click Transactions** from the menu."
          },
          {
            "response_type": "text",
            "text": "Here you can view your charges.\n **Scroll through the Transactions page and review your charges.** Each charge contains a merchant name, transaction date, and amount charged."
          },
          {
            "response_type": "image",
            "source": "https://example.com/image.png",
            "alt_text": "Image showing location of Dispute option",
            "description": "The option to Dispute is marked in red on the right hand side of each row in the Transactions table. Just click here to file a dispute."
          },
          {
            "response_type": "video",
            "source": "https://vimeo.com/769580398",
            "description": "Watch this short video to learn what to expect now that you’ve filed a dispute."
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### Initialize a List with Choice List Values

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=releases-release-notes-2024

Shows how to initialize a list using predefined choice list values. All values must conform to the choice list type.

```text
{US, GB, GER}
```

--------------------------------

### Check if String Starts With Substring

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=reference-expression-language-methods-actions

Returns true if the string starts with the specified substring.

```actionscript
${step_297}.startsWith('What')
```

--------------------------------

### Create Milvus Client Session in Python

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=repository-enabling-granular-access-control-milvus

Establishes a connection to the Milvus service using provided credentials and SSL certificate path. Ensure the URI, username, password, and certificate path are correctly configured.

```python
from pymilvus import MilvusClient
client = MilvusClient(
    uri="<your milvus service URI>", # your Milvus service URI, for example, http://localhost:19530
    user="<your username>",
    password="<your password>",
    server_pem_path="./milvus_onprem_tls.crt" # path to your SSL certificate
)
```

--------------------------------

### Example User Payload for Zendesk

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=integrations-integrating-zendesk

An example of the user payload structure containing name and email for Zendesk integration.

```javascript
    const userPayload = {
     "name" : "Cade Jones",
     "email" : "cade@example.com",
    }
```

--------------------------------

### Initialize a List with Simple Type Values

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=releases-release-notes-2024

Demonstrates initializing a list with simple string values. Ensure all elements are of the same type.

```text
{"a", "b", "c"}
```

--------------------------------

### User Defined Response Example

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=reference-response-types

A generic example of a user-defined response. The 'user_defined' object can contain any valid JSON data.

```json
{
  "generic":[
    {
      "response_type": "user_defined",
      "user_defined": {
        "field_1": "String value",
        "array_1": [
          1,
          2
        ],
        "object_1": {
          "property_1": "Another string value"
        }
      }
    }
  ]
}
```

--------------------------------

### Connect to agent response with all configurable parameters

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=phone-handling-interactions

This example demonstrates a complete _Connect to agent_ response, including SIP transfer details, custom headers, and messages for agent availability and unavailability. Use this when you need to configure all available transfer options.

```json
{
  "generic": [
    {
      "response_type": "connect_to_agent",
      "transfer_info": {
        "target": {
          "service_desk": {
            "sip": {
              "uri": "sip:user\\@domain.com",
              "transfer_headers": [
                {
                  "name": "Customer-Header1",
                  "value": "Some-Custom-Info"
                },
                {
                  "name": "User-to-User",
                  "value": "XXXXXX"
                }
              ],
              "transfer_headers_send_method": "refer_to_header"
            }
          }
        }
      },
      "agent_available": {
        "message": "I'll transfer you to an agent"
      },
      "agent_unavailable": {
        "message": "Sorry, I could not find an agent."
      },
      "message_to_human_agent": "The caller needs help resetting their password"
    }
  ]
}
```

--------------------------------

### Channel Object Example

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=reference-integration-variables

This example shows the structure of the `channel` object, which always included and contains general information about the communication channel.

```json
"channel": {
  {
    "name": "Web chat",
    "private": {
      "user": {
        "id": "anonymous_IBMuid-727c0302-6fd7-4abb-b7ee-f06b4bf30e99"
      }
    }
  }
}
```

--------------------------------

### Add and configure WXO Platform User API connection

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=limitations-building-tools

These commands are used to activate the environment, add the WXO_PLATFORM_USER_API connection, configure it for draft and live environments with a team type and API key, and then set the credentials for both environments.

```bash
$ orchestrate env activate
$ orchestrate connections add -a WXO_PLATFORM_USER_API

$ orchestrate connections configure -a WXO_PLATFORM_USER_API --env draft -t team -k api_key
$ orchestrate connections configure -a WXO_PLATFORM_USER_API --env live -t team -k api_key

$ orchestrate connections set-credentials -a WXO_PLATFORM_USER_API --env draft --api-key
$ orchestrate connections set-credentials -a WXO_PLATFORM_USER_API --env live --api-key
```

--------------------------------

### Example Directory Structure

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=agents-creating-langgraph-package-import

A simple agent structure.

```directory
my-agent/
├── agent.yaml
├── agent.py
└── requirements.txt
```

--------------------------------

### Example Username and API Key Format

Source: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=api-generating-key-premises

This shows the required format for combining your username and API key before Base64 encoding.

```text
myUser:abcdefghijklmnopqrstuvwxyz1234567890
```