读取 Agent (Agents)
你的后端可以读取工作区里有哪些 Agent，以及每个 Agent 的名称、简介和头像——用来渲染 Agent 列表、在客户端展示最新的名字和 logo。 这两个接口只读，数据在请求时实时读取。
import { OpenhexClient } from '@openhex-ai/agent-sdk';
const ws = new OpenhexClient({ apiKey: process.env.OPENHEX_WORKSPACE_KEY! })
.workspace(process.env.OPENHEX_WORKSPACE_SLUG!);
列出 Agent
const { scope, workspace_id, agents } = await ws.listAgents();
// scope === 'workspace'
读取单个 Agent
const { agent } = await ws.getAgent('你的-agent-id');
// → { id, name, description, avatar, is_public, created_at, updated_at }
id 不属于这个工作区时返回 404 Agent not found in this workspace，而不是返回别的工作区的 Agent。
返回字段
| 字段 | 说明 |
|---|---|
id | Agent id |
name | 名称 |
description | 简介，可能为 null |
avatar | 头像的签名 URL，可能为 null |
is_public | 是否公开 |
created_at / updated_at | 创建 / 最近修改时间（ISO-8601 字符串） |
两个接口的响应都带 scope: "workspace" 和 workspace_id，可以直接断言，不必猜测数据来自哪里。列表单次最多返回 500 个 Agent。
后端调用，还是客户端调用？
listAgents / getAgent 是后端接口：接受工作区 API Key 或工作区所有者的登录态。成员的会话令牌调用会得到 403 not the owner of this workspace。
客户端（网页、小程序、App）手里只有会话令牌，要读取单个 Agent 的信息，用 REST 接口：
const res = await fetch(`https://api.openhex.tech/api/v2/marketplace/agents/${agentId}`, {
headers: { Authorization: `Bearer ${sessionToken}` },
});
const agent = await res.json(); // { id, name, description, is_public, created_at, updated_at, … }
三个真实集成里踩过的坑：
- 不要请求
/marketplace/agents（列表）再取第一个。 不带 id 时它返回的是公开市场；新开通的成员名下没有任何 Agent，第一条是平台自己的助手，不是你的 Agent。每次都返回200，看起来一切正常。一定要用带 id 的单个 Agent 接口。 - 不要让客户端调
/workspaces/{slug}/agents。 那是后端接口，会话令牌会被拒绝。 - 用
updated_at判断是否有变化，不要比较头像 URL。 同一张图片的签名 URL 刻意保持稳定，方便客户端缓存；换了新头像才会得到新 URL。
平台不会主动推送 Agent 信息的变化。需要让改名或新 logo 出现在客户端，就在进入页面时重新读取、比较 updated_at。