--- title: "List agents" method: GET path: "/v2/agents" tags: ["Agents"] --- # List agents `GET /v2/agents` Retrieves a comprehensive list of agents configured in your workspace. Supports pagination for large datasets and returns agents sorted by creation date (newest first). Each agent in the response includes its complete configuration: model settings with fallback options, instructions, tools, knowledge bases, memory stores, and execution parameters. Use pagination parameters to efficiently navigate through large collections of agents. ## Query parameters - `limit` number — A limit on the number of objects to be returned. Limit can range between 1 and 200. When not provided, returns all agents without pagination. - `starting_after` string — A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `after=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the next page of the list. - `ending_before` string — A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `before=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the previous page of the list. - `type` 'internal' — Filter agents by type ## Response `200` Successfully retrieved the list of agents. Returns a paginated response containing agent manifests with complete configurations, including primary and fallback models, tools, knowledge bases, and execution settings. - object - `object` 'list', required - `data` object[], required - `_id` string, required - `key` string, required — Unique identifier for the agent within the workspace - `display_name` string - `created_by_id` string, nullable - `updated_by_id` string, nullable - `created` string - `updated` string - `status` 'live' | 'draft' | 'pending' | 'published', required — The status of the agent. `Live` is the latest version of the agent. `Draft` is a version that is not yet published. `Pending` is a version that is pending approval. `Published` is a version that was live and has been replaced by a new version. - `version` string — Current semantic version of the agent manifest. - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project. - `memory_stores` string[] — Array of memory store identifiers. Accepts both memory store IDs and keys. - `team_of_agents` object[] — The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks. - `key` string, required — The unique key of the agent within the workspace - `role` string — The role of the agent in this context. This is used to give extra information to the leader to help it decide which agent to hand off to. - `skills` string[] — List of skills that the agent can utilize. This field allows you to specify which skills the agent has access to, enabling more complex and dynamic behavior. - `metrics` object - `total_cost` number - `variables` object — Extracted variables from agent instructions - `knowledge_bases` object[] — Agent knowledge bases reference - `knowledge_id` string, required — Unique identifier of the knowledge base to search - `source` 'internal' | 'external' | 'experiment' - `engine` 'text' | 'jinja' | 'mustache' - `type` 'internal' | 'a2a' — Agent type: internal (Orquesta-managed) or a2a (external A2A-compliant) - `role` string, required - `description` string, required - `system_prompt` string, nullable - `instructions` string, required - `settings` object - `max_iterations` integer — Maximum iterations(llm calls) before the agent will stop executing. - `max_execution_time` integer — Maximum time (in seconds) for the agent thinking process. This does not include the time for tool calls and sub agent calls. It will be loosely enforced, the in progress LLM calls will not be terminated and the last assistant message will be returned. - `max_cost` number — Maximum cost in USD for the agent execution. When the accumulated cost exceeds this limit, the agent will stop executing. Set to 0 for unlimited. Only supported in v3 responses - `tool_approval_required` 'all' | 'respect_tool' | 'none' — If all, the agent will require approval for all tools. If respect_tool, the agent will require approval for tools that have the requires_approval flag set to true. If none, the agent will not require approval for any tools. - `chat_exposed` boolean — When enabled, this agent is exposed as a selectable target in AI Chat for users to consume. - `tools` object[] - `id` string, ulid, required — The id of the resource - `key` string — Optional tool key for custom tools - `action_type` string, required - `display_name` string - `description` string — Optional tool description - `configuration` object — Static tool configuration set at design time. Merged over LLM-provided arguments at execution time. - `requires_approval` boolean - `tool_id` string — Nested tool ID for MCP tools (identifies specific tool within MCP server) - `conditions` object[] - `condition` string, required — The argument of the tool call to evaluate - `operator` string, required — The operator to use - `value` string, required — The value to compare against - `timeout` number — Tool execution timeout in seconds for this agent (max: 10 minutes). Overrides the timeout configured on the tool definition. - `evaluators` object[] — Configuration for an evaluator applied to the agent - `id` string, required — Unique key or identifier of the evaluator - `sample_rate` number — The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions. - `execute_on` 'input' | 'output', required — Determines whether the evaluator runs on the agent input (user message) or output (agent response). - `guardrails` object[] — Configuration for a guardrail applied to the agent - `id` string, required — Unique key or identifier of the evaluator - `sample_rate` number — The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions. - `execute_on` 'input' | 'output', required — Determines whether the evaluator runs on the agent input (user message) or output (agent response). - `model` object, required - `id` string, required — The database ID of the primary model - `integration_id` string, nullable — Optional integration ID for custom model configurations - `parameters` object, nullable — Model behavior parameters (snake_case) stored as part of the agent configuration. These become the default parameters used when the agent is executed. Commonly used: temperature (0-1, controls randomness), max_completion_tokens (response length), top_p (nucleus sampling). Advanced: frequency_penalty, presence_penalty, response_format (JSON/structured output), reasoning_effort (for o1/thinking models), seed (reproducibility), stop sequences. Model-specific support varies. Runtime parameters in agent execution requests can override these defaults. - `name` string — The name to display on the trace. If not specified, the default system name will be used. - `frequency_penalty` number, nullable — Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `max_tokens` integer, nullable — `[Deprecated]`. The maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. This value is now `deprecated` in favor of `max_completion_tokens`, and is not compatible with o1 series models. - `max_completion_tokens` integer, nullable — An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens - `presence_penalty` number, nullable — Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `response_format` union — An object specifying the format that the model must output - object — Default response format. Used to generate text responses - `type` 'text', required - object — JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required - object — JSON Schema response format. Used to generate structured JSON responses - `type` 'json_schema', required - `json_schema` object, required - … - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' — Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is currently only supported for `gpt-5.1-codex-max`. Any of "none", "minimal", "low", "medium", "high", "xhigh". - `verbosity` string — Adjusts response verbosity. Lower levels yield shorter answers. - `seed` number, nullable — If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. - `stop` union — Up to 4 sequences where the API will stop generating further tokens. - string - string[] - `thinking` union - ThinkingConfigDisabledSchema — Disables the thinking mode capability - `type` 'disabled', required — Disables the thinking mode capability - ThinkingConfigEnabledSchema — Enables the thinking mode capability - `type` 'enabled', required — Enables or disables the thinking mode capability - `budget_tokens` number, required — Determines how many tokens the model can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality. Must be ≥1024 and less than `max_tokens`. - `thinking_level` 'minimal' | 'low' | 'medium' | 'high' — The level of reasoning the model should use. This setting is supported only by `gemini-3` models. If budget_tokens is specified and `thinking_level` is available, `budget_tokens` will be ignored. - ThinkingConfigAdaptiveSchema — Enables adaptive thinking mode where the model dynamically determines thinking depth - `type` 'adaptive', required — Lets the model dynamically determine when and how much to use extended thinking based on the complexity of each request. Supported on Claude Opus 4.6 and Sonnet 4.6. - `temperature` number, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. - `top_k` number, nullable — Limits the model to consider only the top k most likely tokens at each step. - `tool_choice` union — Controls which (if any) tool is called by the model. - 'none' | 'auto' | 'required' - object - `type` 'function' — The type of the tool. Currently, only function is supported. - `function` object, required - … - `parallel_tool_calls` boolean — Whether to enable parallel function calling during tool use. - `modalities` string[], nullable — Output types that you would like the model to generate. Most models are capable of generating text, which is the default: ["text"]. The gpt-4o-audio-preview model can also be used to generate audio. To request that this model generate both text and audio responses, you can use: ["text", "audio"]. - `guardrails` object[] — A list of guardrails to apply to the request. - `id` union, required - 'orq_pii_detection' | 'orq_secret_detection' | 'orq_sexual_moderation' | 'orq_harmful_moderation' — The key of the guardrail. - string — Unique key or identifier of the evaluator - `execute_on` 'input' | 'output', required — Determines whether the guardrail runs on the input (user message) or output (model response). - `plugins` union[] — Request-scoped transforms applied to the text exchanged with the model. Supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response, and `response_healing`, which repairs malformed JSON in non-streaming output. - union - PIIRedactionPluginAuto - … - PIIRedactionPluginEn - … - PIIRedactionPluginNl - … - ResponseHealingPlugin - … - `fallbacks` object[] — Array of fallback models to use if primary model fails - `model` string, required — Fallback model identifier - `cache` object — Cache configuration for the request. - `ttl` number — Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). - `type` 'exact_match', required - `load_balancer` object — Load balancer configuration for the request. - `type` 'weight_based', required - `models` object[], required - `model` string, required — Model identifier for load balancing - `weight` number — Weight assigned to this model for load balancing - `timeout` object — Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. - `call_timeout` number, required — Timeout value in milliseconds - `cache_control` object — Provider-level prompt caching configuration applied to the request. Creates a cache control breakpoint covering the request content. Only supported by `Anthropic` Claude models. - `type` 'ephemeral', required — Create a cache control breakpoint at this content block. Accepts only the value "ephemeral". - `ttl` '5m' | '1h' — The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by `Anthropic` Claude models. - `prompt_cache_key` string — Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the legacy `user` field for prompt caching. - `retry` object — Retry configuration for model requests. Allows customizing retry count (1-5) and HTTP status codes that trigger retries. Default codes: [429]. Common codes: 500 (internal error), 429 (rate limit), 502/503/504 (gateway errors). - `count` number — Number of retry attempts (1-5) - `on_codes` number[] — HTTP status codes that trigger retry logic - `fallback_models` union[], nullable — Optional array of fallback models (string IDs or config objects) that will be used automatically in order if the primary model fails - union — Fallback model for automatic failover when primary model request fails. Supports optional parameter overrides. Can be a simple model ID string or a configuration object with model-specific parameters. Fallbacks are tried in order. - string — A fallback model ID string (e.g., `openai/gpt-4o-mini`). Will be used if the primary model request fails. Must support tool calling. - object — Fallback model configuration with optional parameters and retry settings. - `id` string, required — A fallback model ID string. Must support tool calling. - `parameters` object — Optional model parameters specific to this fallback model. Overrides primary model parameters if this fallback is used. - … - `retry` object — Retry configuration for this fallback model. Allows customizing retry count (1-5) and HTTP status codes that trigger retries. - … - `has_more` boolean, required --- [API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/6a22c53a2580/schema)