@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/GUIDE.md +975 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +84 -0
- package/MIGRATION.zh.md +70 -0
- package/PROVIDERS.md +273 -0
- package/PROVIDERS.zh.md +234 -0
- package/README.md +334 -2
- package/dist/AgentClient.d.ts +312 -0
- package/dist/AgentClient.d.ts.map +1 -0
- package/dist/AgentClient.js +715 -0
- package/dist/AgentClient.js.map +1 -0
- package/dist/AgenticID.d.ts +823 -0
- package/dist/AgenticID.d.ts.map +1 -0
- package/dist/AgenticID.js +1188 -0
- package/dist/AgenticID.js.map +1 -0
- package/dist/AgenticIDClient.d.ts +68 -0
- package/dist/AgenticIDClient.d.ts.map +1 -0
- package/dist/AgenticIDClient.js +198 -0
- package/dist/AgenticIDClient.js.map +1 -0
- package/dist/AttestorClient.d.ts +465 -0
- package/dist/AttestorClient.d.ts.map +1 -0
- package/dist/AttestorClient.js +1030 -0
- package/dist/AttestorClient.js.map +1 -0
- package/dist/Providers.d.ts +72 -0
- package/dist/Providers.d.ts.map +1 -0
- package/dist/Providers.js +182 -0
- package/dist/Providers.js.map +1 -0
- package/dist/ReputationClient.d.ts +213 -0
- package/dist/ReputationClient.d.ts.map +1 -0
- package/dist/ReputationClient.js +708 -0
- package/dist/ReputationClient.js.map +1 -0
- package/dist/SandboxClient.d.ts +107 -0
- package/dist/SandboxClient.d.ts.map +1 -0
- package/dist/SandboxClient.js +200 -0
- package/dist/SandboxClient.js.map +1 -0
- package/dist/ServeProof.d.ts +161 -0
- package/dist/ServeProof.d.ts.map +1 -0
- package/dist/ServeProof.js +230 -0
- package/dist/ServeProof.js.map +1 -0
- package/dist/ServeSession.d.ts +180 -0
- package/dist/ServeSession.d.ts.map +1 -0
- package/dist/ServeSession.js +336 -0
- package/dist/ServeSession.js.map +1 -0
- package/dist/Settings.d.ts +179 -0
- package/dist/Settings.d.ts.map +1 -0
- package/dist/Settings.js +247 -0
- package/dist/Settings.js.map +1 -0
- package/dist/abi.d.ts +2216 -0
- package/dist/abi.d.ts.map +1 -0
- package/dist/abi.js +1248 -0
- package/dist/abi.js.map +1 -0
- package/dist/cli/commands/cells.d.ts +34 -0
- package/dist/cli/commands/cells.d.ts.map +1 -0
- package/dist/cli/commands/cells.js +66 -0
- package/dist/cli/commands/cells.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts +15 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -0
- package/dist/cli/commands/doctor.js +236 -0
- package/dist/cli/commands/doctor.js.map +1 -0
- package/dist/cli/commands/interactive.d.ts +107 -0
- package/dist/cli/commands/interactive.d.ts.map +1 -0
- package/dist/cli/commands/interactive.js +3034 -0
- package/dist/cli/commands/interactive.js.map +1 -0
- package/dist/cli/commands/list.d.ts +31 -0
- package/dist/cli/commands/list.d.ts.map +1 -0
- package/dist/cli/commands/list.js +115 -0
- package/dist/cli/commands/list.js.map +1 -0
- package/dist/cli/commands/providers.d.ts +3 -0
- package/dist/cli/commands/providers.d.ts.map +1 -0
- package/dist/cli/commands/providers.js +21 -0
- package/dist/cli/commands/providers.js.map +1 -0
- package/dist/cli/commands/settings.d.ts +22 -0
- package/dist/cli/commands/settings.d.ts.map +1 -0
- package/dist/cli/commands/settings.js +188 -0
- package/dist/cli/commands/settings.js.map +1 -0
- package/dist/cli/commands/status.d.ts +16 -0
- package/dist/cli/commands/status.d.ts.map +1 -0
- package/dist/cli/commands/status.js +148 -0
- package/dist/cli/commands/status.js.map +1 -0
- package/dist/cli/commands/update.d.ts +21 -0
- package/dist/cli/commands/update.d.ts.map +1 -0
- package/dist/cli/commands/update.js +95 -0
- package/dist/cli/commands/update.js.map +1 -0
- package/dist/cli/config.d.ts +73 -0
- package/dist/cli/config.d.ts.map +1 -0
- package/dist/cli/config.js +239 -0
- package/dist/cli/config.js.map +1 -0
- package/dist/cli/env.d.ts +36 -0
- package/dist/cli/env.d.ts.map +1 -0
- package/dist/cli/env.js +74 -0
- package/dist/cli/env.js.map +1 -0
- package/dist/cli/envelope.d.ts +33 -0
- package/dist/cli/envelope.d.ts.map +1 -0
- package/dist/cli/envelope.js +62 -0
- package/dist/cli/envelope.js.map +1 -0
- package/dist/cli/errors.d.ts +48 -0
- package/dist/cli/errors.d.ts.map +1 -0
- package/dist/cli/errors.js +81 -0
- package/dist/cli/errors.js.map +1 -0
- package/dist/cli/inference.d.ts +21 -0
- package/dist/cli/inference.d.ts.map +1 -0
- package/dist/cli/inference.js +60 -0
- package/dist/cli/inference.js.map +1 -0
- package/dist/cli/logo.d.ts +21 -0
- package/dist/cli/logo.d.ts.map +1 -0
- package/dist/cli/logo.js +131 -0
- package/dist/cli/logo.js.map +1 -0
- package/dist/cli/main.d.ts +14 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +223 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/proofs.d.ts +67 -0
- package/dist/cli/proofs.d.ts.map +1 -0
- package/dist/cli/proofs.js +133 -0
- package/dist/cli/proofs.js.map +1 -0
- package/dist/cli/ref.d.ts +39 -0
- package/dist/cli/ref.d.ts.map +1 -0
- package/dist/cli/ref.js +48 -0
- package/dist/cli/ref.js.map +1 -0
- package/dist/cli/sdk.d.ts +24 -0
- package/dist/cli/sdk.d.ts.map +1 -0
- package/dist/cli/sdk.js +65 -0
- package/dist/cli/sdk.js.map +1 -0
- package/dist/cli/settings.d.ts +66 -0
- package/dist/cli/settings.d.ts.map +1 -0
- package/dist/cli/settings.js +137 -0
- package/dist/cli/settings.js.map +1 -0
- package/dist/cli/tokenize.d.ts +61 -0
- package/dist/cli/tokenize.d.ts.map +1 -0
- package/dist/cli/tokenize.js +157 -0
- package/dist/cli/tokenize.js.map +1 -0
- package/dist/cli/types.d.ts +25 -0
- package/dist/cli/types.d.ts.map +1 -0
- package/dist/cli/types.js +8 -0
- package/dist/cli/types.js.map +1 -0
- package/dist/constants.d.ts +107 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +74 -0
- package/dist/constants.js.map +1 -0
- package/dist/context.d.ts +108 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +64 -0
- package/dist/context.js.map +1 -0
- package/dist/index.d.ts +45 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +118 -0
- package/dist/index.js.map +1 -0
- package/dist/provider-catalog.json +23 -0
- package/dist/seal.d.ts +47 -0
- package/dist/seal.d.ts.map +1 -0
- package/dist/seal.js +145 -0
- package/dist/seal.js.map +1 -0
- package/dist/secretEnv.d.ts +119 -0
- package/dist/secretEnv.d.ts.map +1 -0
- package/dist/secretEnv.js +199 -0
- package/dist/secretEnv.js.map +1 -0
- package/dist/taskHash.d.ts +39 -0
- package/dist/taskHash.d.ts.map +1 -0
- package/dist/taskHash.js +119 -0
- package/dist/taskHash.js.map +1 -0
- package/dist/types.d.ts +336 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +19 -0
- package/dist/types.js.map +1 -0
- package/package.json +75 -4
- package/scripts/sync-providers.cjs +8 -0
- package/src/AgentClient.ts +897 -0
- package/src/AgenticID.ts +1382 -0
- package/src/AgenticIDClient.ts +238 -0
- package/src/AttestorClient.ts +1306 -0
- package/src/Providers.ts +176 -0
- package/src/ReputationClient.ts +821 -0
- package/src/SandboxClient.ts +227 -0
- package/src/ServeProof.ts +290 -0
- package/src/ServeSession.ts +421 -0
- package/src/Settings.ts +296 -0
- package/src/abi.ts +1282 -0
- package/src/cli/commands/cells.ts +61 -0
- package/src/cli/commands/doctor.ts +235 -0
- package/src/cli/commands/interactive.ts +2715 -0
- package/src/cli/commands/list.ts +117 -0
- package/src/cli/commands/providers.ts +16 -0
- package/src/cli/commands/settings.ts +197 -0
- package/src/cli/commands/status.ts +170 -0
- package/src/cli/commands/update.ts +86 -0
- package/src/cli/config.ts +225 -0
- package/src/cli/env.ts +90 -0
- package/src/cli/envelope.ts +57 -0
- package/src/cli/errors.ts +114 -0
- package/src/cli/inference.ts +57 -0
- package/src/cli/logo.ts +125 -0
- package/src/cli/main.ts +235 -0
- package/src/cli/proofs.ts +160 -0
- package/src/cli/ref.ts +58 -0
- package/src/cli/sdk.ts +65 -0
- package/src/cli/settings.ts +153 -0
- package/src/cli/tokenize.ts +131 -0
- package/src/cli/types.ts +27 -0
- package/src/constants.ts +106 -0
- package/src/context.ts +161 -0
- package/src/index.ts +129 -0
- package/src/provider-catalog.json +23 -0
- package/src/seal.ts +163 -0
- package/src/secretEnv.ts +250 -0
- package/src/taskHash.ts +100 -0
- package/src/types.ts +357 -0
package/PROVIDERS.zh.md
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# 推理 provider
|
|
2
|
+
|
|
3
|
+
attestor 通过 `GET /inference/providers` 提供平台注册表,运维通过
|
|
4
|
+
`PUT /admin/inference/providers` 发布更新。配置存入 Postgres,API 多实例共享,
|
|
5
|
+
重启后保留。发布配置无需 SSH、替换服务器文件、OSS 或重启进程。
|
|
6
|
+
公开注册表仅包含路由和模型信息,不包含用户推理 key。
|
|
7
|
+
|
|
8
|
+
## 首次上线
|
|
9
|
+
|
|
10
|
+
SDK/CLI、attestor 与所有已配置 sealed 镜像统一升级。按本次版本更新已有的
|
|
11
|
+
`ATTESTOR_SANDBOX_SNAPSHOT` / `ATTESTOR_FRAMEWORKS`,开启已有的加密凭据开关:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
ATTESTOR_SECRET_ENV_ENABLED=true
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
先构建并上传全部 sealed 镜像,再统一升级 attestor API、worker、indexer 并启用对应镜像。
|
|
18
|
+
已有 agent 用 reset 换到新镜像。worker 会内部注入 `SEAL_BOOT_TICKET`,不用运维手配;
|
|
19
|
+
新镜像不接受缺少票据的启动。stop/start 保留票据和已授权 provider 路由,轮换启动代次;
|
|
20
|
+
reset 使用新票据并可重新授权 provider。拒绝的 provision 请求不会修改或删除容器。
|
|
21
|
+
|
|
22
|
+
不新增管理员或镜像能力 ENV。运维写入由 **attestor 对应 Tapp 的当前 owner** 授权,
|
|
23
|
+
使用已有的 `ATTESTOR_APP_ID`、`ATTESTOR_TAPP_REGISTRY_ADDR` 调用 `getAppInfo`
|
|
24
|
+
实时查询;不使用 attestor 的 TEE 签名身份、agent owner 或 sandbox 管理员名单。
|
|
25
|
+
Tapp 未配置、未注册或 RPC 查询失败时,拒绝发布。
|
|
26
|
+
|
|
27
|
+
`GET /config` 根据本版本与已配置的框架、snapshot 名称自动声明能力。Hermes
|
|
28
|
+
声明 managed OpenAI,其余内置 adapter 声明 managed OpenAI 和 Anthropic;
|
|
29
|
+
native 接线与凭据版本也自动声明。未配置的显式镜像不在能力名单中。
|
|
30
|
+
部署约定是整套运行时同版发布,不混用新旧镜像。
|
|
31
|
+
|
|
32
|
+
主包和旧名兼容包发布后,旧用户可用 `0g-agenticid update` 升级。旧 key 原子迁移到
|
|
33
|
+
`inferenceKeys["0g-compute"]`,保留钱包、其他 provider 的 key、proof tickets 和
|
|
34
|
+
secret-env 降级保护记录,见 [升级说明](./MIGRATION.zh.md)。
|
|
35
|
+
|
|
36
|
+
## 发布 provider
|
|
37
|
+
|
|
38
|
+
provider 更新属于 attestor 运维操作,通过 HTTP API 或 SDK 在运维脚本、后台中
|
|
39
|
+
执行。CLI 只读注册表,不提供 provider 发布命令。
|
|
40
|
+
|
|
41
|
+
先读取当前版本及配置:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl -fsS "$ATTESTOR_URL/inference/providers" > providers.json
|
|
45
|
+
# 修改 providers,保留 version 原值。
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
运维脚本通过配置了 attestor Tapp owner 钱包的 SDK 客户端签名并提交修改:
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
import { readFileSync } from 'node:fs';
|
|
52
|
+
import { AgentDNA } from '@0gfoundation/0g-agentdna';
|
|
53
|
+
|
|
54
|
+
const ag = await AgentDNA.fromAttestor(attestorUrl, { account });
|
|
55
|
+
const edited = JSON.parse(readFileSync('providers.json', 'utf8'));
|
|
56
|
+
await ag.admin.updateProviders(edited.providers, { baseVersion: edited.version });
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
只上传配置及签名,私钥留在签名钱包中。文件里的原始版本保护读取、编辑到发布期间的
|
|
60
|
+
并发修改。发布会替换完整名单,因此要保留现有条目。外部签名器也可以按下文准备并
|
|
61
|
+
提交签名 HTTP 请求。
|
|
62
|
+
|
|
63
|
+
例如,向导出的名单追加一个托管 provider:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"id": "partner",
|
|
68
|
+
"name": "Partner",
|
|
69
|
+
"formats": ["openai"],
|
|
70
|
+
"defaultFormat": "openai",
|
|
71
|
+
"endpoints": {"openai": "https://partner.example/v1"},
|
|
72
|
+
"models": [{
|
|
73
|
+
"id": "model-id",
|
|
74
|
+
"supported_formats": ["openai"],
|
|
75
|
+
"supported_parameters": ["tools"],
|
|
76
|
+
"context_length": 128000,
|
|
77
|
+
"max_completion_tokens": 16000
|
|
78
|
+
}]
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
域名为占位符。可用静态列表,或返回 `{ "data": [...] }` 的公开 `modelCatalog`。
|
|
83
|
+
仅返回 ID 的目录表示模型能力未知。协议限于已实现的 OpenAI/Anthropic 接线;
|
|
84
|
+
其他协议或特殊鉴权仍需改代码发版。endpoint 和目录必须为 HTTPS,不含内嵌凭据、
|
|
85
|
+
query 或 fragment。兼容参数仅作用于对应 provider;新增托管服务不继承 compute
|
|
86
|
+
的元数据或路由猜测。名单必须保留 `0g-compute`。仅 `openai`、`anthropic` 可标记
|
|
87
|
+
native,使用框架自身接线,不设置自定义 endpoint。
|
|
88
|
+
|
|
89
|
+
## 发布 API
|
|
90
|
+
|
|
91
|
+
`PUT /admin/inference/providers` 接收:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{"document":"<原始JSON字符串>","signature":"0x<EIP-191签名>"}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
文档包含 `schema:1`、`chain_id`、`agentic_id_addr`、`tapp_registry_addr`、
|
|
98
|
+
`attestor_app_id`、`base_version`、`expires_at`(Unix 秒)和 `providers`。签名消息为
|
|
99
|
+
`AgentDNA.ProviderRegistry.v1:<document UTF-8 字节的 sha256,小写hex,不含0x>`。
|
|
100
|
+
签名覆盖提交的原始字节,不重新序列化。请求须在未来 300 秒内过期,SDK 使用 180 秒。
|
|
101
|
+
这是发布请求的有效期,已接受配置不会因此过期。
|
|
102
|
+
|
|
103
|
+
服务端校验精确的链/合约/Tapp 范围、实时 Tapp owner 授权、结构和版本后才提交。
|
|
104
|
+
EOA 使用 EIP-191 签名,合约钱包 owner 通过
|
|
105
|
+
[EIP-1271](https://eips.ethereum.org/EIPS/eip-1271) 验证。成功返回 `{ok:true,version}`。
|
|
106
|
+
并发、过期版本或重放更新返回 HTTP 409 及当前 `version`;SDK 返回该失败,
|
|
107
|
+
不会自动重试,应重新读取再应用修改。回滚内容也作为
|
|
108
|
+
新版本发布,旧版本保留在历史表中。
|
|
109
|
+
|
|
110
|
+
`GET /inference/providers` 返回 `version`、`providers`;已发布版本还带原始
|
|
111
|
+
`document` 和 `signature`。`/config` 已声明注册表能力时,包括 404 在内的读取失败
|
|
112
|
+
都会在封装凭据、签名前终止,不回退到内置名单。版本 0 是 `sealed/internal/inference/providers.json`
|
|
113
|
+
提供的内置初始名单,SDK 构建时也打包它以兼容旧 attestor、支持离线查询。
|
|
114
|
+
已发布配置不编进 SDK 或镜像。API 使用 KMS 派生的密钥,对环境、Tapp、版本、
|
|
115
|
+
发布者及完整签名原文生成接受凭据 MAC,数据库修改无法伪造该凭据。
|
|
116
|
+
Tapp owner 转让或合约钱包策略变化后,已接受配置仍可读取;新写入始终重新查询
|
|
117
|
+
当前 owner,旧 owner 不能继续发布。
|
|
118
|
+
|
|
119
|
+
受信任 attestor 的 `/config` 仅从已验证的接受凭据生成并提供
|
|
120
|
+
`provider_registry_version`、`provider_registry_digest`。SDK 与 sealed 使用它核对
|
|
121
|
+
配置指纹、原始文档及范围,再使用注册表。这里沿用合约地址、snapshot 发现的
|
|
122
|
+
attestor 信任边界,不额外构成独立信任根。SDK 实例会拒绝低于已见版本、或同版本
|
|
123
|
+
内容冲突的注册表。
|
|
124
|
+
|
|
125
|
+
`/config` 本身不可读时也直接终止,不会当作旧 attestor;首次发现的能力会保留,
|
|
126
|
+
后续响应不能撤回已声明的注册表能力。并发刷新仅在版本、摘要及全部环境条件相同时
|
|
127
|
+
合并请求,否则分别校验各自的发现结果。
|
|
128
|
+
|
|
129
|
+
## 使用 provider
|
|
130
|
+
|
|
131
|
+
在 `0g-agentdna` 交互管理界面中执行:
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
login partner
|
|
135
|
+
settings 42 provider=partner model=model-id
|
|
136
|
+
reset 42
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
CLI 在选择 provider 前刷新名单。`login` 保留其他 key,设置以后 deploy/login
|
|
140
|
+
的默认 provider。已有 agent 的 reset 从 owner settings 读取 provider,不取全局
|
|
141
|
+
默认值;读取失败则停止。`whoami` 仅显示是否登记 key。模型补全按 provider 区分。
|
|
142
|
+
|
|
143
|
+
跨 provider 修改先保存并提示等待 reset,不把旧凭据推给新服务。同 provider 的
|
|
144
|
+
模型、thinking 修改仍可即时应用。凭据与 provider 或路由不匹配时提示 reset。
|
|
145
|
+
reset 使用已有的兼容镜像重建容器,会中断当前工作,无需重新构建镜像。
|
|
146
|
+
owner 授权创建新容器时,worker 在创建前清零当前未确认配置的尝试计数,
|
|
147
|
+
让 reset 在启动失败后用对应 key 重新尝试当前文档;内容、版本及 last-known-good
|
|
148
|
+
均保留。自动重启继续使用原有回退规则和凭据校验。
|
|
149
|
+
发布 provider 本身不会重启已有 agent。
|
|
150
|
+
|
|
151
|
+
旧 `AGENTIC_API_KEY` / `API_KEY` 仅属于 compute。按 provider 覆盖环境变量时,
|
|
152
|
+
同时设置 `AGENTDNA_API_KEY_PROVIDER`、`AGENTDNA_API_KEY`,无归属的新变量被拒绝。
|
|
153
|
+
key 通过遮罩输入或环境变量提供,不进 argv,本地按 `inferenceKeys[provider]`
|
|
154
|
+
保存在权限为 0600 的凭据文件内。
|
|
155
|
+
|
|
156
|
+
## 查询 agent 当前配置
|
|
157
|
+
|
|
158
|
+
owner 的 `0g-agentdna settings <agent>` / `ag.agent.getSettings(sealId)` 读取的是
|
|
159
|
+
attestor 在 Postgres 保存的文档,可能包含等待 reset 的修改。agent 自查当前已采用的
|
|
160
|
+
配置,应走容器内部接口:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
curl --unix-socket "$SEAL_SIGN_SOCK" http://localhost/settings
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
结果来自 sealed 已成功渲染的运行状态,包含 `source: "runtime"`、provider、model、
|
|
167
|
+
thinking,以及托管路由的 `base_url`、`format`、`registry_version` 和 `route_hash`。
|
|
168
|
+
原生 framework 路由不返回 `base_url`。不返回 API key 或任意 framework 配置;不查询
|
|
169
|
+
attestor 的最新 settings。启动尚未准备好时返回 503。此接口只在 0600 内部 socket 上
|
|
170
|
+
免签可读,公开 HTTP 的 `/_seal/settings` 仍需 owner 签名。
|
|
171
|
+
|
|
172
|
+
## SDK
|
|
173
|
+
|
|
174
|
+
```typescript
|
|
175
|
+
const ag = await AgentDNA.fromAttestor(attestorUrl, { account });
|
|
176
|
+
ag.agent.listProviders(); // 读缓存;fromAttestor 会加载新注册表
|
|
177
|
+
await ag.agent.refreshProviders(); // 取得新的已验证快照
|
|
178
|
+
await ag.agent.listModels({ provider: 'partner' });
|
|
179
|
+
|
|
180
|
+
const { settings, version } = await ag.agent.getSettings(sealId);
|
|
181
|
+
await ag.agent.setSettings(sealId, {
|
|
182
|
+
...(settings ?? {}), provider: 'partner', model: 'model-id',
|
|
183
|
+
}, { baseVersion: version });
|
|
184
|
+
await ag.agent.reset(sealId, { provider: 'partner', apiKey: partnerKey });
|
|
185
|
+
|
|
186
|
+
// 仅 attestor Tapp owner 钱包:
|
|
187
|
+
const current = await ag.agent.getProviderRegistry();
|
|
188
|
+
await ag.admin.updateProviders(updatedProviders, { baseVersion: current.version });
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
owner 为合约钱包时,只读客户端可以准备精确消息,在外部取得 owner 钱包的
|
|
192
|
+
EIP-1271 签名,再转发提交,无需持有 owner 私钥:
|
|
193
|
+
|
|
194
|
+
```typescript
|
|
195
|
+
const request = await ag.admin.prepareProviderUpdate(updatedProviders, {
|
|
196
|
+
baseVersion: current.version,
|
|
197
|
+
});
|
|
198
|
+
// 在请求过期前,取得 owner 钱包对 request.message 的 signature。
|
|
199
|
+
await ag.admin.publishSignedProviders({ document: request.document, signature });
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
无参数模型查询仍默认 compute。原生 provider 无目录时允许手动输入模型 ID。
|
|
204
|
+
首次部署非 compute agent,或 compute 路由已改动时,不传 `sandbox`,等待 mint,
|
|
205
|
+
保存 provider/model 设置,再携带 provider/key/framework 调用 start。CLI 向导在
|
|
206
|
+
询问完成后重新读取当前注册表,并执行此流程。只有未改动的内置 compute 路由
|
|
207
|
+
支持一步部署,其他一步部署请求会在签名前拒绝。
|
|
208
|
+
|
|
209
|
+
## 凭据及运行时绑定
|
|
210
|
+
|
|
211
|
+
动态路由沿用现有 ECIES 加密,明文使用 v3:
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
{"v":3,"owner":"0x...","provider":"partner","route_hash":"0x...","registry":{"version":1,"digest":"0x..."},"env":{"API_KEY":"..."}}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
路由 hash 覆盖 provider ID、native/managed 类型、协议集合、默认协议和固定地址,
|
|
218
|
+
SDK/Go 使用固定字段顺序编码并共享跨语言测试向量,不包含模型元数据。
|
|
219
|
+
v3 需要对应镜像声明支持,不允许回退到明文。`sealApiKey` 同样支持服务端加密,
|
|
220
|
+
提交其不透明结果时传相同 provider。
|
|
221
|
+
|
|
222
|
+
v3 凭据还绑定已接受注册表的 `registry.version` 和 `registry.digest`。sealed 用实时
|
|
223
|
+
owner 验证凭据,通过 `GET /inference/providers?version=N` 读取该历史版本,并在
|
|
224
|
+
查询模型目录或写框架配置前验证文档摘要和路由 hash。Postgres 保留已接受的历史版本;
|
|
225
|
+
stop/start 使用原凭据和原版本,更新地址或从最新名单删除 provider 都不会重定向旧 key。
|
|
226
|
+
签名后、首次启动前发生发布,也仍读取已授权版本。owner 通过 reset 携带新 key 绑定新
|
|
227
|
+
版本与路由。历史版本缺失、被篡改或不可读取时失败关闭,不改用最新地址。
|
|
228
|
+
如果 owner 已把 agent settings 改成另一个 provider,则仍需要 reset;stop/start 不会
|
|
229
|
+
为新 provider 提供凭据。
|
|
230
|
+
旧明文/v1 key 仅属于 compute;v2 继续兼容内置原生定义。无效密文不回退到另一份
|
|
231
|
+
明文 key;注册表获取或接受凭据校验失败不代用 compute。这些约束覆盖平台渲染的路由及
|
|
232
|
+
凭据,不是框架所有网络行为的出口限制。
|
|
233
|
+
|
|
234
|
+
English: [PROVIDERS.md](PROVIDERS.md).
|
package/README.md
CHANGED
|
@@ -1,3 +1,335 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 0g-agentdna
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@0gfoundation/0g-agentdna) [](./LICENSE)
|
|
4
|
+
|
|
5
|
+
**0G AgentDNA** TypeScript SDK for the AgenticID protocol — deploy, call, and build on-chain reputation for autonomous AI agents. Built on [viem](https://viem.sh).
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @0gfoundation/0g-agentdna viem
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
**What do you want to do?**
|
|
12
|
+
|
|
13
|
+
- **Deploy & run your own agent** → [Quickstart](#quickstart)
|
|
14
|
+
- **Call another agent, leave reputation** → [`ag.reputation`](#agreputation--serve-proof--feedback)
|
|
15
|
+
- **Independently verify a serve-proof** → [serve-proof primitives](./GUIDE.md#advanced) (in the guide)
|
|
16
|
+
|
|
17
|
+
> This README is the **interface reference** — signatures and shapes. The **[Guide](./GUIDE.md)** explains the reasoning behind each call; the [repo](https://github.com/0gfoundation/0g-agentic-id) has protocol docs + source.
|
|
18
|
+
|
|
19
|
+
Upgrading from the old SDK/CLI? See [migration](./MIGRATION.md) ([中文](./MIGRATION.zh.md)).
|
|
20
|
+
Provider registration, CLI switching, and image rollout: [providers](./PROVIDERS.md) ([中文](./PROVIDERS.zh.md)).
|
|
21
|
+
|
|
22
|
+
## The API at a glance
|
|
23
|
+
|
|
24
|
+
One entry point: agent, reputation, and admin namespaces + top-level ops.
|
|
25
|
+
|
|
26
|
+
| Surface | What |
|
|
27
|
+
|---|---|
|
|
28
|
+
| `ag.agent` | agent lifecycle (deploy / clone / transfer), reads (owner, agentSeal, iData…), agent-seal gas top-up |
|
|
29
|
+
| `ag.reputation` | capture a TEE-signed serve-proof, verify it, submit/read on-chain feedback |
|
|
30
|
+
| `ag.ack()` / `ag.ackStatus()` | acknowledge the TEE trust-root component set (attestor + kms + sandbox-provider) |
|
|
31
|
+
| `ag.deposit()` / `ag.getBalance()` | fund / read the prepaid sandbox balance (pay-as-you-go runtime) |
|
|
32
|
+
| `ag.getBalanceDetail()` / `ag.requestRefund()` / `ag.withdrawRefund()` | full 3-value account view; withdraw prepaid funds (time-locked two-step) |
|
|
33
|
+
|
|
34
|
+
Backends (AgenticID / the canonical ERC-8004 ReputationRegistry + VerifiedFeedbackRegistry / TappRegistry / SandboxServing contracts + the attestor's HTTP endpoints) are hidden behind the facade — you don't decide which call is on-chain and which is HTTP.
|
|
35
|
+
|
|
36
|
+
## Quickstart
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import { AgentDNA } from '@0gfoundation/0g-agentdna';
|
|
40
|
+
|
|
41
|
+
// 0G mainnet; for the Galileo testnet use 'https://agenticid-testnet.0g.ai'
|
|
42
|
+
const ag = await AgentDNA.fromAttestor('https://agenticid.0g.ai', {
|
|
43
|
+
account: process.env.PRIVATE_KEY as `0x${string}`, // omit for read-only
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`fromAttestor` reads the attestor's `GET /config` and fills all contract addresses, RPC, and appIds — the URL alone pins the environment (0G AgenticID is ERC-8004 identity + reputation, plus ERC-7857 sealed intelligent data). Manual construction (`new AgentDNA({ addresses, … })`), `overrides`, custom `walletClient`, and the full config shape are covered in the [setup guide](./GUIDE.md#setup).
|
|
48
|
+
|
|
49
|
+
**What you pass grows with what you do:**
|
|
50
|
+
|
|
51
|
+
| You want to… | Pass |
|
|
52
|
+
|---|---|
|
|
53
|
+
| read the chain (owner, balance, agent data) | `addresses` only (RPC has a built-in default) |
|
|
54
|
+
| write to the chain (deploy, transfer, feedback) | `+ account` |
|
|
55
|
+
| manage containers / see deploy status | `+ attestorUrl` |
|
|
56
|
+
|
|
57
|
+
Bindings used in the snippets below:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
const agentId = 33n; // ERC-7857 tokenId (ERC-721-compatible)
|
|
61
|
+
const owner = '0xAaAa...'; // the address that owns the agent
|
|
62
|
+
const buyer = '0xBbBb...'; // the address leaving feedback (attribution is msg.sender)
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## `ag.agent` — lifecycle + reads
|
|
66
|
+
|
|
67
|
+
> `iData` is the encrypted content minted for an agent (persona, framework binding). `deploy` assembles it from `name`/`description`/`inference` via `defaultIData()`; pass your own `iData` for full control ([details in the guide](./GUIDE.md#the-runtime-image-framework-and-idata-shapes)).
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { parseEther } from 'viem';
|
|
71
|
+
|
|
72
|
+
// deploy — signs the deploy + sandbox-create envelopes, POSTs them to the attestor
|
|
73
|
+
const params = {
|
|
74
|
+
name: 'Sage',
|
|
75
|
+
description: 'a helpful agent',
|
|
76
|
+
framework: 'openclaw', // a name from GET /config's frameworks[]; SDK resolves its sealed image
|
|
77
|
+
inference: { provider: '0g-compute', model: 'claude-sonnet-5' }, // optional (see listModels())
|
|
78
|
+
sandbox: { apiKey: process.env.AGENT_API_KEY }, // sealedImage optional — pass only to pin a specific image
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
// deploy/clone are ASYNC (submit → mint → provision). `wait` picks how far to block:
|
|
82
|
+
// omit → accepted · 'minted' → +agentId · 'running' → +url
|
|
83
|
+
const { sealId, agentSealAddr, agentId } = await ag.agent.deploy(params, { wait: 'minted' });
|
|
84
|
+
const { url } = await ag.agent.deploy(params, { wait: 'running' });
|
|
85
|
+
await ag.agent.deploy({ ...params, sandbox: undefined }, { wait: 'minted' }); // mint-only, no container
|
|
86
|
+
|
|
87
|
+
// or fire-and-forget:
|
|
88
|
+
const dep = await ag.agent.deploy(params); // → { sealId, agentSealAddr }
|
|
89
|
+
const id = await ag.agent.waitForMint(dep.sealId); // → 34n; throws on phase=failed or timeout
|
|
90
|
+
|
|
91
|
+
// clone — source owner mints a copy for another owner (attestor re-keys the sealed data)
|
|
92
|
+
const cl = await ag.agent.clone({ sourceAgentId: agentId, targetOwner: newOwner }, { wait: 'minted' });
|
|
93
|
+
// → { sealId, agentSealAddr, agentId }
|
|
94
|
+
|
|
95
|
+
// clone, contract mode (issue #133 marketplace fork) — the BUYER (connected
|
|
96
|
+
// wallet == targetOwner) signs an intent binding the policy context, and the
|
|
97
|
+
// source owner's on-chain ICloneAuthorizer decides:
|
|
98
|
+
const fork = await ag.agent.clone(
|
|
99
|
+
{ sourceAgentId, targetOwner: buyer, authorization: { authData: purchaseReceipt } },
|
|
100
|
+
{ wait: 'minted' },
|
|
101
|
+
);
|
|
102
|
+
// authorization.authorizer is optional — read live via cloneAuthorizerOf when
|
|
103
|
+
// omitted. See the GUIDE's marketplace-fork walkthrough.
|
|
104
|
+
|
|
105
|
+
// transfer — ERC-7857 (old container reaped async by the indexer; don't gate on phase right after)
|
|
106
|
+
await ag.agent.transferFrom(owner, newOwner, agentId); // → "0x…"
|
|
107
|
+
await ag.agent.safeTransferFrom(owner, newOwner, agentId); // → "0x…"
|
|
108
|
+
|
|
109
|
+
// reads
|
|
110
|
+
await ag.agent.ownerOf(agentId); // → "0x…"
|
|
111
|
+
await ag.agent.getAgentSeal(agentId); // → "0x…" the agent's on-chain signing key (address)
|
|
112
|
+
await ag.agent.getSealId(agentId); // → "0x…" bytes32 seal id (== deploy's sealId)
|
|
113
|
+
await ag.agent.getAgentIdBySealId(sealId); // → 33n reverse lookup
|
|
114
|
+
await ag.agent.isSealIdBound(sealId); // → true
|
|
115
|
+
await ag.agent.intelligentDatasOf(agentId); // → [{ dataDescription /* JSON string */, dataHash }, …]
|
|
116
|
+
await ag.agent.sealedKeysOf(agentId); // → ["0x04…", …] one sealed key per iData entry
|
|
117
|
+
await ag.agent.balanceOf(owner); // → 5n agents owned by `owner`
|
|
118
|
+
|
|
119
|
+
// agent-seal gas — the agent's own on-chain-write budget
|
|
120
|
+
await ag.agent.topUpAgentSeal(await ag.agent.getAgentSeal(agentId), parseEther('0.01')); // → "0x…"
|
|
121
|
+
|
|
122
|
+
// runtime lifecycle (owner-signed; on-chain identity preserved)
|
|
123
|
+
await ag.agent.stop(sealId, sandboxId);
|
|
124
|
+
await ag.agent.start(sealId, sandboxId); // resume a STOPPED container
|
|
125
|
+
await ag.agent.start(sealId, { apiKey }); // FIRST provision of a mint-only agent
|
|
126
|
+
await ag.agent.reset(sealId, { framework, apiKey }); // recreate an EXISTING container
|
|
127
|
+
await ag.agent.retry(sealId, { apiKey }); // resume a 'failed' deploy (do NOT redeploy — that orphans the mint)
|
|
128
|
+
await ag.agent.listDeployments(); // public listing; sandboxId/lastProvisionError null (owner+agentSeal present on minted rows)
|
|
129
|
+
await ag.agent.listMyDeployments(); // owner-signed; full detail
|
|
130
|
+
// row → { agentId, sealId, phase, sandboxId, url, owner, agentSeal, name, createdAt, lastProvisionError }
|
|
131
|
+
// phase: 'deploying' | 'running' | 'stopped' | 'offline' | 'failed'
|
|
132
|
+
|
|
133
|
+
// settings — the owner's configuration document (which model the agent thinks
|
|
134
|
+
// with, and how hard). Stored by the attestor as an OPAQUE blob and applied by
|
|
135
|
+
// the container, so widening the vocabulary never needs an attestor change.
|
|
136
|
+
// Owner-signed BOTH ways — it is on no listing and on no public row.
|
|
137
|
+
const { settings, version } = await ag.agent.getSettings(sealId);
|
|
138
|
+
// settings → { provider, model, thinking, framework } | null (null = never configured)
|
|
139
|
+
// version → the number to write back against (0 when there is no document)
|
|
140
|
+
await ag.agent.setSettings(sealId, { ...(settings ?? {}), model: '0gm-1.0-35b-a3b', thinking: 'high' }, {
|
|
141
|
+
baseVersion: version, // compare-and-swap: a stale one is refused, not applied
|
|
142
|
+
onWarn: console.warn, // advisory provider catalog check, run before signing
|
|
143
|
+
}); // → { version }
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`setSettings` writes the WHOLE document (spread the current one to change a field) and is owner-signed: the attestor verifies the signer against the **live on-chain owner**, so a seller cannot keep configuring an agent they sold — and the same signature gates the READ, because the document is the owner's, not public. It is deliberately **not** on chain — configuration is re-suppliable, where the agent's memory is not. The container picks it up on its next boot (`reset` to apply immediately) and reports success, which promotes it to last-known-good; a container that keeps coming back WITHOUT ever confirming is handed that last-known-good document instead, so a document that prevents boot costs a boot rather than the agent. `framework` is an opaque JSON section for that framework's own knobs — the platform neither parses nor validates it. `onWarn` is advisory only: an unlisted model is reported against its provider's configured catalog without blocking; native providers without a catalog accept manual model IDs. Non-compute providers require runtime image support and a provider-bound key; see [providers](./PROVIDERS.md).
|
|
147
|
+
|
|
148
|
+
Every write is a **compare-and-swap** on `baseVersion` — the version you read before editing (0 = "no document yet"). If the stored version has moved on, the write is refused with `SettingsConflictError`, which carries the document that is actually there. Re-read, re-apply, write again; do not loop on it, or the other writer's change is the one that disappears.
|
|
149
|
+
|
|
150
|
+
The [lifecycle guide](./GUIDE.md#agagent--lifecycle--reads) covers async phases, transfer teardown, mint-only vs first-provision, `apiKey` handling, and failure reasons.
|
|
151
|
+
|
|
152
|
+
`start` / `reset` / `retry` seal `apiKey` to the agent (`SEAL_SECRET_ENV`) when the attestor advertises `secret_env_scheme`, so the owner's wallet prompt never shows it. A one-shot `deploy` with `sandbox` still signs it in clear; to avoid that, deploy without `sandbox`, then `start(sealId, { apiKey })`. When your server supplies the key and a user signs, seal it on the server with `agent.sealApiKey(sealId, { owner, apiKey })` and pass the result to the browser's `start` / `reset` / `retry` as `sealedSecretEnv`, so the key never reaches the browser. See the [guide](./GUIDE.md#the-runtime-image-framework-and-idata-shapes) for `secretEnv: 'sealed' | 'plaintext'` and `SecretEnvRefusedError`.
|
|
153
|
+
|
|
154
|
+
**Three IDs, same agent:**
|
|
155
|
+
|
|
156
|
+
| Identifier | What it is | Used by |
|
|
157
|
+
|---|---|---|
|
|
158
|
+
| `agentId` (bigint) | ERC-7857 tokenId (ERC-721-compatible) | reads, transfer, clone, runtimeCosts |
|
|
159
|
+
| `sealId` (bytes32) | seal-binding hash; the attestor's deployment key | stop/start/reset/retry, waitForMint |
|
|
160
|
+
| `agentSeal` (address) | the agent's own wallet | topUpAgentSeal, serve-proof signer checks |
|
|
161
|
+
|
|
162
|
+
Convert freely: `getSealId` / `getAgentIdBySealId` / `getAgentSeal`.
|
|
163
|
+
|
|
164
|
+
## `ag.reputation` — serve-proof + feedback
|
|
165
|
+
|
|
166
|
+
When the runtime has a VerifiedFeedbackRegistry configured (`VERIFIED_FEEDBACK_ADDR`; otherwise no response carries a proof and `proof` is `null`), the sealed proxy stamps `X-Agent-Proof` on the agent's **`/api/*` services** (its outward, attributable surface) — not on the owner↔agent chat/UI routes (signing an owner-authenticated channel would be self-dealt reputation). `capture` reads that header; on-chain attribution stays `msg.sender`, and each proof is bound to a single `submitter` (the only address allowed to redeem it). Feedback is **stored in the official canonical ERC-8004 Reputation Registry** (every 8004 reader sees it natively); the local VerifiedFeedbackRegistry records which entries were proof-backed — `giveFeedback` bundles the two calls. The [reputation guide](./GUIDE.md#agreputation--serve-proof--feedback) explains why.
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
import { keccak256, toBytes } from 'viem';
|
|
170
|
+
|
|
171
|
+
// 1. call one of the agent's signed /api/* services and capture the proof (public handle needs no wallet)
|
|
172
|
+
const agent = await ag.agent.connect(agentId);
|
|
173
|
+
const { response, proof, task } = await agent.fetchWithProof('/api/summarize', {
|
|
174
|
+
method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ q: 'hi' }),
|
|
175
|
+
});
|
|
176
|
+
// proof → { agentId, submitter, timestamp, deadline, taskHash, dataHashes, frameworkHash, signature,
|
|
177
|
+
// validator /* registry it was signed for — diagnostics, not on-chain */ } | null
|
|
178
|
+
// low-level escape hatch: ag.reputation.capture(() => fetch(…))
|
|
179
|
+
|
|
180
|
+
// 2. verify before spending gas — the signature is bound to addresses.verifiedFeedback
|
|
181
|
+
// (fromAttestor fills it); registryMatches: false = none configured / a different one
|
|
182
|
+
if (proof) await ag.reputation.verifyProof(proof, { task });
|
|
183
|
+
// → { ok, signerMatches, notExpired, dataOnChain, registryMatches, taskMatches, reasons }
|
|
184
|
+
// pass { task } (the TaskExchange fetchWithProof recorded) to also get
|
|
185
|
+
// taskMatches — the proof bound to THIS response's bytes, not just the
|
|
186
|
+
// signer; ok requires it. task: null (unrecorded) fails closed with ok:
|
|
187
|
+
// false. Hand-rolled fetch: pass the TaskExchange itself — for a URL whose
|
|
188
|
+
// form is ambiguous (trailing "?") taskRevealOf's element 0 can name the
|
|
189
|
+
// wrong URI; verifyProof tries every candidate, so the exchange always
|
|
190
|
+
// matches.
|
|
191
|
+
|
|
192
|
+
// 3. submit feedback — canonical 8004 write (attribution = msg.sender) + TEE
|
|
193
|
+
// verification mark, bundled. On 7702-enabled environments (a feedbackBatcher
|
|
194
|
+
// is advertised) both land in ONE atomic type-4 tx; otherwise two sequential
|
|
195
|
+
// txs. An owner CANNOT attest feedback on their own agent, nor can the
|
|
196
|
+
// agent's own agentSeal or its payment wallet (the verified registry
|
|
197
|
+
// rejects all three). |value| must be ≤ 1e9 with 0..18 decimals.
|
|
198
|
+
// inside the same guard — serveProof is ServeProof here; the old `proof!`
|
|
199
|
+
// form would have compiled and passed null at runtime
|
|
200
|
+
if (proof) {
|
|
201
|
+
const fb = await ag.reputation.giveFeedback({ agentId, value: 5n, serveProof: proof });
|
|
202
|
+
// → { feedbackTx (mined), attestTx (pending — wait it), feedbackIndex }
|
|
203
|
+
await ag.reputation.waitForTransaction(fb.attestTx);
|
|
204
|
+
}
|
|
205
|
+
// optional params: valueDecimals / tag1 / tag2 / endpoint / feedbackURI / feedbackHash
|
|
206
|
+
// escape hatch: attestFeedback(agentId, idx, proof) marks an entry submitted separately
|
|
207
|
+
|
|
208
|
+
// canonical reads (raw 8004 feedback — permissionless, verified or not)
|
|
209
|
+
await ag.reputation.getLastIndex(agentId, buyer); // → 2n
|
|
210
|
+
await ag.reputation.readFeedback(agentId, buyer, idx); // → { value, valueDecimals, tag1, tag2, isRevoked }
|
|
211
|
+
await ag.reputation.getSummary({ agentId }); // → { count, summaryValue, summaryValueDecimals }
|
|
212
|
+
await ag.reputation.readAllFeedback({ agentId }); // filters: clientAddresses / tags / includeRevoked
|
|
213
|
+
await ag.reputation.getClients(agentId); // → ["0x…", …]
|
|
214
|
+
await ag.reputation.getResponseCount(agentId, buyer, idx, [owner]); // → 1n
|
|
215
|
+
|
|
216
|
+
// verified reads (TEE marks — intersect these with the canonical entries)
|
|
217
|
+
await ag.reputation.isVerified(agentId, buyer, idx); // → true
|
|
218
|
+
await ag.reputation.getVerifiedSummary({ agentId }); // proof-backed entries only
|
|
219
|
+
await ag.reputation.getVerifiedClients(agentId); // clients with ≥1 verified entry
|
|
220
|
+
await ag.reputation.getVerifiedIndexes(agentId, buyer); // → [1n, …]
|
|
221
|
+
await ag.reputation.getServeData(agentId, buyer, idx); // → { dataHashes, frameworkHash }
|
|
222
|
+
// task-receipt opening: pass `task` (method/uri/body hashes/status of the rated
|
|
223
|
+
// interaction) to giveFeedback and the contract verifies it against the proof's
|
|
224
|
+
// taskHash, recording the URI as the entry's TEE-verified endpoint
|
|
225
|
+
// (statusCode: an integer in 100..999 — anything else is refused before broadcast):
|
|
226
|
+
await ag.reputation.getVerifiedEndpoint(agentId, buyer, idx); // → "/hello" ("" if unrevealed)
|
|
227
|
+
await ag.reputation.getVerifiedSummaryForEndpoint(agentId, '/hello'); // per-interface verified aggregate
|
|
228
|
+
|
|
229
|
+
// owner responds to an entry; the client who left it can revoke
|
|
230
|
+
await ag.reputation.appendResponse({ agentId, clientAddress: buyer, feedbackIndex: idx, responseURI: 'ipfs://…', responseHash: keccak256(toBytes('thanks')) });
|
|
231
|
+
await ag.reputation.revokeFeedback(agentId, idx); // → "0x…"
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## Top-level ops
|
|
235
|
+
|
|
236
|
+
Two distinct balances: **`ag.deposit()`** funds the prepaid sandbox balance (compute runtime, pay-as-you-go), **`ag.agent.topUpAgentSeal()`** funds the agentSeal's own gas (the agent's on-chain activity). The [top-level-ops guide](./GUIDE.md#top-level-ops-not-scoped-to-one-agent) explains both in full.
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
import { parseEther } from 'viem';
|
|
240
|
+
|
|
241
|
+
// trust-root acknowledgment (TappRegistry — spans attestor + kms + sandbox-provider)
|
|
242
|
+
await ag.ackStatus(owner); // → { allAcked, missing }
|
|
243
|
+
await ag.components(owner); // → per-component detail
|
|
244
|
+
const ackTx = await ag.ack(); // → "0x…", or null if nothing was missing
|
|
245
|
+
if (ackTx) await ag.waitForTransaction(ackTx);
|
|
246
|
+
|
|
247
|
+
// prepaid sandbox balance (SandboxServing)
|
|
248
|
+
await ag.getBalance(); // → wei
|
|
249
|
+
const depositTx = await ag.deposit({ amountWei: parseEther('0.5') });
|
|
250
|
+
await ag.waitForTransaction(depositTx);
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
`deploy()`/`clone()` **preflight** both prerequisites (all components acked + balance ≥ 0.1 OG). Bare writes (`ack`/`deposit`/`topUpAgentSeal`) return before mining — `await ag.waitForTransaction(tx)` before reading state back; `giveFeedback` mines the canonical write internally and returns a pending `attestTx` to wait on (more in the [guide](./GUIDE.md#top-level-ops-not-scoped-to-one-agent)).
|
|
254
|
+
|
|
255
|
+
## iData & framework
|
|
256
|
+
|
|
257
|
+
You don't pass a sealed image — the SDK resolves it from your `framework` via `GET /config`'s `frameworks[]` (each `{ name, image? }`). `iData` is an array of `{ role, plaintext, extra }`; `deploy` builds a `framework` + `persona` entry by default. The [iData guide](./GUIDE.md#the-runtime-image-framework-and-idata-shapes) has the shapes and rules (WYSIWYS, persona is a one-shot seed, what the attestor validates).
|
|
258
|
+
|
|
259
|
+
```ts
|
|
260
|
+
await ag.agent.refreshProviders(); // refresh the platform registry
|
|
261
|
+
ag.agent.listProviders(); // cached provider descriptors
|
|
262
|
+
await ag.agent.listModels(); // → ['claude-opus-4-8', …] the 0G router's live catalog
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
## Cost
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
await ag.agent.estimateCosts(); // pricing + cost/min (+ your balance/runway if account set)
|
|
269
|
+
await ag.agent.runtimeCosts(agentId); // + that agent's evolution-gas balance
|
|
270
|
+
// → { prepaidBalanceWei, sealGasWei,
|
|
271
|
+
// pricing: { pricePerCPUPerMin, pricePerMemGBPerMin, createFee },
|
|
272
|
+
// costPerMinWei, estimatedRunwayMinutes }
|
|
273
|
+
// Pass { cpu, memGb } if the container spec differs.
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## Interacting with a running agent
|
|
277
|
+
|
|
278
|
+
`ag.agent.client(agentId)` resolves the URL on chain — one handle for every caller; owner ops (`chat`/`chatStream`/`logs`) are present only when `ag` holds the owner key. Multi-window apps: pass `{ instanceId }` — the container seats ONE driving client at a time (a displaced window gets 409; `claimAgent` takes the seat over; callers without an id bypass the gate). See the [guide](./GUIDE.md#agagent--lifecycle--reads).
|
|
279
|
+
|
|
280
|
+
```ts
|
|
281
|
+
const { hello, verification } = await ag.agent.sayHi(agentUrl);
|
|
282
|
+
// hello → { agent, owner, public_url, message, services, routes }
|
|
283
|
+
// services: { path, method, description?, input_example?, transport? } — proof-signed /api/* endpoints
|
|
284
|
+
// transport: "mcp" marks an MCP server endpoint (JSON-RPC over POST):
|
|
285
|
+
// mount `<base><path>` as a streamable-HTTP MCP server in any MCP client —
|
|
286
|
+
// responses carry X-Agent-Proof (when the runtime has a serve-proof
|
|
287
|
+
// validator configured). Per-exchange verification: pass fetchWithProof's
|
|
288
|
+
// returned `task` to verifyProof(proof, { task }) — the verdict's
|
|
289
|
+
// `taskMatches` binds the proof to THIS response's bytes (see mcpServices'
|
|
290
|
+
// doc in AgentClient.ts). Also: the deploy console's copy-ready curl needs
|
|
291
|
+
// `Accept: application/json, text/event-stream` for MCP routes.
|
|
292
|
+
// routes: { prefix, kind?, auth?, signed, description? } — framework prefixes (e.g. chat at /v1/)
|
|
293
|
+
|
|
294
|
+
const agent = await ag.agent.client(agentId); // agentId OR agentUrl — the SDK fills in the other half
|
|
295
|
+
agent.routes; agent.services;
|
|
296
|
+
|
|
297
|
+
if (agent.chat) { // present only with an owner key + a declared chat route
|
|
298
|
+
const { choices } = await agent.chat([{ role: 'user', content: 'hi' }], { model: 'openclaw' });
|
|
299
|
+
}
|
|
300
|
+
if (agent.chatStream) { // streaming variant — yields content deltas
|
|
301
|
+
for await (const delta of agent.chatStream(msgs, { model: 'openclaw' })) process.stdout.write(delta);
|
|
302
|
+
}
|
|
303
|
+
const r = await agent.fetch('/v1/models'); // attaches the bearer if the route asks
|
|
304
|
+
const { response, proof } = await agent.fetchWithProof('/api/summarize', { method: 'POST', body });
|
|
305
|
+
if (agent.logs) await agent.logs({ tail: 200 }); // owner-only: the agent's own process log
|
|
306
|
+
|
|
307
|
+
// Long tasks: when /hello declares a kind "responses" route, chat/chatStream
|
|
308
|
+
// already ride it — the turn is owned by a server-side task id, survives
|
|
309
|
+
// dropped connections (auto-resume by sequence number), and can be
|
|
310
|
+
// re-attached or stopped by id:
|
|
311
|
+
let taskId = '';
|
|
312
|
+
for await (const d of agent.chatStream!(msgs, { onTask: (id) => (taskId = id) })) process.stdout.write(d);
|
|
313
|
+
await agent.task!(taskId); // poll {status, output_text}
|
|
314
|
+
for await (const d of agent.followTask!(taskId)) process.stdout.write(d); // re-attach: replay + live
|
|
315
|
+
await agent.cancelTask!(taskId); // stop the turn
|
|
316
|
+
|
|
317
|
+
// opinionated shortcuts over client():
|
|
318
|
+
const auth = await ag.agent.authenticate(agentId); // mints the owner token up front (needs a wallet)
|
|
319
|
+
const pub = await ag.agent.connect(agentId); // explicit PUBLIC handle (never attaches a token)
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
`model` is the framework's own selector, not an LLM name (the LLM is fixed at deploy) — openclaw wants `"openclaw"`. The [interaction guide](./GUIDE.md#interacting-with-a-running-agent-no-console-needed) covers capability signalling, openclaw's token lifecycle, and the failure/`retry` flow.
|
|
323
|
+
|
|
324
|
+
## More
|
|
325
|
+
|
|
326
|
+
- **[Agents as owners (nested agents)](./GUIDE.md#agents-as-owners-nested-agents)** — an in-container agent runs this SDK as itself over the sign socket (`sealAccount()`), never holding a raw key.
|
|
327
|
+
- **[Addresses](./GUIDE.md#addresses)** — a deployment artifact, not baked into the SDK; `fromAttestor` fills them. Exported constants: `ZERO_G_TESTNET` / `ZERO_G_MAINNET` / `RPC_URL` / `CHAIN_ID` / `RECEIPT_WAIT`.
|
|
328
|
+
- **[Advanced](./GUIDE.md#advanced)** — raw ABIs + serve-proof primitives (`buildServeProofMessageHash`, `buildServeProofSigningHash`, `signServeProof`, `verifyServeProofSignature`, the last three taking the VerifiedFeedbackRegistry as `validator`; `taskHashOf` / `requestUriOf` / `requestUriCandidates` for the taskHash commitment) and the canonical digest spec (EIP-191 version 0x00, intended validator = the registry; 0.2.0 is a hard cut from personal_sign).
|
|
329
|
+
- **[CLI](./GUIDE.md#cli-0g-agentdna)** `npx 0g-agentdna` — interactive shell (deploy/use agents, chat with Esc-interruptible turns); `doctor` / `status <agent>` / `list` subcommands with `--json` for scripts.
|
|
330
|
+
|
|
331
|
+
## Notes
|
|
332
|
+
|
|
333
|
+
- **Serve-proof binding** — attribution is `msg.sender` at submission; each proof also names a `submitter` (the redeemer) and is signed for exactly one VerifiedFeedbackRegistry. Treat proofs as sensitive regardless of transport.
|
|
334
|
+
- **0G receipt timing** — `waitForTransaction` is tuned for 0G (120s + retries); if it times out the tx likely still landed — confirm by reading state.
|
|
335
|
+
- **On-chain types** — `value`/`summaryValue` are `int128`, `feedbackIndex` is `uint64` (all bigint).
|