---
title: "List Registered Agents"
method: GET
path: "/v1/orchestrate/agents"
tags: ["Agents"]
---

# List Registered Agents

`GET /v1/orchestrate/agents`

Lists all registered agents.

Query Parameters:
    include: List of additional scopes to include. Supported values:
        - 'global': Include agents from global workspace along with the specified workspace

## Query parameters

- `show_bundled` boolean
- `include_hidden` boolean
- `ids` string[], nullable
- `names` string[], nullable
- `workspace_id` string, uuid, nullable — Filter agents by workspace ID. If not provided, returns agents from global workspace (workspace_id is null)
- `include` string[], nullable — Include additional workspace scopes. Use 'global' to include global workspace agents along with workspace-specific agents

## Response `200`

Successful Response

- union
  - ListAgent[]
    - `id` string, uuid, required — Unique identifier for the agent
    - `tenant_id` string, required — ID of the tenant that owns this agent
    - `workspace_id` string, uuid, nullable — ID of the workspace that owns this agent
    - `name` string, required — Name of the agent
    - `description` string, required — Description of what the agent does
    - `instructions` string, nullable — Instructions for the agent
    - `tools` string[] — List of tool names available to the agent
    - `collaborators` string[] — List of other agent names this agent can collaborate with
    - `knowledge_base` string[]
    - `llm` string, nullable — LLM identifier for the agent
    - `style` 'default' | 'react' | 'planner' | 'custom' | 'react_intrinsic' | 'experimental_customer_care' | 'code_act', required
    - `supported_apps` SupportedApp[], nullable — Supported apps of the agent
    - `created_by` string, required — ID of the user who created the agent
    - `created_on` string, date-time, required — Creation timestamp
    - `updated_by` string, required — ID of the user who updated the agent
    - `updated_at` string, date-time, required — Last update timestamp
    - `deleted_by` string, nullable
    - `deleted_at` string, date-time, nullable
    - `environments` EnvironmentSchema[] — List of simplified environments associated with the agent
      - `id` string, uuid, required — Unique identifier for the environment
      - `name` string, required — Name of the environment
      - `current_version` integer, nullable — current_version
      - `voice` object, nullable — Voice configuration for the environment
      - `enable_wxg_integration` string, nullable — Flag to enable/disable wxg integration
      - `wxg_metrics_url` string, nullable — URL to watsonx.governance metrics dashboard for this agent
    - `agent_mapping` object, nullable
    - `hidden` boolean — To show or hide agent when agents are listed
    - `display_name` string, nullable — Display name of the agent
    - `structured_output` object, nullable — JSON schema defining the structure for agent responses
    - `custom_join_tool` string, nullable — Reference to a Python tool that will be used for custom synthesis of task results
    - `guidelines` Guideline[] — List of guidelines for the agent behavior
      - `display_name` string, nullable — Display name of the guideline
      - `condition` string, required — Condition when the guideline should be applied
      - `action` string, required — Action to take when the condition is met
      - `tool` string, nullable — The tool id use for this guideline
    - `tags` string[], nullable — List of tags associated to agent
    - `chat_with_docs` ChatWithDocsConfig
      - `enabled` boolean — Controls if the Chat with Documents feature is enabled for this agent
      - `supports_full_document` boolean — Controls if the Agent can request to use the full document. Only used if generation.enabled = false
      - `vector_index` KnowledgeBaseBuiltInVectorIndexConfig
        - `embeddings_model_name` string, nullable
        - `chunk_size` integer
        - `chunk_overlap` integer
        - `limit` integer
        - `extraction_strategy` 'express' | 'standard' | 'high_quality'
      - `generation` GenerationConfiguration — example { "model_id": "meta-llama/llama-3-1-70b-instruct", "prompt_instruction": "When the documents are in different languages, you should respond in english.", "max_docs_passed_to_llm": 5, "retrieval_confidence_threshold": "Lowest", "generated_response_length": "Moderate", "response_confidence_threshold": "Low", "display_text_no_results_found": "no docs found", "display_text_connectivity_issue": "conn failed", }
        - `model_id` string, nullable
        - `prompt_instruction` string
        - `max_docs_passed_to_llm` integer
        - `generated_response_length` 'Concise' | 'Moderate' | 'Verbose'
        - `display_text_no_results_found` string
        - `display_text_connectivity_issue` string
        - `idk_message` string
        - `enabled` boolean
      - `query_rewrite` QueryRewriteConfig — example { "enabled": True, "model_id": "meta-llama/llama-3-1-70b-instruct" }
        - `enabled` boolean
        - `model_id` string, nullable
      - `confidence_thresholds` ConfidenceThresholds
        - `retrieval_confidence_threshold` 'Off' | 'Lowest' | 'Low' | 'High' | 'Highest'
        - `response_confidence_threshold` 'Off' | 'Lowest' | 'Low' | 'High' | 'Highest'
      - `citations` CitationsConfig — example: { "citation_title": "how do i know", "citations_shown": 5, }
        - `citation_title` string
        - `citations_shown` integer
      - `hap_filtering` HAPFiltering — example { "output": { "enabled": True, "threshold": 0.7, } }
        - `output` HAPFilteringConfig
          - `enabled` boolean
          - `threshold` number
      - `query_source` 'SessionHistory' | 'Agent'
      - `agent_query_description` string
    - `voice_configuration_id` string, uuid, nullable — Voice configuration for the agent
    - `voice_webhook_connections` object, nullable — Voice webhook connections organized by environment (draft/live)
    - `additional_properties` AgentAdditionalProperties — A specification for settings within an agent. This schema is used for OUTPUT (reading from database). Database stores nested format: {"en": [...], "es": [...]} Using Dict[str, Any] preserves the nested language structure.
      - `icon` string, nullable — xml strings or encoded base64 image data
      - `starter_prompts` object, nullable — Agent Starter Prompts (nested by language)
      - `welcome_content` object, nullable — Agent Welcome Message (nested by language)
      - `context_settings` ContextSettings — Context management settings for an agent.
        - `context_compaction_enabled` boolean, nullable — Enable context compaction
        - `context_compaction_threshold` integer, nullable — Token threshold for context compaction
        - `compaction_sliding_window` integer, nullable — Sliding window size for compaction
        - `large_message_threshold` integer, nullable — Token threshold for large message handling
        - `large_message_chunk_size` integer, nullable — Chunk size for large message processing
        - `large_message_target_summary` integer, nullable — Target summary size for large messages
        - `large_message_detect_structured` boolean, nullable — Enable structured data detection
      - `realtime_agent_settings` RealtimeAgentSettings — Base model for realtime agent settings
        - `enabled` boolean, nullable — Whether the realtime agent is enabled
    - `context_access_enabled` boolean — Enable access to context variables for this agent
    - `connection_ids` string[] — List of connection IDs for direct agent-to-connection bindings
    - `context_variables` string[] — List of context variable names that this agent can access
    - `hide_reasoning` boolean — Enable/disable reasoning trace
    - `sync_tool_flow_interactions` boolean — Enable/disable syncing user interactions from tool flow to the agent
    - `restrictions` string — Enable editable for the colloborator agent
    - `bundled` boolean, nullable — Catalog Agent bundled flag
    - `bundled_agent_id` string, uuid, nullable — Base agent id
    - `llm_config` ModelConfig
      - `decoding_method` string, nullable
      - `prompt` union
        - string
        - string[]
      - `max_tokens` integer, nullable
      - `max_completion_tokens` integer, nullable
      - `temperature` number, nullable
      - `top_p` number, nullable
      - `n` integer, nullable
      - `stream` boolean, nullable
      - `logprobs` integer, nullable
      - `top_logprobs` boolean, nullable
      - `echo` boolean, nullable
      - `stop` union
        - string
        - string[]
      - `presence_penalty` number, nullable
      - `frequency_penalty` number, nullable
      - `best_of` integer, nullable
      - `logit_bias` object, nullable
      - `user` string, nullable
      - `context` string, nullable
      - `examples` Examples[], nullable
        - `input` unknown, required
        - `output` unknown, required
      - `top_k` integer, nullable
      - `response_format` ResponseFormat
        - `type` string, required
        - `json_schema` unknown
      - `seed` integer, nullable
      - `store` boolean, nullable
      - `metadata` object, nullable
      - `modalities` string[], nullable
      - `audio` AudioConfig
        - `voice` string, required
        - `format` string, required
      - `service_tier` string, nullable
      - `prediction` Prediction
        - `type` string, required
        - `content` union, required
          - PredictionContent[]
            - `type` string, required
            - `text` string, required
          - string
      - `safety_settings` unknown
      - `anthropic_beta` string, nullable
      - `anthropic_version` string, nullable
      - `thinking` Thinking
        - `type` string, nullable
        - `budget_tokens` integer, required
      - `space_id` string, nullable
      - `project_id` string, nullable
      - `reasoning_effort` string, nullable
      - `parallel_tool_calls` boolean, nullable
      - `disable_parallel_tool_use` boolean, nullable
      - `disable_tool_validation` boolean, nullable
      - `verbosity` string, nullable
      - `thinking_level` string, nullable
    - `plugins` Plugins
      - `agent_pre_invoke` Plugin[], nullable — Plugins to the invoke before agent
        - `plugin_id` string — Plugins to the invoke before agent
      - `agent_post_invoke` Plugin[], nullable — Plugins to the invoke after agent
        - `plugin_id` string — Plugins to the invoke before agent
    - `toolkits` string[] — List of toolkit ids available to the agent
    - `memory_enabled` boolean — Enable/disable agentic memory for this agent
    - `is_schedulable` boolean — Indicates whether this agent can be scheduled for tasks
    - `custom_agents_metadata` CustomAgentsMetadata — Metadata for custom agents extracted from uploaded packages.
      - `language` string, nullable — Programming language (e.g., 'Python', 'TypeScript')
      - `framework` string, nullable — Framework used (e.g., 'LangGraph')
      - `tool_count` integer, nullable — Number of tools included in the agent
      - `tool_names` string[], nullable — Names of tools included in the agent
      - `connection_requirements` object, nullable — Dictionary of required connections for the agent, mapping tool names to connection requirements and global requirements
    - `deleted_semantic_versions` string[] — Track deleted semantic versions to prevent reuse (V2 API)
  - ListAgentVersion[]
    - `id` string, uuid, required — Unique identifier for the agent
    - `tenant_id` string, required — ID of the tenant that owns this agent
    - `name` string, required — Name of the agent
    - `description` string, required — Description of what the agent does
    - `version_label` integer, required — Version of the deployed agent
    - `semantic_version` string, nullable — Semantic version (e.g., 1.2.0)
    - `version_name` string, nullable — Human-readable version name
    - `version_description` string, nullable — Description of changes in this version
    - `instructions` string, nullable — Instructions for the agent
    - `tools` union[] — List of tool names available to the agent
      - union
        - string
        - object
    - `collaborators` union[] — List of other agent names this agent can collaborate with
      - union
        - string
        - object
    - `llm` string, nullable — LLM identifier for the agent
    - `style` 'default' | 'react' | 'planner' | 'custom' | 'react_intrinsic' | 'experimental_customer_care' | 'code_act', required
    - `supported_apps` SupportedApp[], nullable — Supported apps of the agent
    - `points_to` string[] — Environment IDs points to this version
    - `comments` string, nullable — Comments added by the user while deploying an agent
    - `mapped_environments` EnvironmentSchema[], nullable — List of Environments points to the agent version
      - `id` string, uuid, required — Unique identifier for the environment
      - `name` string, required — Name of the environment
      - `current_version` integer, nullable — current_version
      - `voice` object, nullable — Voice configuration for the environment
      - `enable_wxg_integration` string, nullable — Flag to enable/disable wxg integration
      - `wxg_metrics_url` string, nullable — URL to watsonx.governance metrics dashboard for this agent
    - `created_by` string, required — ID of the user who created the agent
    - `created_on` string, date-time, required — Creation timestamp
    - `updated_by` string, required — ID of the user who updated the agent
    - `updated_at` string, date-time, required — Last update timestamp
    - `deleted_by` string, nullable
    - `hidden` boolean — To show or hide agent when agents are listed
    - `environments` EnvironmentSchema[] — List of simplified environments associated with the agent
      - `id` string, uuid, required — Unique identifier for the environment
      - `name` string, required — Name of the environment
      - `current_version` integer, nullable — current_version
      - `voice` object, nullable — Voice configuration for the environment
      - `enable_wxg_integration` string, nullable — Flag to enable/disable wxg integration
      - `wxg_metrics_url` string, nullable — URL to watsonx.governance metrics dashboard for this agent
    - `deleted_at` string, date-time, nullable
    - `knowledge_base` string[], nullable — List of knowledge_base available to the agent
    - `display_name` string, nullable — Display name of the agent
    - `structured_output` object, nullable — JSON schema defining the structure for agent responses
    - `guidelines` Guideline[] — List of guidelines for the agent behavior
      - `display_name` string, nullable — Display name of the guideline
      - `condition` string, required — Condition when the guideline should be applied
      - `action` string, required — Action to take when the condition is met
      - `tool` string, nullable — The tool id use for this guideline
    - `custom_join_tool` object, nullable — Reference to a Python tool ID that will be used for custom synthesis of task results
    - `tags` string[], nullable — List of tags associated to agent
    - `voice_configuration_id` string, uuid, nullable — Voice configuration for the agent
    - `deployment_status` string, nullable — V1 API: Single deployment status for backward compatibility
    - `deployment_statuses` object, nullable — V2 API: Per-environment deployment statuses {env_id: status}
    - `chat_with_docs` ChatWithDocsConfig
      - `enabled` boolean — Controls if the Chat with Documents feature is enabled for this agent
      - `supports_full_document` boolean — Controls if the Agent can request to use the full document. Only used if generation.enabled = false
      - `vector_index` KnowledgeBaseBuiltInVectorIndexConfig
        - `embeddings_model_name` string, nullable
        - `chunk_size` integer
        - `chunk_overlap` integer
        - `limit` integer
        - `extraction_strategy` 'express' | 'standard' | 'high_quality'
      - `generation` GenerationConfiguration — example { "model_id": "meta-llama/llama-3-1-70b-instruct", "prompt_instruction": "When the documents are in different languages, you should respond in english.", "max_docs_passed_to_llm": 5, "retrieval_confidence_threshold": "Lowest", "generated_response_length": "Moderate", "response_confidence_threshold": "Low", "display_text_no_results_found": "no docs found", "display_text_connectivity_issue": "conn failed", }
        - `model_id` string, nullable
        - `prompt_instruction` string
        - `max_docs_passed_to_llm` integer
        - `generated_response_length` 'Concise' | 'Moderate' | 'Verbose'
        - `display_text_no_results_found` string
        - `display_text_connectivity_issue` string
        - `idk_message` string
        - `enabled` boolean
      - `query_rewrite` QueryRewriteConfig — example { "enabled": True, "model_id": "meta-llama/llama-3-1-70b-instruct" }
        - `enabled` boolean
        - `model_id` string, nullable
      - `confidence_thresholds` ConfidenceThresholds
        - `retrieval_confidence_threshold` 'Off' | 'Lowest' | 'Low' | 'High' | 'Highest'
        - `response_confidence_threshold` 'Off' | 'Lowest' | 'Low' | 'High' | 'Highest'
      - `citations` CitationsConfig — example: { "citation_title": "how do i know", "citations_shown": 5, }
        - `citation_title` string
        - `citations_shown` integer
      - `hap_filtering` HAPFiltering — example { "output": { "enabled": True, "threshold": 0.7, } }
        - `output` HAPFilteringConfig
          - `enabled` boolean
          - `threshold` number
      - `query_source` 'SessionHistory' | 'Agent'
      - `agent_query_description` string
    - `connection_ids` string[] — List of connection IDs for direct agent-to-connection bindings
    - `additional_properties` AgentAdditionalProperties — A specification for settings within an agent. This schema is used for OUTPUT (reading from database). Database stores nested format: {"en": [...], "es": [...]} Using Dict[str, Any] preserves the nested language structure.
      - `icon` string, nullable — xml strings or encoded base64 image data
      - `starter_prompts` object, nullable — Agent Starter Prompts (nested by language)
      - `welcome_content` object, nullable — Agent Welcome Message (nested by language)
      - `context_settings` ContextSettings — Context management settings for an agent.
        - `context_compaction_enabled` boolean, nullable — Enable context compaction
        - `context_compaction_threshold` integer, nullable — Token threshold for context compaction
        - `compaction_sliding_window` integer, nullable — Sliding window size for compaction
        - `large_message_threshold` integer, nullable — Token threshold for large message handling
        - `large_message_chunk_size` integer, nullable — Chunk size for large message processing
        - `large_message_target_summary` integer, nullable — Target summary size for large messages
        - `large_message_detect_structured` boolean, nullable — Enable structured data detection
      - `realtime_agent_settings` RealtimeAgentSettings — Base model for realtime agent settings
        - `enabled` boolean, nullable — Whether the realtime agent is enabled
    - `context_access_enabled` boolean — Enable access to context variables for this agent
    - `context_variables` string[] — List of context variable names that this agent can access
    - `hide_reasoning` boolean — Enable/disable reasoning trace
    - `llm_config` ModelConfig
      - `decoding_method` string, nullable
      - `prompt` union
        - string
        - string[]
      - `max_tokens` integer, nullable
      - `max_completion_tokens` integer, nullable
      - `temperature` number, nullable
      - `top_p` number, nullable
      - `n` integer, nullable
      - `stream` boolean, nullable
      - `logprobs` integer, nullable
      - `top_logprobs` boolean, nullable
      - `echo` boolean, nullable
      - `stop` union
        - string
        - string[]
      - `presence_penalty` number, nullable
      - `frequency_penalty` number, nullable
      - `best_of` integer, nullable
      - `logit_bias` object, nullable
      - `user` string, nullable
      - `context` string, nullable
      - `examples` Examples[], nullable
        - `input` unknown, required
        - `output` unknown, required
      - `top_k` integer, nullable
      - `response_format` ResponseFormat
        - `type` string, required
        - `json_schema` unknown
      - `seed` integer, nullable
      - `store` boolean, nullable
      - `metadata` object, nullable
      - `modalities` string[], nullable
      - `audio` AudioConfig
        - `voice` string, required
        - `format` string, required
      - `service_tier` string, nullable
      - `prediction` Prediction
        - `type` string, required
        - `content` union, required
          - PredictionContent[]
            - `type` string, required
            - `text` string, required
          - string
      - `safety_settings` unknown
      - `anthropic_beta` string, nullable
      - `anthropic_version` string, nullable
      - `thinking` Thinking
        - `type` string, nullable
        - `budget_tokens` integer, required
      - `space_id` string, nullable
      - `project_id` string, nullable
      - `reasoning_effort` string, nullable
      - `parallel_tool_calls` boolean, nullable
      - `disable_parallel_tool_use` boolean, nullable
      - `disable_tool_validation` boolean, nullable
      - `verbosity` string, nullable
      - `thinking_level` string, nullable
    - `plugins` Plugins
      - `agent_pre_invoke` Plugin[], nullable — Plugins to the invoke before agent
        - `plugin_id` string — Plugins to the invoke before agent
      - `agent_post_invoke` Plugin[], nullable — Plugins to the invoke after agent
        - `plugin_id` string — Plugins to the invoke before agent
    - `sync_tool_flow_interactions` boolean — Enable/disable syncing user interactions from tool flow to the agent
    - `toolkits` union[] — List of toolkits available to the agent
      - union
        - string
        - object
    - `memory_enabled` boolean — Enable/disable agentic memory for this agent

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/ibm/apis/wxo-server-api.md) · [All operations](https://skmtc.net/ibm/apis/wxo-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ibm/wxo-server-api/versions/82c114c37196/schema)