> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List and retrieve agents SDK Reference

> SDK reference for List and retrieve agents in the Agents API, available in Node.js and Python.

## Agents

### List Agents

List all agents in the workspace with full configuration details. Supports pagination and sorts agents newest first.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY"),
) as orq:

    res = orq.agents.list(limit=10)

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.list(10);

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "limit": Optional[float],
    "starting_after": Optional[str],
    "ending_before": Optional[str],
    "type_": Optional[Literal["internal"]],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
// orq.agents.list(limit?, startingAfter?, endingBefore?, type?)
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "object": Literal["list"],
    "data": [{
        "id": str,
        "key": str,
        "display_name": Optional[str],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": Optional[str],
        "updated": Optional[str],
        "status": Literal["live", "draft", "pending", "published"],
        "version": Optional[str],
        "path": str,
        "memory_stores": List[str],  # optional
        "team_of_agents": [{  # optional
            "key": str,
            "role": Optional[str],
        }],
        "skills": List[str],  # optional
        "agent_plugins": [{  # optional
            "id": str,
            "version": str,
        }],
        "metrics": {  # optional
            "total_cost": Optional[float],
        },
        "variables": Dict[str, Any],  # optional
        "knowledge_bases": [{  # optional
            "knowledge_id": str,
        }],
        "source": Optional[Literal["internal", "external", "experiment"]],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "type": Optional[Literal["internal", "a2a"]],
        "role": str,
        "description": str,
        "system_prompt": Optional[str],
        "instructions": str,
        "settings": {  # optional
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "chat_exposed": Optional[bool],
            "tools": [{  # optional
                "id": str,
                "key": Optional[str],
                "action_type": str,
                "display_name": Optional[str],
                "description": Optional[str],
                "configuration": Dict[str, Any],  # optional
                "requires_approval": Optional[bool],
                "tool_id": Optional[str],
                "whole_server": Optional[bool],
                "conditions": [{  # optional
                    "condition": str,
                    "operator": str,
                    "value": str,
                }],
                "timeout": Optional[float],
            }],
            "evaluators": [{  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            }],
            "guardrails": [{  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            }],
        },
        "model": {
            "id": str,
            "integration_id": Optional[str],
            "parameters": {  # optional
                "name": Optional[str],
                "frequency_penalty": Optional[float],
                "max_tokens": Optional[int],
                "max_completion_tokens": Optional[int],
                "presence_penalty": Optional[float],
                "response_format": {  # optional
                    # one of: ListAgentsResponseFormatText, ListAgentsResponseFormatJSONObject, ListAgentsResponseFormatAgentsJSONSchema
                    "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
                    "json_schema": {
                        "description": Optional[str],
                        "name": str,
                        "schema_": Optional[Any],
                        "strict": Optional[bool],
                    },
                },
                "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
                "verbosity": Optional[str],
                "seed": Optional[float],
                "stop": Union[str, List[str]],  # optional
                "thinking": {  # optional
                    # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
                    "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],
                    "budget_tokens": Union[float, Optional[float]],
                    "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
                    "display": Optional[Literal["summarized", "omitted", "updates"]],
                },
                "temperature": Optional[float],
                "top_p": Optional[float],
                "top_k": Optional[float],
                "tool_choice": {  # optional
                    # one of: ListAgentsToolChoice1, ListAgentsToolChoice2
                    "type": Optional[Literal["function"]],
                    "function": {
                        "name": str,
                    },
                },
                "parallel_tool_calls": Optional[bool],
                "modalities": List[Literal["text", "audio"]],  # optional
                "guardrails": [{  # optional
                    "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
                    "execute_on": Literal["input", "output"],
                }],
                "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
                "fallback_on_codes": List[int],  # optional
                "fallbacks": [{  # optional
                    "model": str,
                }],
                "cache": {  # optional
                    "ttl": Optional[float],
                    "type": Literal["exact_match"],
                },
                "load_balancer": {  # optional
                    # one of: ListAgentsLoadBalancer1
                    "type": Literal["weight_based"],
                    "models": [{
                        "model": str,
                        "weight": Optional[float],
                    }],
                },
                "timeout": {  # optional
                    "call_timeout": float,
                },
                "cache_control": {  # optional
                    "type": Literal["ephemeral"],
                    "ttl": Optional[Literal["5m", "1h"]],
                },
                "prompt_cache_key": Optional[str],
            },
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],  # optional
            },
            "fallback_models": List[Union[str, ListAgentsFallbackModelConfiguration2]],  # optional
        },
    }],
    "has_more": bool,
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  object: "list";
  data: {
    id: string;
    key: string;
    displayName?: string;
    createdById?: string;
    updatedById?: string;
    created?: string;
    updated?: string;
    status: "live" | "draft" | "pending" | "published";
    version?: string;
    path: string;
    memoryStores?: string[];
    teamOfAgents?: {
      key: string;
      role?: string;
    }[];
    skills?: string[];
    agentPlugins?: {
      id: string;
      version: string;
    }[];
    metrics?: {
      totalCost?: number;
    };
    variables?: Record<string, any>;
    knowledgeBases?: {
      knowledgeId: string;
    }[];
    source?: "internal" | "external" | "experiment";
    engine?: "text" | "jinja" | "mustache";
    type?: "internal" | "a2a";
    role: string;
    description: string;
    systemPrompt?: string;
    instructions: string;
    settings?: {
      maxIterations?: number;
      maxExecutionTime?: number;
      maxCost?: number;
      toolApprovalRequired?: "all" | "respect_tool" | "none";
      chatExposed?: boolean;
      tools?: {
        id: string;
        key?: string;
        actionType: string;
        displayName?: string;
        description?: string;
        configuration?: Record<string, any>;
        requiresApproval?: boolean;
        toolId?: string;
        wholeServer?: boolean;
        conditions?: {
          condition: string;
          operator: string;
          value: string;
        }[];
        timeout?: number;
      }[];
      evaluators?: {
        id: string;
        sampleRate?: number;
        executeOn: "input" | "output";
      }[];
      guardrails?: {
        id: string;
        sampleRate?: number;
        executeOn: "input" | "output";
      }[];
    };
    model: {
      id: string;
      integrationId?: string;
      parameters?: {
        name?: string;
        frequencyPenalty?: number;
        maxTokens?: number;
        maxCompletionTokens?: number;
        presencePenalty?: number;
        responseFormat?: {
          // one of: ListAgentsResponseFormatText, ListAgentsResponseFormatJSONObject, ListAgentsResponseFormatAgentsJSONSchema
          type: "text" | "json_object" | "json_schema";
          jsonSchema: {
            description?: string;
            name: string;
            schema?: any;
            strict?: boolean;
          };
        };
        reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
        verbosity?: string;
        seed?: number;
        stop?: string | string[];
        thinking?: {
          // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
          type: "disabled" | "enabled" | "adaptive" | "between_tools";
          budgetTokens: number;
          thinkingLevel?: "minimal" | "low" | "medium" | "high";
          display?: "summarized" | "omitted" | "updates";
        };
        temperature?: number;
        topP?: number;
        topK?: number;
        toolChoice?: {
          // one of: ListAgentsToolChoice1, ListAgentsToolChoice2
          type?: "function";
          function: {
            name: string;
          };
        };
        parallelToolCalls?: boolean;
        modalities?: ("text" | "audio")[];
        guardrails?: {
          id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
          executeOn: "input" | "output";
        }[];
        plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
        fallbackOnCodes?: number[];
        fallbacks?: {
          model: string;
        }[];
        cache?: {
          ttl?: number;
          type: "exact_match";
        };
        loadBalancer?: {
          // one of: ListAgentsLoadBalancer1
          type: "weight_based";
          models: {
            model: string;
            weight?: number;
          }[];
        };
        timeout?: {
          callTimeout: number;
        };
        cacheControl?: {
          type: "ephemeral";
          ttl?: "5m" | "1h";
        };
        promptCacheKey?: string;
      };
      retry?: {
        count?: number;
        onCodes?: number[];
      };
      fallbackModels?: (string | ListAgentsFallbackModelConfiguration2)[];
    };
  }[];
  hasMore: boolean;
}
```

**Variant types**

#### ListAgentsFallbackModelConfiguration2

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "id": str,
    "parameters": {  # optional
        "name": Optional[str],
        "frequency_penalty": Optional[float],
        "max_tokens": Optional[int],
        "max_completion_tokens": Optional[int],
        "presence_penalty": Optional[float],
        "response_format": {  # optional
            # one of: ListAgentsResponseFormatAgentsText, ListAgentsResponseFormatAgentsJSONObject, ListAgentsResponseFormatAgentsResponse200JSONSchema
            "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
            "json_schema": {
                "description": Optional[str],
                "name": str,
                "schema_": Optional[Any],
                "strict": Optional[bool],
            },
        },
        "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
        "verbosity": Optional[str],
        "seed": Optional[float],
        "stop": Union[str, List[str]],  # optional
        "thinking": {  # optional
            # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
            "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],
            "budget_tokens": Union[float, Optional[float]],
            "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
            "display": Optional[Literal["summarized", "omitted", "updates"]],
        },
        "temperature": Optional[float],
        "top_p": Optional[float],
        "top_k": Optional[float],
        "tool_choice": {  # optional
            # one of: ListAgentsToolChoiceAgents1, ListAgentsToolChoiceAgents2
            "type": Optional[Literal["function"]],
            "function": {
                "name": str,
            },
        },
        "parallel_tool_calls": Optional[bool],
        "modalities": List[Literal["text", "audio"]],  # optional
        "guardrails": [{  # optional
            "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
            "execute_on": Literal["input", "output"],
        }],
        "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
        "fallback_on_codes": List[int],  # optional
        "fallbacks": [{  # optional
            "model": str,
        }],
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],
        },
        "load_balancer": {  # optional
            # one of: ListAgentsLoadBalancerAgents1
            "type": Literal["weight_based"],
            "models": [{
                "model": str,
                "weight": Optional[float],
            }],
        },
        "timeout": {  # optional
            "call_timeout": float,
        },
        "cache_control": {  # optional
            "type": Literal["ephemeral"],
            "ttl": Optional[Literal["5m", "1h"]],
        },
        "prompt_cache_key": Optional[str],
    },
    "retry": {  # optional
        "count": Optional[float],
        "on_codes": List[float],  # optional
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  parameters?: {
    name?: string;
    frequencyPenalty?: number;
    maxTokens?: number;
    maxCompletionTokens?: number;
    presencePenalty?: number;
    responseFormat?: {
      // one of: ListAgentsResponseFormatAgentsText, ListAgentsResponseFormatAgentsJSONObject, ListAgentsResponseFormatAgentsResponse200JSONSchema
      type: "text" | "json_object" | "json_schema";
      jsonSchema: {
        description?: string;
        name: string;
        schema?: any;
        strict?: boolean;
      };
    };
    reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    verbosity?: string;
    seed?: number;
    stop?: string | string[];
    thinking?: {
      // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
      type: "disabled" | "enabled" | "adaptive" | "between_tools";
      budgetTokens: number;
      thinkingLevel?: "minimal" | "low" | "medium" | "high";
      display?: "summarized" | "omitted" | "updates";
    };
    temperature?: number;
    topP?: number;
    topK?: number;
    toolChoice?: {
      // one of: ListAgentsToolChoiceAgents1, ListAgentsToolChoiceAgents2
      type?: "function";
      function: {
        name: string;
      };
    };
    parallelToolCalls?: boolean;
    modalities?: ("text" | "audio")[];
    guardrails?: {
      id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
      executeOn: "input" | "output";
    }[];
    plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
    fallbackOnCodes?: number[];
    fallbacks?: {
      model: string;
    }[];
    cache?: {
      ttl?: number;
      type: "exact_match";
    };
    loadBalancer?: {
      // one of: ListAgentsLoadBalancerAgents1
      type: "weight_based";
      models: {
        model: string;
        weight?: number;
      }[];
    };
    timeout?: {
      callTimeout: number;
    };
    cacheControl?: {
      type: "ephemeral";
      ttl?: "5m" | "1h";
    };
    promptCacheKey?: string;
  };
  retry?: {
    count?: number;
    onCodes?: number[];
  };
}
```

### Retrieve an Agent

Retrieve the complete agent manifest by key, including model assignments, tools, knowledge bases, memory stores, and execution parameters.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY"),
) as orq:

    res = orq.agents.retrieve(agent_key="<value>")

    # Handle response
    print(res)

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.retrieve("<value>");

  console.log(result);
}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
// orq.agents.retrieve(agentKey)
```

**Response**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "id": str,
    "key": str,
    "display_name": Optional[str],
    "project_id": str,
    "created_by_id": Optional[str],
    "updated_by_id": Optional[str],
    "created": Optional[str],
    "updated": Optional[str],
    "status": Literal["live", "draft", "pending", "published"],
    "version": Optional[str],
    "path": str,
    "memory_stores": List[str],  # optional
    "team_of_agents": [{  # optional
        "key": str,
        "role": Optional[str],
    }],
    "skills": List[str],  # optional
    "agent_plugins": [{  # optional
        "id": str,
        "version": str,
    }],
    "metrics": {  # optional
        "total_cost": Optional[float],
    },
    "variables": Dict[str, Any],  # optional
    "knowledge_bases": [{  # optional
        "knowledge_id": str,
    }],
    "source": Optional[Literal["internal", "external", "experiment"]],
    "engine": Optional[Literal["text", "jinja", "mustache"]],
    "type": Optional[Literal["internal", "a2a"]],
    "role": str,
    "description": str,
    "system_prompt": Optional[str],
    "instructions": str,
    "settings": {  # optional
        "max_iterations": Optional[int],
        "max_execution_time": Optional[int],
        "max_cost": Optional[float],
        "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
        "chat_exposed": Optional[bool],
        "tools": [{  # optional
            "id": str,
            "key": Optional[str],
            "action_type": str,
            "display_name": Optional[str],
            "description": Optional[str],
            "configuration": Dict[str, Any],  # optional
            "requires_approval": Optional[bool],
            "tool_id": Optional[str],
            "whole_server": Optional[bool],
            "conditions": [{  # optional
                "condition": str,
                "operator": str,
                "value": str,
            }],
            "timeout": Optional[float],
        }],
        "evaluators": [{  # optional
            "id": str,
            "sample_rate": Optional[float],
            "execute_on": Literal["input", "output"],
        }],
        "guardrails": [{  # optional
            "id": str,
            "sample_rate": Optional[float],
            "execute_on": Literal["input", "output"],
        }],
    },
    "model": {
        "id": str,
        "integration_id": Optional[str],
        "parameters": {  # optional
            "name": Optional[str],
            "frequency_penalty": Optional[float],
            "max_tokens": Optional[int],
            "max_completion_tokens": Optional[int],
            "presence_penalty": Optional[float],
            "response_format": {  # optional
                # one of: RetrieveAgentRequestResponseFormatText, RetrieveAgentRequestResponseFormatJSONObject, RetrieveAgentRequestResponseFormatAgentsJSONSchema
                "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
                "json_schema": {
                    "description": Optional[str],
                    "name": str,
                    "schema_": Optional[Any],
                    "strict": Optional[bool],
                },
            },
            "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
            "verbosity": Optional[str],
            "seed": Optional[float],
            "stop": Union[str, List[str]],  # optional
            "thinking": {  # optional
                # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
                "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],
                "budget_tokens": Union[float, Optional[float]],
                "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
                "display": Optional[Literal["summarized", "omitted", "updates"]],
            },
            "temperature": Optional[float],
            "top_p": Optional[float],
            "top_k": Optional[float],
            "tool_choice": {  # optional
                # one of: RetrieveAgentRequestToolChoice1, RetrieveAgentRequestToolChoice2
                "type": Optional[Literal["function"]],
                "function": {
                    "name": str,
                },
            },
            "parallel_tool_calls": Optional[bool],
            "modalities": List[Literal["text", "audio"]],  # optional
            "guardrails": [{  # optional
                "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
                "execute_on": Literal["input", "output"],
            }],
            "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
            "fallback_on_codes": List[int],  # optional
            "fallbacks": [{  # optional
                "model": str,
            }],
            "cache": {  # optional
                "ttl": Optional[float],
                "type": Literal["exact_match"],
            },
            "load_balancer": {  # optional
                # one of: RetrieveAgentRequestLoadBalancer1
                "type": Literal["weight_based"],
                "models": [{
                    "model": str,
                    "weight": Optional[float],
                }],
            },
            "timeout": {  # optional
                "call_timeout": float,
            },
            "cache_control": {  # optional
                "type": Literal["ephemeral"],
                "ttl": Optional[Literal["5m", "1h"]],
            },
            "prompt_cache_key": Optional[str],
        },
        "retry": {  # optional
            "count": Optional[float],
            "on_codes": List[float],  # optional
        },
        "fallback_models": List[Union[str, RetrieveAgentRequestFallbackModelConfiguration2]],  # optional
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  key: string;
  displayName?: string;
  projectId: string;
  createdById?: string;
  updatedById?: string;
  created?: string;
  updated?: string;
  status: "live" | "draft" | "pending" | "published";
  version?: string;
  path: string;
  memoryStores?: string[];
  teamOfAgents?: {
    key: string;
    role?: string;
  }[];
  skills?: string[];
  agentPlugins?: {
    id: string;
    version: string;
  }[];
  metrics?: {
    totalCost?: number;
  };
  variables?: Record<string, any>;
  knowledgeBases?: {
    knowledgeId: string;
  }[];
  source?: "internal" | "external" | "experiment";
  engine?: "text" | "jinja" | "mustache";
  type?: "internal" | "a2a";
  role: string;
  description: string;
  systemPrompt?: string;
  instructions: string;
  settings?: {
    maxIterations?: number;
    maxExecutionTime?: number;
    maxCost?: number;
    toolApprovalRequired?: "all" | "respect_tool" | "none";
    chatExposed?: boolean;
    tools?: {
      id: string;
      key?: string;
      actionType: string;
      displayName?: string;
      description?: string;
      configuration?: Record<string, any>;
      requiresApproval?: boolean;
      toolId?: string;
      wholeServer?: boolean;
      conditions?: {
        condition: string;
        operator: string;
        value: string;
      }[];
      timeout?: number;
    }[];
    evaluators?: {
      id: string;
      sampleRate?: number;
      executeOn: "input" | "output";
    }[];
    guardrails?: {
      id: string;
      sampleRate?: number;
      executeOn: "input" | "output";
    }[];
  };
  model: {
    id: string;
    integrationId?: string;
    parameters?: {
      name?: string;
      frequencyPenalty?: number;
      maxTokens?: number;
      maxCompletionTokens?: number;
      presencePenalty?: number;
      responseFormat?: {
        // one of: RetrieveAgentRequestResponseFormatText, RetrieveAgentRequestResponseFormatJSONObject, RetrieveAgentRequestResponseFormatAgentsJSONSchema
        type: "text" | "json_object" | "json_schema";
        jsonSchema: {
          description?: string;
          name: string;
          schema?: any;
          strict?: boolean;
        };
      };
      reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      verbosity?: string;
      seed?: number;
      stop?: string | string[];
      thinking?: {
        // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
        type: "disabled" | "enabled" | "adaptive" | "between_tools";
        budgetTokens: number;
        thinkingLevel?: "minimal" | "low" | "medium" | "high";
        display?: "summarized" | "omitted" | "updates";
      };
      temperature?: number;
      topP?: number;
      topK?: number;
      toolChoice?: {
        // one of: RetrieveAgentRequestToolChoice1, RetrieveAgentRequestToolChoice2
        type?: "function";
        function: {
          name: string;
        };
      };
      parallelToolCalls?: boolean;
      modalities?: ("text" | "audio")[];
      guardrails?: {
        id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
        executeOn: "input" | "output";
      }[];
      plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
      fallbackOnCodes?: number[];
      fallbacks?: {
        model: string;
      }[];
      cache?: {
        ttl?: number;
        type: "exact_match";
      };
      loadBalancer?: {
        // one of: RetrieveAgentRequestLoadBalancer1
        type: "weight_based";
        models: {
          model: string;
          weight?: number;
        }[];
      };
      timeout?: {
        callTimeout: number;
      };
      cacheControl?: {
        type: "ephemeral";
        ttl?: "5m" | "1h";
      };
      promptCacheKey?: string;
    };
    retry?: {
      count?: number;
      onCodes?: number[];
    };
    fallbackModels?: (string | RetrieveAgentRequestFallbackModelConfiguration2)[];
  };
}
```

**Variant types**

#### RetrieveAgentRequestFallbackModelConfiguration2

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "id": str,
    "parameters": {  # optional
        "name": Optional[str],
        "frequency_penalty": Optional[float],
        "max_tokens": Optional[int],
        "max_completion_tokens": Optional[int],
        "presence_penalty": Optional[float],
        "response_format": {  # optional
            # one of: RetrieveAgentRequestResponseFormatAgentsText, RetrieveAgentRequestResponseFormatAgentsJSONObject, RetrieveAgentRequestResponseFormatAgentsResponse200JSONSchema
            "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
            "json_schema": {
                "description": Optional[str],
                "name": str,
                "schema_": Optional[Any],
                "strict": Optional[bool],
            },
        },
        "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
        "verbosity": Optional[str],
        "seed": Optional[float],
        "stop": Union[str, List[str]],  # optional
        "thinking": {  # optional
            # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
            "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],
            "budget_tokens": Union[float, Optional[float]],
            "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
            "display": Optional[Literal["summarized", "omitted", "updates"]],
        },
        "temperature": Optional[float],
        "top_p": Optional[float],
        "top_k": Optional[float],
        "tool_choice": {  # optional
            # one of: RetrieveAgentRequestToolChoiceAgents1, RetrieveAgentRequestToolChoiceAgents2
            "type": Optional[Literal["function"]],
            "function": {
                "name": str,
            },
        },
        "parallel_tool_calls": Optional[bool],
        "modalities": List[Literal["text", "audio"]],  # optional
        "guardrails": [{  # optional
            "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
            "execute_on": Literal["input", "output"],
        }],
        "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
        "fallback_on_codes": List[int],  # optional
        "fallbacks": [{  # optional
            "model": str,
        }],
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],
        },
        "load_balancer": {  # optional
            # one of: RetrieveAgentRequestLoadBalancerAgents1
            "type": Literal["weight_based"],
            "models": [{
                "model": str,
                "weight": Optional[float],
            }],
        },
        "timeout": {  # optional
            "call_timeout": float,
        },
        "cache_control": {  # optional
            "type": Literal["ephemeral"],
            "ttl": Optional[Literal["5m", "1h"]],
        },
        "prompt_cache_key": Optional[str],
    },
    "retry": {  # optional
        "count": Optional[float],
        "on_codes": List[float],  # optional
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  parameters?: {
    name?: string;
    frequencyPenalty?: number;
    maxTokens?: number;
    maxCompletionTokens?: number;
    presencePenalty?: number;
    responseFormat?: {
      // one of: RetrieveAgentRequestResponseFormatAgentsText, RetrieveAgentRequestResponseFormatAgentsJSONObject, RetrieveAgentRequestResponseFormatAgentsResponse200JSONSchema
      type: "text" | "json_object" | "json_schema";
      jsonSchema: {
        description?: string;
        name: string;
        schema?: any;
        strict?: boolean;
      };
    };
    reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    verbosity?: string;
    seed?: number;
    stop?: string | string[];
    thinking?: {
      // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
      type: "disabled" | "enabled" | "adaptive" | "between_tools";
      budgetTokens: number;
      thinkingLevel?: "minimal" | "low" | "medium" | "high";
      display?: "summarized" | "omitted" | "updates";
    };
    temperature?: number;
    topP?: number;
    topK?: number;
    toolChoice?: {
      // one of: RetrieveAgentRequestToolChoiceAgents1, RetrieveAgentRequestToolChoiceAgents2
      type?: "function";
      function: {
        name: string;
      };
    };
    parallelToolCalls?: boolean;
    modalities?: ("text" | "audio")[];
    guardrails?: {
      id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
      executeOn: "input" | "output";
    }[];
    plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
    fallbackOnCodes?: number[];
    fallbacks?: {
      model: string;
    }[];
    cache?: {
      ttl?: number;
      type: "exact_match";
    };
    loadBalancer?: {
      // one of: RetrieveAgentRequestLoadBalancerAgents1
      type: "weight_based";
      models: {
        model: string;
        weight?: number;
      }[];
    };
    timeout?: {
      callTimeout: number;
    };
    cacheControl?: {
      type: "ephemeral";
      ttl?: "5m" | "1h";
    };
    promptCacheKey?: string;
  };
  retry?: {
    count?: number;
    onCodes?: number[];
  };
}
```

### Delete an Agent

Permanently remove an agent and all associated configuration from the workspace. Terminate active sessions and the key becomes reusable.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY"),
) as orq:

    orq.agents.delete(agent_key="<value>")

```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  await orq.agents.delete("<value>");

}

run();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "agent_key": str,  # required
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
// orq.agents.delete(agentKey)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.