---
title: "Get A Registered Agent By Id."
method: GET
path: "/v1/orchestrate/agents/{id}"
tags: ["Agents"]
---

# Get A Registered Agent By Id.

`GET /v1/orchestrate/agents/{id}`

Retrieves details of a specific agent by its id.

## Path parameters

- `id` string, required

## Response `200`

Successful Response

- ListAgent — Schema for fetching agent.
  - `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)

## 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)