Retrieve an agent

Retrieve one agent’s full spec by name, including pre-built h/ agents.

GET /api/v2/agents/{agent_name}

Python

from hai_agents import Client

client = Client()

agent = client.agents.get_agent(agent_name="h/web-surfer-flash")
print(agent.description, agent.skills)

200

{
  "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
}

Path parameters

agent_name · string · required

The agent’s name, for example h/web-surfer-flash or my-custom-bot.

Query parameters

revision · integer

Read this revision instead of the latest. List them with List revisions.

resolve · boolean · default: "false"

When true, string references in environments, skills, and subagents are expanded into their full specs. When false, they are returned as stored.

Response

200 with the agent object, also returned by create, list, update, and patch. Field constraints are on Create an agent.

The ETag response header holds the revision you read, for example "3". Send it back as If-Match to update only if nobody changed the agent since. A resolve=true read has no ETag, since it also reflects the environments, skills, and subagents it expands.

name · string

Catalog identifier. h/ names are H’s reserved, read-only agents.

description · string

What the agent does.

environments · array

Catalog ID strings or inline environment specs.

model · string | null

Holo model ID. null uses the default, holo4-27b.

reasoning_effort · string | null

disabled, low, medium, or xhigh. null uses medium on Holo4 models and the model’s default thinking on Holo3 and Holo3.1.

instructions · string | null

Steering text appended to the system prompt.

subagents · array | null

Agents this one can delegate to: catalog names or inline agent specs.

skills · array | null

Catalog skill names or inline skill specs.

answer_format · object | null

JSON Schema of the final answer. null returns free-form text.

tools · object[] | null

Custom tools executed by your code.

Python

from hai_agents import Client

client = Client()

agent = client.agents.get_agent(agent_name="h/web-surfer-flash")
print(agent.description, agent.skills)

200

{
  "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
}

Errors

Status	Cause
400	The path carries a name:N pin. Read a revision with ?revision=N instead.
404	Not found, or not in your organization. Also sent for an unknown revision.
410	The revision’s stored spec fails current validation.