List agents

List your custom agents and the pre-built h/ agents.

GET /api/v2/agents

Python

from hai_agents import Client

client = Client()

agents = client.agents.list_agents()
print(agents.items)

200

{
  "items": [
    {
      "name": "h/web-surfer-flash",
      "description": "Visual web agent for interactive or visually rendered pages.",
      "environments": ["h/browser"],
      "model": "holo4-35b-a3b",
      "reasoning_effort": null,
      "instructions": null,
      "subagents": null,
      "skills": ["h/company", "h/user-collaboration", "h/answering", "h/planning"],
      "answer_format": null,
      "tools": null
    },
    {
      "name": "price-checker",
      "description": "Compares product prices across e-commerce sites.",
      "environments": ["h/browser"],
      "model": null,
      "reasoning_effort": null,
      "instructions": null,
      "subagents": null,
      "skills": null,
      "answer_format": null,
      "tools": null
    }
  ],
  "page": 1,
  "total": 8
}

Query parameters

agent_name · string

Case-insensitive substring match on the agent name.

search · string

Case-insensitive match on the agent name or description.

reserved · boolean

true: only H’s reserved h/ agents. false: only your organization’s agents. Omit for both.

include · string

revision: each item also carries revision, the agent’s current revision number. The SDKs still type items as agents, so revision is an untyped extra field: agent.revision in Python, (agent as any).revision in TypeScript.

page · integer · default: "1"

Page number (1-based).

size · integer · default: "10"

Items per page. Maximum: 1000.

sort · string · default: "-created_at"

Sort order. Options: created_at, -created_at, agent_name, -agent_name.

Response

200 with a page envelope whose items are agent objects.

Python

from hai_agents import Client

client = Client()

agents = client.agents.list_agents()
print(agents.items)

200

{
  "items": [
    {
      "name": "h/web-surfer-flash",
      "description": "Visual web agent for interactive or visually rendered pages.",
      "environments": ["h/browser"],
      "model": "holo4-35b-a3b",
      "reasoning_effort": null,
      "instructions": null,
      "subagents": null,
      "skills": ["h/company", "h/user-collaboration", "h/answering", "h/planning"],
      "answer_format": null,
      "tools": null
    },
    {
      "name": "price-checker",
      "description": "Compares product prices across e-commerce sites.",
      "environments": ["h/browser"],
      "model": null,
      "reasoning_effort": null,
      "instructions": null,
      "subagents": null,
      "skills": null,
      "answer_format": null,
      "tools": null
    }
  ],
  "page": 1,
  "total": 8
}

List only your organization’s agents

Python

agents = client.agents.list_agents(reserved=False)