dmt-agent-api 0.3.0__tar.gz

dmt_agent_api-0.3.0/.env.example

@@ -0,0 +1,3 @@
+DUMATE_API_KEY=
+DUMATE_BASE_URL=https://api.dumate.cn/api/v1
+DUMATE_AGENT_ID=

dmt_agent_api-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md .env.example
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include tools *.py

dmt_agent_api-0.3.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: dmt-agent-api
+Version: 0.3.0
+Summary: DMT Agent API Python SDK for DuMate
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: notebook
+Requires-Dist: ipython>=8; extra == "notebook"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+
+# DuMate Python SDK
+
+面向 DuMate 老版 `/api/v1` 的 Python 客户端。Python 3.10+，提供同步 `DuMate` 和异步 `AsyncDuMate`。当前版本 0.3.0，为独立开发的 SDK。
+
+应用层快速接入与前端数据协议见 [APPLICATIONS.md](docs/APPLICATIONS.md)。提供 `skills.ensure`、`conversations.create/history/stream` 和 `notebook.stream`。
+
+## 安装
+
+```bash
+pip install ./dmt_agent_api-0.3.0-py3-none-any.whl
+```
+
+源码安装：`pip install .`。配置环境变量 `DUMATE_API_KEY`；可选 `DUMATE_BASE_URL`，默认 `https://api.dumate.cn/api/v1`。Key 仅放在后端。
+
+## 一次调用，等待最终结果
+
+```python
+from dumate import DuMate
+
+with DuMate() as client:
+    agent = client.agents.create(name="我的助手")
+    session = client.sessions.create(agent_id=agent["id"])
+    result = client.runs.run_and_wait(
+        session_id=session["id"],
+        message="介绍你能完成的工作",
+        timeout=180,
+    )
+    print(result.output_text)
+```
+
+`runs.run_and_wait` 在客户端发送一次消息并轮询历史，关联本次用户消息与最终回答；没有对应的服务端 `/runs` 接口。适合网页的一键任务按钮：后端执行调用，完成后返回 `output_text`，前端展示结果即可。较长任务应由应用队列执行并提供任务状态查询。
+
+同一会话串行发送，不同会话可以并发。超时仅停止本地等待，服务端任务可能仍在执行；可查询历史或显式 `sessions.interrupt`。`timeout` 限制轮询等待，单次网络请求还受客户端 `timeout` 约束。默认等待时间无限，建议显式设置。
+
+## 流式事件
+
+```python
+with client.sessions.stream(session_id, message="帮我分析这个问题") as events:
+    for event in events:
+        if event.type == "message.part.updated":
+            part = event.properties.get("part", {})
+            print(part.get("type"), part.get("text", ""))
+        elif event.type == "session.idle" or (
+            event.type == "session.status"
+            and event.properties.get("status", {}).get("type") == "idle"
+        ):
+            break
+```
+
+流建立后才发送消息。事件保留原始 `type`、`properties` 和 `raw`，未知事件也会返回；SSE `id`、`event` 字段独立保留。应用处理规则：
+
+|数据|处理方式|
+|---|---|
+|message.updated 的 info|按消息 ID 更新角色、完成状态和错误|
+|message.part.updated 的 part|按 part ID 替换快照；text 展示文字，reasoning 折叠展示，tool 按真实状态展示|
+|增量事件|仅对明确增量字段追加；快照和增量同时出现时避免重复拼接|
+|工具调用|保留调用 ID、输入、状态和输出；只展示真实事件|
+|session.status / session.idle|更新运行状态；idle 还需核对历史中的最终答案或错误|
+|未知事件|保留原始对象供兼容处理|
+
+SDK 提供事件解析，不包含网页组件。断流抛出 `StreamInterruptedError`；应用先恢复 `sessions.history`，再重新订阅，不能自动重发原 query。SDK 不承诺事件重放或 Last-Event-ID 恢复。完整事件字段以服务端实际返回为准。
+
+## Skill
+
+ZIP 中包含技能目录和 `SKILL.md`，文件带 YAML `name`、`description`。
+
+```python
+skill = client.skills.upload("my-skill.zip")
+mount = client.skills.mount(skill["id"])
+session = client.sessions.create(agent_id=agent_id, skills=[mount])
+
+updated = client.skills.update_zip(skill["id"], "my-skill-v2.zip")
+new_mount = client.skills.mount(skill["id"])
+client.sessions.update(session["id"], skills=[new_mount])
+```
+
+挂载使用 `skillID`、`releaseID`、`type`；`mount()` 从详情取得 `releaseId`，不能把展示版本号当作发布 ID。URL 导入用 `skills.create(url=...)`，URL 更新用 `skills.update(skill_id, url=...)`。
+
+## Vault、凭据和 MCP
+
+```python
+import os
+
+vault = client.vaults.create(name="业务系统")
+credentials = client.vaults.credentials(vault["id"])
+credential = credentials.create(
+    name="业务访问令牌",
+    auth={
+        "type": "environment_variable",
+        "secretName": "BUSINESS_TOKEN",
+        "secretValue": os.environ["BUSINESS_TOKEN"],
+        "networking": {
+            "type": "limited",
+            "allowedHosts": ["api.your-company.com"],
+        },
+    },
+)
+session = client.sessions.create(agent_id=agent_id, vault_ids=[vault["id"]])
+```
+
+`auth` 原样传递平台的 `environment_variable`、`static_bearer` 或 `mcp_oauth` 结构，敏感值不要记录到日志。MCP 配置通过 `mcp_servers` 传入 Agent 或 Session，例如 `[{"type":"url","name":"business","url":"https://your-company.com/mcp"}]`；会话配置 MCP 时同时提供对应 `vault_ids`。各 MCP 的认证字段须按官方文档及服务商要求填写；SDK 不代办 OAuth 授权。平台未提供凭据更新接口，轮换需创建新凭据并迁移使用后删除旧凭据。
+
+## 文件与产物
+
+```python
+uploaded = client.files.upload("input.pdf", session_id=session_id)
+result = client.runs.run_and_wait(
+    session_id=session_id, message="总结附件", file_ids=[uploaded["fileID"]], timeout=300,
+)
+client.files.download(uploaded["fileID"], "downloaded.pdf")
+
+mapping = client.artifacts.path_map(session_id)
+for path, artifact in mapping.items():
+    if artifact.get("uploadStatus") == "ready":
+        client.artifacts.download(session_id, artifact["artifactID"], "output.bin")
+        break
+```
+
+path-map 是整个会话的产物集合，不能全部当作本轮产物。按本轮回答中的文件路径、工具结果或执行前后的映射差异关联。`output.bin` 应由业务层按选中的文件设置名称；不要直接信任远端路径。
+
+下载返回落盘信息，默认禁止覆盖，支持 `max_bytes`。文件先写临时文件，成功后提交；校验响应长度并计算 SHA-256。产物必须 ready；存储返回 403 时刷新一次 URL。存储下载不携带 DuMate Key。URL 校验阻止明显私网地址及不安全跳转；生产环境仍需网络出口策略防止 DNS 重绑定。
+
+预览由应用后端代理文件，前端按 MIME 展示图片、音视频、PDF；HTML 应隔离在 sandbox iframe 中，未知类型提供下载。签名 URL 有时效，不应长期保存为产物身份。
+
+## 异步
+
+```python
+import asyncio
+from dumate import AsyncDuMate
+
+async def main():
+    async with AsyncDuMate() as client:
+        session = await client.sessions.create(agent_id="你的 Agent ID")
+        result = await client.runs.run_and_wait(
+            session_id=session["id"], message="你好", timeout=180,
+        )
+        print(result.output_text)
+
+asyncio.run(main())
+```
+
+异步资源方法使用 `await`；列表迭代用 `async for item in client.agents.iter()`；流用 `async with client.sessions.stream(...) as events` 和 `async for`。文件落盘及 DNS 检查仍包含短同步操作，大文件应用可用专门下载工作进程。
+
+## 错误与运行边界
+
+- GET 对网络错误、429 和部分 5xx 做有限重试，默认 2 次；写操作不自动重试。
+- 写请求连接失败时 `ConnectionError.outcome_unknown=True`，先核对服务端状态，避免重复创建或执行。
+- `APIError` 包含状态码及请求 ID；异常文本不包含响应正文或 Key。应用不要直接打印凭据查询返回值。
+- `RunTimeoutError`、`RunFailedError`、`ProtocolError` 区分等待超时、运行失败和协议异常。
+- 会话与租户归属校验、鉴权、队列持久化、限流和登录恢复由业务后端负责。
+- 删除 Agent 会级联删除其会话；只清理自己创建且确认不再使用的资源。
+
+完整方法见 [API.md](docs/API.md)，验证范围见 [TESTING.md](docs/TESTING.md)。

dmt_agent_api-0.3.0/README.md

@@ -0,0 +1,153 @@
+# DuMate Python SDK
+
+面向 DuMate 老版 `/api/v1` 的 Python 客户端。Python 3.10+，提供同步 `DuMate` 和异步 `AsyncDuMate`。当前版本 0.3.0，为独立开发的 SDK。
+
+应用层快速接入与前端数据协议见 [APPLICATIONS.md](docs/APPLICATIONS.md)。提供 `skills.ensure`、`conversations.create/history/stream` 和 `notebook.stream`。
+
+## 安装
+
+```bash
+pip install ./dmt_agent_api-0.3.0-py3-none-any.whl
+```
+
+源码安装：`pip install .`。配置环境变量 `DUMATE_API_KEY`；可选 `DUMATE_BASE_URL`，默认 `https://api.dumate.cn/api/v1`。Key 仅放在后端。
+
+## 一次调用，等待最终结果
+
+```python
+from dumate import DuMate
+
+with DuMate() as client:
+    agent = client.agents.create(name="我的助手")
+    session = client.sessions.create(agent_id=agent["id"])
+    result = client.runs.run_and_wait(
+        session_id=session["id"],
+        message="介绍你能完成的工作",
+        timeout=180,
+    )
+    print(result.output_text)
+```
+
+`runs.run_and_wait` 在客户端发送一次消息并轮询历史，关联本次用户消息与最终回答；没有对应的服务端 `/runs` 接口。适合网页的一键任务按钮：后端执行调用，完成后返回 `output_text`，前端展示结果即可。较长任务应由应用队列执行并提供任务状态查询。
+
+同一会话串行发送，不同会话可以并发。超时仅停止本地等待，服务端任务可能仍在执行；可查询历史或显式 `sessions.interrupt`。`timeout` 限制轮询等待，单次网络请求还受客户端 `timeout` 约束。默认等待时间无限，建议显式设置。
+
+## 流式事件
+
+```python
+with client.sessions.stream(session_id, message="帮我分析这个问题") as events:
+    for event in events:
+        if event.type == "message.part.updated":
+            part = event.properties.get("part", {})
+            print(part.get("type"), part.get("text", ""))
+        elif event.type == "session.idle" or (
+            event.type == "session.status"
+            and event.properties.get("status", {}).get("type") == "idle"
+        ):
+            break
+```
+
+流建立后才发送消息。事件保留原始 `type`、`properties` 和 `raw`，未知事件也会返回；SSE `id`、`event` 字段独立保留。应用处理规则：
+
+|数据|处理方式|
+|---|---|
+|message.updated 的 info|按消息 ID 更新角色、完成状态和错误|
+|message.part.updated 的 part|按 part ID 替换快照；text 展示文字，reasoning 折叠展示，tool 按真实状态展示|
+|增量事件|仅对明确增量字段追加；快照和增量同时出现时避免重复拼接|
+|工具调用|保留调用 ID、输入、状态和输出；只展示真实事件|
+|session.status / session.idle|更新运行状态；idle 还需核对历史中的最终答案或错误|
+|未知事件|保留原始对象供兼容处理|
+
+SDK 提供事件解析，不包含网页组件。断流抛出 `StreamInterruptedError`；应用先恢复 `sessions.history`，再重新订阅，不能自动重发原 query。SDK 不承诺事件重放或 Last-Event-ID 恢复。完整事件字段以服务端实际返回为准。
+
+## Skill
+
+ZIP 中包含技能目录和 `SKILL.md`，文件带 YAML `name`、`description`。
+
+```python
+skill = client.skills.upload("my-skill.zip")
+mount = client.skills.mount(skill["id"])
+session = client.sessions.create(agent_id=agent_id, skills=[mount])
+
+updated = client.skills.update_zip(skill["id"], "my-skill-v2.zip")
+new_mount = client.skills.mount(skill["id"])
+client.sessions.update(session["id"], skills=[new_mount])
+```
+
+挂载使用 `skillID`、`releaseID`、`type`；`mount()` 从详情取得 `releaseId`，不能把展示版本号当作发布 ID。URL 导入用 `skills.create(url=...)`，URL 更新用 `skills.update(skill_id, url=...)`。
+
+## Vault、凭据和 MCP
+
+```python
+import os
+
+vault = client.vaults.create(name="业务系统")
+credentials = client.vaults.credentials(vault["id"])
+credential = credentials.create(
+    name="业务访问令牌",
+    auth={
+        "type": "environment_variable",
+        "secretName": "BUSINESS_TOKEN",
+        "secretValue": os.environ["BUSINESS_TOKEN"],
+        "networking": {
+            "type": "limited",
+            "allowedHosts": ["api.your-company.com"],
+        },
+    },
+)
+session = client.sessions.create(agent_id=agent_id, vault_ids=[vault["id"]])
+```
+
+`auth` 原样传递平台的 `environment_variable`、`static_bearer` 或 `mcp_oauth` 结构，敏感值不要记录到日志。MCP 配置通过 `mcp_servers` 传入 Agent 或 Session，例如 `[{"type":"url","name":"business","url":"https://your-company.com/mcp"}]`；会话配置 MCP 时同时提供对应 `vault_ids`。各 MCP 的认证字段须按官方文档及服务商要求填写；SDK 不代办 OAuth 授权。平台未提供凭据更新接口，轮换需创建新凭据并迁移使用后删除旧凭据。
+
+## 文件与产物
+
+```python
+uploaded = client.files.upload("input.pdf", session_id=session_id)
+result = client.runs.run_and_wait(
+    session_id=session_id, message="总结附件", file_ids=[uploaded["fileID"]], timeout=300,
+)
+client.files.download(uploaded["fileID"], "downloaded.pdf")
+
+mapping = client.artifacts.path_map(session_id)
+for path, artifact in mapping.items():
+    if artifact.get("uploadStatus") == "ready":
+        client.artifacts.download(session_id, artifact["artifactID"], "output.bin")
+        break
+```
+
+path-map 是整个会话的产物集合，不能全部当作本轮产物。按本轮回答中的文件路径、工具结果或执行前后的映射差异关联。`output.bin` 应由业务层按选中的文件设置名称；不要直接信任远端路径。
+
+下载返回落盘信息，默认禁止覆盖，支持 `max_bytes`。文件先写临时文件，成功后提交；校验响应长度并计算 SHA-256。产物必须 ready；存储返回 403 时刷新一次 URL。存储下载不携带 DuMate Key。URL 校验阻止明显私网地址及不安全跳转；生产环境仍需网络出口策略防止 DNS 重绑定。
+
+预览由应用后端代理文件，前端按 MIME 展示图片、音视频、PDF；HTML 应隔离在 sandbox iframe 中，未知类型提供下载。签名 URL 有时效，不应长期保存为产物身份。
+
+## 异步
+
+```python
+import asyncio
+from dumate import AsyncDuMate
+
+async def main():
+    async with AsyncDuMate() as client:
+        session = await client.sessions.create(agent_id="你的 Agent ID")
+        result = await client.runs.run_and_wait(
+            session_id=session["id"], message="你好", timeout=180,
+        )
+        print(result.output_text)
+
+asyncio.run(main())
+```
+
+异步资源方法使用 `await`；列表迭代用 `async for item in client.agents.iter()`；流用 `async with client.sessions.stream(...) as events` 和 `async for`。文件落盘及 DNS 检查仍包含短同步操作，大文件应用可用专门下载工作进程。
+
+## 错误与运行边界
+
+- GET 对网络错误、429 和部分 5xx 做有限重试，默认 2 次；写操作不自动重试。
+- 写请求连接失败时 `ConnectionError.outcome_unknown=True`，先核对服务端状态，避免重复创建或执行。
+- `APIError` 包含状态码及请求 ID；异常文本不包含响应正文或 Key。应用不要直接打印凭据查询返回值。
+- `RunTimeoutError`、`RunFailedError`、`ProtocolError` 区分等待超时、运行失败和协议异常。
+- 会话与租户归属校验、鉴权、队列持久化、限流和登录恢复由业务后端负责。
+- 删除 Agent 会级联删除其会话；只清理自己创建且确认不再使用的资源。
+
+完整方法见 [API.md](docs/API.md)，验证范围见 [TESTING.md](docs/TESTING.md)。

dmt_agent_api-0.3.0/docs/API.md

@@ -0,0 +1,27 @@
+# 方法索引
+
+所有 JSON 响应保留服务端原字段名；可选参数默认省略。除特别说明外，同步与异步参数一致。
+
+|资源|方法|
+|---|---|
+|agents|list(keyword,cursor,limit)、iter、create(name,description,system,skills,files,mcp_servers,tools)、get(id,version)、update(id,version,system,skills,files,mcp_servers,tools)、delete(id)|
+|skills|list(page,page_size,skill_id,keyword,order)、iter(page_size)、upload(file)、create(url)、get(id,release_id)、update(id,url)、update_zip(id,file)、mount(id,release_id,type)、delete(id)|
+|vaults|list(cursor,limit)、iter、create(name)、get(id)、delete(id)、credentials(vault_id)|
+|vaults.credentials(id)|list(cursor,limit,auth_type)、iter、create(name,auth)、get(id)、delete(id)|
+|sessions|list(cursor,limit,status)、iter、create(agent_id,metadata,vault_ids,skills,mcp_servers)、get(id)、update(id,metadata,vault_ids,skills,mcp_servers)、delete(id)|
+|sessions 消息|history(id,limit,paginated)、send(id,message,file_ids)、send_event(id,event)、stream(id,message,file_ids)、interrupt(id)、submit_tool_result(id,custom_tool_use_id,content,is_error)、resource_points(id,start_at,end_at)|
+|files|list(cursor,limit,order,file_ids)、iter、upload(file,session_id,mime_type)、update(id,file)、get(id)、delete(id)、download(id,destination,max_bytes,overwrite)|
+|artifacts|path_map(session_id,paths)、download(session_id,artifact_id,destination,max_bytes,overwrite)|
+|runs|run_and_wait(session_id,message,file_ids,timeout,poll_interval)|
+
+ID、文件和 destination 为位置参数，其余多数参数为关键字参数；具体签名可用 Python help() 查看。异步的 `credentials(vault_id)` 和 `stream(...)` 是资源及上下文管理器工厂，不加 await。
+
+`send()` 返回 `SendReceipt`：session_id、request_id、accepted。accepted 表示接口接受，尚未表示执行成功。
+
+`run_and_wait()` 返回 `RunResult`：session_id、user_message_id、request_id、output_text、messages、status。messages 仅包含关联的 assistant 消息。附件请单独查询产物映射。
+
+自定义工具收到真实调用后，后端执行授权业务逻辑，再用 `submit_tool_result` 回传同一个 custom_tool_use_id。工具执行须自行鉴权、限流及去重。
+
+官方入口：https://cloud.baidu.com/doc/Dumate/s/Mmtv8sxf3
+
+对照文档日期：2026-11-11。当前接口版本 `/api/v1`。Skill URL 更新按官方请求示例使用 POST；文档个别标题的方法与示例存在不一致。URL 导入及外部 MCP/OAuth 需按部署环境另行验收。

dmt_agent_api-0.3.0/docs/APPLICATIONS.md

@@ -0,0 +1,85 @@
+# 应用接入：0.2
+
+## 资源管理与快捷运行
+
+资源仍可独立管理：`client.agents`、`client.skills`、`client.files`、`client.sessions`、`client.vaults`。快捷层只引用已有 ID：
+
+```python
+chat = client.conversations.create(agent_id=agent_id, skills=[skill_mount])
+receipt = client.conversations.send(chat["session_id"], message="你好")
+result = client.conversations.run(chat["session_id"], message="继续处理", timeout=300)
+client.conversations.save(client.conversations.history(chat["session_id"]), "state.json")
+```
+
+`send` 只负责受理；`run` 负责一次发送并等待最终结果；`stream` 负责事件到统一快照；`save` 写入可恢复的 JSON。
+
+## Notebook
+
+```python
+from getpass import getpass
+from dumate import DuMate
+
+with DuMate(api_key=getpass("DuMate Key：")) as client:
+    skill = client.skills.ensure(name="amount-check", file="amount-check.zip")
+    chat = client.conversations.create(
+        name="金额分析助手",
+        skills=[client.skills.mount(skill["id"])],
+    )
+    attachment = client.files.upload("amounts.txt", session_id=chat["session_id"])
+    result = client.notebook.stream(
+        chat["session_id"],
+        message="按照技能要求读取附件，计算合计。",
+        file_ids=[attachment["fileID"]],
+    )
+```
+
+安装 Notebook 可选依赖：`pip install 'dumate-agent-sdk[notebook]'`；本地 wheel 安装后可单独安装 ipython。使用 Python 3.10+。已有 Agent 时传 `agent_id`，避免每次新建。已有会话直接使用 session_id。
+
+`skills.ensure` 按精确名称复用已有 Skill，不更新其内容；新 ZIP 的 YAML name 必须与 name 相同。修改技能用 update_zip。并发首次创建可能发生平台重名冲突，不自动重试写操作。
+
+`conversations.create` 同时支持 skills、vault_ids、mcp_servers。只在没有 agent_id 时创建 Agent。会话创建失败时异常上的 created_agent_id 保留新建 Agent ID，可由应用决定清理。
+
+## 前端和后端
+
+```python
+with client.conversations.stream(session_id, message=query, file_ids=file_ids) as updates:
+    for snapshot in updates:
+        send_to_frontend(snapshot)
+```
+
+`send_to_frontend` 由业务服务实现，可以使用 SSE 或 WebSocket。每个 snapshot 为 JSON 可序列化完整状态，前端整体替换，按 message.id 和 part.id 做组件 key，无需再拼接原始 SSE。
+
+|字段|含义|
+|---|---|
+|schema_version|当前为 1|
+|session_id|当前会话|
+|revision|本次订阅内递增版本；重连后重新计数|
+|status|平台运行状态；idle 仅代表空闲，不保证成功|
+|needs_history|出现缺少对应 Part 的增量，需要历史恢复|
+|messages|消息列表，包含 id、role、finish、error、parts|
+
+Part 保留平台字段：text 显示正文，reasoning 折叠展示平台提供的内容，tool 显示 tool、state.status、state.input/output/error。未知类型可保留而不渲染。Notebook 对所有内容做 HTML 转义，工具结果默认展开且限制可视高度。返回值保留全部内容。
+
+会话快照包含用户输入和工具结果，业务服务必须鉴权，并根据用户权限脱敏。不要将凭据或任意工具输出发给无权查看的前端。
+
+## 历史、断流和并发
+
+`client.conversations.history(session_id)` 返回相同结构，可用于页面刷新。流式接口先读历史、建立 SSE 后发消息；流结束后再以历史校准快照。发生网络异常直接抛出，不自动重发 query。恢复时读取历史，再以 message=None 订阅；不承诺无损事件重放。
+
+同一会话串行发送，不同会话可并行。快照每次深拷贝，调用方修改不会污染 SDK 状态。没有独立事件 ID 时无法识别重复 delta；最终以历史为准。高频长会话可在业务层节流 UI 更新。
+
+同步和异步客户端都有 conversations.create/history/stream。异步使用 await、async with、async for。Notebook 渲染适配器当前仅提供同步接口。
+
+## 一键任务、文件、产物
+
+只要最终答案：`client.runs.run_and_wait(...)`。流式展示：conversations.stream 或 notebook.stream。两者都会发送消息，不能为同一请求同时调用。
+
+File 上传、Skill 上传及 Vault 凭据配置属于资源准备阶段；可保存 ID 复用。用户附件通过 file_ids 附到当前 query。SDK 不自动把电脑上的其他文件上传。
+
+产物使用 artifacts.path_map 查询、artifacts.download 下载。映射是整个会话范围，按当前轮工具输出或文件路径关联；不可把历史产物自动算作当前轮。预览组件由前端根据 MIME 选择，HTML 使用隔离 sandbox，下载链接由后端鉴权代理。此版本未提供文件预览组件。
+
+## 生命周期
+
+SDK 不自动删除远端资源。保留 agent_id、session_id、skill_id、fileID、vault_id 供恢复及清理。Agent 删除会级联删除会话。Vault 和 Skill 可能被多个会话使用，确认归属后再删除。
+
+生产应用还需持久任务队列、用户与资源映射、限流、审计和幂等管理。SDK 未提供跨进程运行恢复和跨租户权限系统。

dmt_agent_api-0.3.0/docs/TESTING.md

@@ -0,0 +1,29 @@
+# 验证范围
+
+版本：0.1.0。验证日期：2026-11-11。
+
+## 真实 API
+
+使用独立测试资源调用 `https://api.dumate.cn/api/v1`：
+
+- Agent：列表、创建、详情、删除。
+- Skill：列表、ZIP 上传、详情、ZIP 更新、releaseId 获取与会话挂载。
+- Vault：列表、创建、详情、删除；environment_variable 凭据创建、列表、详情、删除。
+- Session：创建、详情、历史、真实消息执行、资源点查询、删除。
+- SSE：连接后发消息，接收真实 message.updated、message.part.updated、message.part.delta、reasoning-summary、session.status、session.artifact.updated 等事件。
+- 最终答案：同步等待成功；异步调用返回 ASYNC_OK。
+- 产物：真实生成 TXT，查询路径映射、下载，内容包含 SDK artifact verified 及平台生成标识。
+- File：上传、详情、下载、更新、删除；同步与异步下载逐字节比对通过。上传响应字段为 fileID。
+- 测试 Agent、Session、Skill、Vault、凭据及上传文件已清理。
+
+## 自动化测试
+
+21 项通过。包括请求字段、分页、同步与异步调用、SSE 分片/多字节/半帧、先订阅后发送、历史关联、超时不重复发送、错误脱敏、写操作不重试、下载原子提交、私网地址拒绝和产物 URL 刷新。
+
+这些协议与故障测试使用独立测试夹具；真实 API 验证范围列于上节。
+
+## 尚未实测
+
+Skill URL 导入/更新、static_bearer 与 MCP OAuth 的真实授权链路、外部 MCP 工具运行、自定义工具完整回传流程、Agent 版本更新、生产规模并发、断网后应用级恢复与跨租户权限控制。
+
+SDK 为初始版本。上述能力中，平台接口封装可用范围见 API 索引；未实测项仍需接入方在目标环境验收。SDK 不提供持久任务队列、前端组件或自动断点续跑。

dmt_agent_api-0.3.0/examples/async_stream.py

@@ -0,0 +1,18 @@
+import asyncio
+import os
+from dumate import AsyncDuMate
+
+async def main():
+    async with AsyncDuMate() as client:
+        session = await client.sessions.create(agent_id=os.environ["DUMATE_AGENT_ID"])
+        async with client.sessions.stream(session["id"], message="你好") as events:
+            async for event in events:
+                print(event.type)
+                if event.type == "session.idle" or (
+                    event.type == "session.status"
+                    and event.properties.get("status", {}).get("type") == "idle"
+                ):
+                    break
+
+if __name__ == "__main__":
+    asyncio.run(main())

dmt_agent_api-0.3.0/examples/quickstart.py

@@ -0,0 +1,10 @@
+import os
+from dumate import DuMate
+
+if __name__ == "__main__":
+    with DuMate() as client:
+        session = client.sessions.create(agent_id=os.environ["DUMATE_AGENT_ID"])
+        result = client.runs.run_and_wait(
+            session_id=session["id"], message="介绍你能完成的工作", timeout=180,
+        )
+        print(result.output_text)

dmt_agent_api-0.3.0/examples/skills_and_vaults.py

@@ -0,0 +1,27 @@
+import os
+from dumate import DuMate
+
+if __name__ == "__main__":
+    with DuMate() as client:
+        skill = client.skills.upload(os.environ["DUMATE_SKILL_ZIP"])
+        vault = client.vaults.create(name="应用凭据")
+        client.vaults.credentials(vault["id"]).create(
+            name="业务令牌",
+            auth={
+                "type": "environment_variable",
+                "secretName": "BUSINESS_TOKEN",
+                "secretValue": os.environ["BUSINESS_TOKEN"],
+                "networking": {
+                    "type": "limited",
+                    "allowedHosts": [os.environ["BUSINESS_HOST"]],
+                },
+            },
+        )
+        session = client.sessions.create(
+            agent_id=os.environ["DUMATE_AGENT_ID"],
+            skills=[client.skills.mount(skill["id"])],
+            vault_ids=[vault["id"]],
+        )
+        print("session_id:", session["id"])
+        print("skill_id:", skill["id"])
+        print("vault_id:", vault["id"])

dmt_agent_api-0.3.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dmt-agent-api"
+version = "0.3.0"
+description = "DMT Agent API Python SDK for DuMate"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+notebook = ["ipython>=8"]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dumate = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

dmt_agent_api-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+