watsonx_orchestrate service has 7 resource kinds, each listed below with its endpoints, fields, and dependencies. Values resolve late, so you reference another resource with ${kind.ref_name}. For defaults, validation rules, and examples, run wxctl explain <kind>.
YAML envelope & reference syntax
YAML envelope & reference syntax
- Envelope: A config is one or more YAML documents separated by
---. Each has top-levelkindandref_name, then the fields below at the top level (not nested underspec). ref_name: Unique handle for this resource within the config. Used to reference it from other resources, then stripped before the API call (not a schema field).- References: Reference another resource by its ref_name:
${<kind>.<ref_name>}resolves to its id,${<kind>.<ref_name>.<field>}to a specific field. Values resolve late, at plan/apply time.
agent
An Agent is a configurable AI assistant within Watsonx Orchestrate that can perform tasks using tools, collaborate with other agents, and leverage knowledge bases.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/agents |
| Read | GET | /v1/orchestrate/agents/{id} |
| List | GET | /v1/orchestrate/agents |
| Update | PATCH | /v1/orchestrate/agents/{id} |
| Delete | DELETE | /v1/orchestrate/agents/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the agent. Used as the primary reference for the agent within the system and must be unique across all agents in the tenant. |
display_name | string | Optional | Human-readable display name shown in the UI. This is the friendly name that users will see when interacting with or selecting the agent. |
description | string | Required | Primary description of what the agent does. This serves as the agent’s system prompt and defines its core purpose, behavior, and capabilities. |
instructions | string | Optional | Additional instructions that supplement the description. Used to provide specific behavioral guidelines, constraints, or detailed operating procedures for the agent. |
style | string | Required | Defines the agent’s interaction and reasoning style. The ‘default’ style provides standard conversational responses. The ‘react’ style enables ReAct (Reasoning + Acting) pattern for more deliberate, step-by-step problem solving with explicit reasoning chains. The ‘planner’ style enables advanced planning capabilities for complex multi-step task decomposition and execution. |
llm | string | Required | LLM model identifier that specifies which language model the agent uses. Format typically follows the pattern: provider/model-family/model-name (e.g., watsonx/meta-llama/llama-3-2-90b-vision-instruct). This determines the agent’s language understanding and generation capabilities. |
llm_config | object | Optional | |
structured_output | object | Optional | JSON schema that defines the required structure for the agent’s responses. When configured, the agent will format its outputs to match this schema, enabling consistent, machine-parseable responses for integration with downstream systems. |
hidden | boolean | Optional | Controls visibility when listing agents. When true, the agent is hidden from default agent listings and discovery interfaces. Useful for internal/system agents or work-in-progress agents that shouldn’t be publicly available. |
hide_reasoning | boolean | Optional | When enabled, hides the agent’s internal reasoning steps and chain-of-thought from the user interface. Users will only see the final answer/response, not the intermediate reasoning process. Useful for cleaner UX when reasoning details aren’t needed. |
sync_tool_flow_interactions | boolean | Optional | Enable/disable syncing user interactions from tool flow to the agent |
context_access_enabled | boolean | Optional | Enables the agent to access context variables from the runtime environment. When enabled, the agent can read and utilize context-specific information that may vary by session, user, or environment. |
tools | array<string> | Optional | List of tool names that the agent can invoke to perform actions and retrieve information. Tools extend the agent’s capabilities beyond conversation, enabling it to interact with external systems, APIs, and data sources. |
toolkits | array<string> | Optional | List of toolkit ids available to the agent |
collaborators | array<string> | Optional | List of other agent names that this agent can collaborate with. Enables multi-agent workflows where agents can delegate tasks, consult specialists, and coordinate to solve complex problems. |
knowledge_base | array<string> | Optional | List of knowledge base names that provide the agent with access to document-based information. Enables the agent to retrieve relevant context, facts, and domain-specific knowledge when answering user queries. |
glossary | array<string> | Optional | List of glossary available to the agent |
guidelines | array<object> | Optional | Behavioral guidelines that define specific rules, policies, or constraints the agent should follow. Each guideline is an object with display_name (optional), condition (when the guideline applies), and action (what the agent should do). |
connection_ids | array<string> | Optional | List of connection IDs for direct agent-to-connection bindings |
context_variables | array<string> | Optional | List of specific context variable names that this agent is permitted to access. Only the variables listed here will be available to the agent when context_access_enabled is true. Provides fine-grained control over what contextual information the agent can utilize. |
additional_properties | object | Optional | Container for additional agent settings such as starter_prompts (suggested conversation starters shown to users), welcome_content (initial greeting message), and other UI/UX customizations defined in the AgentAdditionalPropertiesIn schema. |
chat_with_docs | object | Optional | Configuration for the Chat with Documents feature, which allows agents to dynamically create and interact with document-based knowledge bases during conversation threads. Enables document upload and contextual Q&A within chat sessions. |
tags | array<string> | Optional | Categorization tags for organizing and filtering agents. Used for grouping related agents and enabling tag-based search and discovery within the system. |
id, agent_mapping, environments, tenant_id, created_by, created_on, updated_by, updated_at, deleted_by, deleted_at.
Depends on
llm→model(optional)tools→tool(optional)toolkits→toolkit(optional)collaborators→agent(optional)knowledge_base→knowledge_base(optional)
agent→.collaborators(optional)agent_release→.agent_id(required)
agent_release
Deploys (releases) a watsonx Orchestrate agent’s current draft to the live environment.
Runs on SaaS + Software · ID field version
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/agents/{agent_id}/releases |
| Read | GET | /v1/orchestrate/agents/{agent_id}/environment |
| List | GET | /v1/orchestrate/agents/{agent_id}/environment |
| Update | POST | /v1/orchestrate/agents/{agent_id}/environment |
| Delete | DELETE | /v1/orchestrate/agents/{agent_id}/environment |
| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | Required | Id of the agent to release. Fills {agent_id} on every endpoint; references agent.id so the release orders after the agent in the DAG. Path (not LocalOnly) so build.rs emits the edge (ordering-only-reference-fields-localonly-no-edge-fix). |
environment | string | Optional | Target environment. Only live is supported (draft is the working state; there is no third environment). Matched against each remote env’s name in discovery. |
version | integer | Optional | Omit to release the current draft (auto-latest, known after apply); set to an existing version to pin/roll the live environment to it (repoint owned by pre_update in Phase 2). |
comments | string | Optional | Optional release comment. LocalOnly, folded into the release body by the handler (not materialized generically). Carries no references, so no edge is lost. |
environment_id, current_version, status.
Depends on
agent_id→agent(required)
knowledge_base
A Knowledge Base provides document-based context and information retrieval capabilities for agents.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/knowledge-bases/documents |
| Read | GET | /v1/orchestrate/knowledge-bases/{id} |
| List | GET | /v1/orchestrate/knowledge-bases |
| Update | PATCH | /v1/orchestrate/knowledge-bases/{id}/documents |
| Delete | DELETE | /v1/orchestrate/knowledge-bases/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the knowledge base. Used as the primary reference for the knowledge base within the system and must be unique across all knowledge bases in the tenant. |
display_name | string | Optional | Human-readable display name shown in the UI. This is the friendly name that users will see when browsing or selecting knowledge bases for their agents. |
description | string | Optional | Textual description explaining what content and information this knowledge base contains. Helps users understand the scope and subject matter of the knowledge base. |
prioritize_built_in_index | boolean | Optional | When both a built-in vector index and external index are available, this flag determines which to prioritize for search queries. True (default) prioritizes the built-in index managed by Watsonx Orchestrate. |
representation | string | Optional | Defines how the knowledge base is represented and accessed by agents. The ‘tool’ representation exposes the knowledge base as a callable tool that agents can invoke for information retrieval. |
vector_index | object | Optional | Configuration for the built-in vector index that enables semantic search over ingested documents. Defines how documents are processed, chunked, embedded, and retrieved during conversational search operations. |
conversational_search_tool | object | Optional | Comprehensive configuration for the conversational search tool that enables natural language querying over the knowledge base. Controls retrieval behavior, response generation, confidence thresholds, citations, and other advanced search features. |
documents | array<object> | Optional | Array of document objects to ingest into the knowledge base via multipart form upload. Each document specifies a local file path to upload and optionally a source URL for metadata tracking. Documents are processed, chunked, and indexed for semantic search. |
id, tenant_id, created_by, updated_at.
Consumers
agent→.knowledge_base(optional)
model
A Model Configuration defines custom language model settings and parameters for use within Watsonx Orchestrate.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/models |
| Read | GET | /v1/orchestrate/models/{id} |
| List | GET | /v1/orchestrate/models |
| Update | PUT | /v1/orchestrate/models/{id} |
| Delete | DELETE | /v1/orchestrate/models/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Unique name identifier for the model configuration. Typically follows the format virtual-model/provider/model-name (e.g., watsonx/meta-llama/llama-3-2-90b-vision-instruct). This is the identifier that agents use when specifying which LLM to use. |
display_name | string | Required | Human-readable display name shown in the UI when selecting or managing models. Provides a friendly name that users can easily recognize. |
provider_config | object | Required | Provider-specific configuration object that identifies which LLM provider this model uses (e.g., watsonx, openai, anthropic). Contains provider name and any provider-specific settings. Additional provider keys not declared below pass through unchanged, only the fields needing cross-resource references are declared here. |
config | object | Optional | Inference-time model configuration (the wxO API’s ModelConfig object). Keys pass through unchanged; commonly used keys are model (the provider-side model id), max_tokens / max_completion_tokens (completion budget; the watsonx.ai default is 1024, which reasoning models such as gpt-oss can exhaust on reasoning_content before emitting any answer text), reasoning_effort (low, medium, high), temperature, thinking, parallel_tool_calls, disable_tool_validation, and response_format. |
description | string | Optional | Textual description of the model configuration, explaining what the model is for, its capabilities, use cases, or any special configuration notes. |
tags | array<string> | Optional | Categorization tags for organizing and filtering model configurations. Useful for grouping models by capability, use case, cost tier, or other organizational criteria. |
model_type | string | Required | Specifies the category and usage pattern of the model. ‘chat’ models are for conversational interactions, ‘completion’ models generate text continuations, and ‘embedding’ models convert text into vector representations for semantic search. |
connection_id | string | Required | Reference to the orchestrate connection that provides authentication credentials for accessing the model’s API. Links this model config to the appropriate connection resource that handles authentication and API access. |
title | string | Optional | Optional title for the model configuration. Can be used for additional labeling or categorization beyond the display_name. |
api_base | string | Optional | Custom base URL for the model’s API endpoint. Overrides the default API endpoint when connecting to custom deployments or alternative hosting environments. |
api_version | string | Optional | Specific API version to use when invoking the model. Allows pinning to particular API versions for stability or accessing version-specific features. |
deployment_id | string | Optional | Identifier for a specific model deployment or instance. Used when the provider supports multiple deployments of the same model with different configurations or scaling. |
id, tenant_id, tenant_name, created_on, created_by, created_by_username, updated_at, model_name, provider.
Depends on
provider_config.watsonx_deployment_id→wml_deployment(optional)provider_config.watsonx_project_id→project(optional)provider_config.watsonx_space_id→space(optional)connection_id→orchestrate_connection(required)
agent→.llm(optional)
- warn (doc_cited, 2026-06-12): A watsonx Orchestrate model’s connection_id must reference an Orchestrate connection (orchestrate_connection), not a Common Core (CAMS) common_core_connection. A CAMS connection asset id is accepted at create time but inference then fails, because the AI gateway cannot resolve credentials from it. Share cross-product credentials through an Orchestrate connection instead.
orchestrate_connection
A Connection represents authentication credentials and configuration for integrating external applications with Watsonx Orchestrate.
Runs on SaaS + Software · ID field app_id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/connections/applications |
| Read | GET | /v1/orchestrate/connections/applications/{app_id} |
| List | GET | /v1/orchestrate/connections/applications |
| Delete | DELETE | /v1/orchestrate/connections/applications/{app_id} |
| Field | Type | Required | Description |
|---|---|---|---|
connection_type | string | Required | Type of connection being created. Used during CREATE operations to specify which authentication mechanism to configure. Each type requires different credential fields. |
credentials | object | Required | JSON object containing the authentication credentials specific to the connection_type. Structure varies based on authentication method (e.g., username/password for basic_auth, tokens for OAuth2). Used during CREATE operations only. |
app_id | string | Required | Application identifier or name that uniquely identifies the external application being connected. This serves as the primary reference for the connection and must be unique within the tenant. |
name | string | Optional | Human-readable display name for the connection. If not provided, defaults to the app_id. This is the friendly name shown in UI when selecting or managing connections. |
description | string | Optional | Textual description of what this connection is for and what external service it connects to. Helps users understand the purpose and scope of the connection. |
icon | string | Optional | SVG icon data or icon reference for visual representation of the connected application. Used in UI to provide visual identification of the connection type or service. |
environment | array<string> | Optional | Environments to configure this connection for, as a list. Each element must be draft (pre-production) or live (production). Declare both (for example [draft, live]) to configure the connection in both environments; a deployed agent runs in live, so its connections need a live configuration. Each listed environment is configured independently at apply time. |
preference | string | Optional | Preference scope for the connection configuration (e.g., team, personal). Determines whether credentials are shared across a team or kept personal to individual users. |
config_security_scheme | string | Optional | Security scheme to use for post-creation configuration (e.g., key_value_creds). Applied when setting up connection authentication after initial creation. |
config_auth_type | string | Optional | Authentication type for post-creation configuration. Specifies the auth mechanism when configuring connection settings via the post_create hook. |
config_sso | boolean | Optional | Flag indicating whether Single Sign-On should be enabled during post-creation configuration. Used when setting up SSO authentication for the connection. |
config_server_url | string | Optional | Server URL to configure during post-creation setup. Allows specifying the API endpoint when configuring connection after creation. |
idp_config_data | object | Optional | Identity Provider (IDP) configuration data object for SSO and OAuth flows. Contains provider-specific settings needed for third-party authentication integration. |
app_config_data | object | Optional | Application-specific configuration data for the connection. Contains settings and parameters specific to the connected application’s API requirements. |
runtime_credentials | object | Optional | Runtime credentials object to be applied after the connection configuration is complete. Used to set actual credential values during the post-creation configuration phase. |
configured_environments | array<string> | Optional | Handler-managed state: the sorted, deduped set of environments this connection is currently configured for. Not user-settable. The handler sets it in post_validate from environment (desired) and in post_discover by probing the API (remote); it participates in state comparison so a missing environment on an existing connection reconciles as an in-place Update (converge), never a recreate. |
tenant_id, is_connected, connection_id, created_on, security_scheme, auth_type, sso, server_url, credentials_entered.
Consumers
model→.connection_id(required)tool→.binding.openapi.connection_id(optional)tool→.binding.python.connections(optional)toolkit→.mcp.connections(optional)
tool
A Tool is a specification for a callable function or service that agents can invoke to perform actions and retrieve information.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/tools |
| Read | GET | /v1/orchestrate/tools/{id} |
| List | GET | /v1/orchestrate/tools |
| Update | PUT | /v1/orchestrate/tools/{id} |
| Delete | DELETE | /v1/orchestrate/tools/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Optional | Unique name identifier for the tool. Used as the primary reference for the tool and must be unique across all tools in the tenant. Agents and users reference tools by this name. |
display_name | string | Optional | Human-readable display name shown in the UI when browsing or selecting tools. Provides a friendly name that users can easily recognize and understand. |
description | string | Optional | Detailed description of what the tool does, when to use it, and what it returns. This description is crucial as it helps agents (via LLM reasoning) decide when to invoke the tool and how to use it effectively. |
permission | string | Required | The permission level required to use this tool, controlling what operations it can perform and how agents reason about its safety. ‘read_only’ tools can only retrieve data without side effects. ‘write_only’ tools can create or modify resources. ‘read_write’ tools can both read and write data. ‘admin’ tools have elevated privileges for system-level operations. |
input_schema | object | Optional | JSON Schema defining the input parameters that the tool accepts. Loaded from schema.yaml in the source directory. Defines parameter names, types, descriptions, and constraints that help agents understand how to invoke the tool with correct arguments. |
output_schema | object | Optional | JSON Schema defining the structure and meaning of the tool’s output. Loaded from schema.yaml in the source directory. Helps agents understand what information the tool returns and how to interpret and use the results. |
binding | object | Optional | Binding configuration that specifies how the tool is implemented and executed. Defines the execution runtime (Python, API, etc.) and provides the necessary references and settings to invoke the actual tool implementation. |
tags | array<string> | Optional | Categorization tags for organizing and discovering tools. Tags help users filter and find tools by capability, domain, or use case (e.g., ‘data’, ‘analytics’, ‘integration’). |
is_async | boolean | Optional | Whether the tool execution is asynchronous. When true, the tool returns an acknowledgment immediately and the actual result is delivered via callback. Asynchronous tools are suitable for long-running operations where the agent should not block waiting for completion. |
source_path | string | Optional | Local filesystem path to the tool source. For Python bindings, this is a directory containing schema.yaml, Python files, and optionally requirements.txt. For flow bindings, this is a path to a flow definition file (.json, .yaml, or .yml). |
spec_path | string | Optional | Path to an OpenAPI specification file (YAML or JSON). Used with binding.openapi. The spec is parsed to auto-discover endpoints and generate tool definitions. Each endpoint becomes an individual tool with schemas extracted from the spec. |
flow_path | string | Optional | Path to a flow definition file (.json, .yaml, or .yml). Used with binding.flow. Additive alias for source_path, both fields work for flow bindings: the flow handler reads source_path first, then falls back to flow_path. Both are resolved against the config dir by resolve_file_paths. |
flow_llm_model | string | Optional | Model the flow runtime uses for the LLM-backed auto-data-mapping nodes (script/decisions). Accepts a ${model.<ref>} reference (resolved to the model name) or a literal model name; the flow handler injects it into the registered flow’s metadata.llm_model. Use this on deployments whose flow runtime has no usable default flow model, e.g. a CP4D AI-Gateway instance, where it routes flow inference through the same gateway model the agents use. Optional: when unset, the flow runtime falls back to the instance DEFAULT_FLOW_LLM_MODEL (sufficient on SaaS). Local-only: consumed at registration, never sent as its own API field. |
artifact | object | Optional | Local reference to the tool artifact ZIP file that will be uploaded to the API. This ZIP contains the Python code, schema, and dependencies. Automatically generated from source_path during tool creation. This is a local-only field for managing the upload. |
id.
Depends on
binding.openapi.connection_id→orchestrate_connection(optional)binding.python.connections→orchestrate_connection(optional)
agent→.tools(optional)
toolkit
An MCP (Model Context Protocol) toolkit backed by a local or remote MCP server.
Runs on SaaS + Software · ID field id
Endpoints
| Operation | Method | Path |
|---|---|---|
| Create | POST | /v1/orchestrate/toolkits |
| Read | GET | /v1/orchestrate/toolkits/{id} |
| List | GET | /v1/orchestrate/toolkits |
| Delete | DELETE | /v1/orchestrate/toolkits/{id} |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Required | Display name of the toolkit. Used for discovery matching and must be unique within the tenant. |
description | string | Required | Human-readable description of the toolkit. |
mcp | object | Optional | MCP server configuration. Defines how the runtime connects to or starts the MCP server. |
server_path | string | Optional | Path to an MCP server source directory. Used with source: files. The directory is packaged as a ZIP and uploaded to the toolkits API. |
artifact | object | Optional | Internal reference to the generated ZIP artifact. |
tags | array<string> | Optional | Local-only tags used internally by the artifact build pipeline. The toolkit API does not support tags, these are not persisted remotely or used in reconciliation. |
id.
Depends on
mcp.connections→orchestrate_connection(optional)
agent→.toolkits(optional)