---
title: "Get all agents (built-in and custom)"
method: GET
path: "/agents"
tags: ["Agents"]
---

# Get all agents (built-in and custom)

`GET /agents`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/agents`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/agents/get.ts> (a function with typed inputs; its response is checked against the schema)

Get all agents (both built-in and custom agents) with unified structure

## Response `200`

Successful operation

- Agent[]
  - `id` string: Agent ID (UUID for custom agents, string like "general-agent" for built-in)
  - `value` string: Agent identifier (agent_type for built-in, agent_name for custom)
  - `label` string: Display name for the agent
  - `enabled` boolean: Whether the agent is enabled (true if all required keys are associated)
  - `type` 'built_in' | 'langgraph' | 'crewai' | 'openai' | 'claude': Agent type
  - `owner` string, nullable: Owner email (null for built-in agents)
  - `description` string: Agent description
  - `api_keys` object: Key associations grouped by requirement type
    - `optional` AgentKeyAssociation[]: Optional key associations (with or without defaults)
      - `name` string: Environment variable name (env_key_name)
      - `associated_key` object, nullable: Associated agent key details if key is assigned
        - `id` string, uuid: Agent key ID
        - `name` string: Agent key name
        - `owner_email` string: Agent key owner email
        - `description` string: Agent key description
    - `required` AgentKeyAssociation[]: Required key associations
      - `name` string: Environment variable name (env_key_name)
      - `associated_key` object, nullable: Associated agent key details if key is assigned
        - `id` string, uuid: Agent key ID
        - `name` string: Agent key name
        - `owner_email` string: Agent key owner email
        - `description` string: Agent key description
    - `custom` AgentKeyAssociation[]: Custom key associations (added after agent creation)
      - `name` string: Environment variable name (env_key_name)
      - `associated_key` object, nullable: Associated agent key details if key is assigned
        - `id` string, uuid: Agent key ID
        - `name` string: Agent key name
        - `owner_email` string: Agent key owner email
        - `description` string: Agent key description
  - `mcp_servers` object[]: MCP server associations (only for custom agents)
    - `tool_name` string: MCP server name from agent metadata
    - `tool_args` string: Tool arguments as JSON string
    - `associated_tool` object, nullable: Associated tool details if tool is resolved
      - `id` string: Tool ID
      - `name` string: Tool name
      - `owner_email` string: Tool owner email
      - `description` string: Tool description

## Other responses

- `400`: Bad request
- `401`: Unauthorized - Invalid or missing API key
- `500`: Internal server error
- `default`: Unexpected error

---

[API](https://skmtc.dev/h2o/apis/h2ogpte-rest-api.md) - [All operations](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/revisions/a82a117320f4?raw)