dingyi-agno

dingyi-agno 是鼎医AI中台面向 Agno Python 项目的接入包。推荐使用 PlatformRuntime：外部项目只声明组件 ID，模型网关、共享 PostgreSQL、官方 tracing 和 AgentOS 资源注册由 SDK 自动处理。

图片与附件存储

运行时使用 Agno 原生 media_storage。图片、音频和文件内容保存在文件存储中， 会话数据库仅保存 media_reference 和文件元数据；恢复模型历史时由 Agno 按引用读取。 保留 store_media=True，设置为 False 会丢弃媒体历史，并不表示改用文件存储。

• 中台使用 AGNO_ADMIN_MEDIA_DIR，默认 data/media。不同 Runtime Generation 共享此目录。
• 独立 PlatformRuntime 使用 DINGYI_MEDIA_DIR，默认当前工作目录的 data/media。
• component dev 使用组件目录下的 .dingyi/media；内存模式不配置持久化媒体。
• 中台历史预览经过原有会话鉴权；SDK 独立页面使用 Agno 原生会话媒体接口。
• PostgreSQL/本地 SQLite 的持久化序列化同时处理事件中的内联媒体；存储失败会阻止该写入，避免回退将 Base64 保存到数据库。

文件目录必须和数据库一起备份。当前采用本地文件存储，容器需要持久化挂载同一路径， 多主机部署需要先统一共享文件存储或接入 Agno 对象存储后端。 数据库中已有的外接 AgentOS 数据，由对应运行环境配置媒体存储与迁移。 附件可保存和下载不代表当前模型支持解析所有文件格式。

pip install "dingyi-agno[postgres]"
# 或
uv add "dingyi-agno[postgres]"

from dingyi_agno import PlatformRuntime

platform = PlatformRuntime.from_env()

agent = platform.agent(
    id="customer-service",
    name="客服助手",
    instructions=["使用中文回答"],
    tools=[...],
)

team = platform.team(
    id="customer-service-team",
    name="客服团队",
    members=[agent],
    mode="route",
)

app = platform.agentos(agents=[agent], teams=[team]).get_app()

PlatformRuntime.agentos() automatically exposes every Agent and Team through standard AG-UI routes for third-party AG-UI clients and browser-side dynamic tools:

/agui/agents/{agent_id}/agui
/agui/teams/{team_id}/agui

The platform's own Chat Gateway uses the AgentOS Runs API by default. Existing interfaces are preserved. Pass enable_agui=False when the service does not need external AG-UI compatibility.

外部组件仍然是标准 Agno Agent、Team 和 Workflow 实例，因此所有原生参数都可以 继续通过 **kwargs 使用。PlatformRuntime 只接管基础设施参数，避免同一个组件 ID 被模型、数据库和 AgentOS 重复配置。

已有服务已经创建 PostgresDb 时，可以通过 PlatformRuntime.from_env(db=shared_db) 直接复用；SDK 仍会在这个数据库上启用 tracing，不会再创建第二个连接池。

配置

DINGYI_PLATFORM_URL=http://127.0.0.1:8000
DINGYI_PLATFORM_SERVICE_TOKEN=管理端生成的模型网关令牌
DINGYI_PLATFORM_DATABASE_URL=postgresql+psycopg://user:password@host/database
DINGYI_PLATFORM_DB_SCHEMA=ai
DINGYI_PLATFORM_REQUEST_TIMEOUT=15

运行诊断：

dingyi-agno doctor

组件包开发

本地开发与上传使用同一份组件代码和 Manifest。首次运行会打开中台登录页，授权仅限模型调用；令牌保存在 macOS Keychain 或 Windows Credential Manager，管理员密码不会写入磁盘：

pip install "dingyi-agno[dev]"
export DINGYI_PLATFORM_URL=http://127.0.0.1:8000  # Windows 可使用 set 或 PowerShell $env:
dingyi-agno component dev

ChatUI、组件运行时和中台模型网关由 SDK 自动连接，之后直接执行 dingyi-agno component pack 上传，无需修改组件代码或配置。

组件工厂建议显式标注 SDK 上下文和 Agno 返回类型。SDK 已包含 py.typed，因此 VS Code （Pylance/Pyright）和 PyCharm 可以直接查看类型、跳转源码并补全 Agno API：

from agno.agent import Agent
from dingyi_agno import ComponentContext


def create_component(ctx: ComponentContext) -> Agent:
    return ctx.agent(
        name="业务助手",
        instructions=["使用中文回答用户问题。"],
        markdown=True,
    )

如果编辑器仍显示 Any，请将解释器切换到安装了当前 SDK 的环境（推荐执行 python -m pip install -e sdk/python），并确认没有把工厂参数写成 ctx: Any。

使用脚手架创建一个可直接上传到中台的组件工程：

dingyi-agno component init ./business-assistant \
  --name "业务助手" \
  --component-id business-agent \
  --component-name "业务 Agent"

默认生成 Agent；也可以通过 --type team 或 --type workflow 生成对应的最小可运行模板。 需要自定义消息内容区时，选择团队熟悉的 Renderer 框架：

# 推荐：React + TSX
dingyi-agno component init ./business-assistant --renderer react

# Vue 3 SFC
dingyi-agno component init ./business-assistant-vue --renderer vue

# 零框架 DOM API
dingyi-agno component init ./business-assistant-native --renderer native

省略 --renderer 的值时默认使用 React。开发者只编辑普通的 ui/src/Renderer.* 组件和 renderer.css；@dingyi-tech/chat-renderer-sdk 的 CLI 会在内存中生成协议入口，并负责 Shadow DOM 样式注入和单文件 ESM 构建。组件工程不需要隐藏适配目录或 vite.config.ts。

脚手架当前生成 @dingyi-tech/chat-renderer-sdk@^0.2.1 依赖。手工创建 UI 工程时可以直接 从 npm 安装；完整的 React、Vue、Native 接入方式见前端 SDK 的 README.md：

npm install @dingyi-tech/chat-renderer-sdk@^0.2.1

服务端交互使用装饰器，输入模型会自动推断：

from pydantic import BaseModel

class FilterInput(BaseModel):
    region: str

@ctx.ui.action("dashboard.filter")
def filter_dashboard(values: FilterInput):
    return {"payload": {"title": "业务看板", "region": values.region}}

yield ctx.ui.render({"title": "业务看板", "region": "全部区域"})

Manifest 只写 "renderer": "react"（或 vue、native）。Action、入口、版本和制品摘要由 平台自动派生，不需要重复维护。

完成业务代码后，在本地校验并打包：

dingyi-agno component validate ./business-assistant
dingyi-agno component dev ./business-assistant
dingyi-agno component pack ./business-assistant

dev 在 127.0.0.1:8001 启动 SDK 内置的完整 ChatUI 和本地运行时。ChatUI 与中台复用同一个聊天工作区，但固定绑定当前开发组件。首次运行需要在浏览器登录中台，之后 SDK 会自动刷新仅限模型调用的授权。Python 与 Renderer 源码会自动重载；会话默认保存在 SDK 管理的 .dingyi/local.db。

dingyi-agno component dev ./business-assistant

组件包包含多个组件时，Local ChatUI 会显示 Agent、Team 和 Workflow 选择器。--component <id> 或 dingyi-component.dev.toml 中的 [preview] component = "<id>" 只用于设置初始选中项，不是启动必需配置。临时调试且不希望保存会话时使用 --memory；使用 --no-open 可禁止自动打开 ChatUI（首次授权仍会打开浏览器）。只有当前包声明了自定义 Renderer 时才需要 Node.js，CLI 会按锁文件自动安装依赖并持续构建。

pack 会自动安装前端依赖、类型检查并构建 Renderer。 如果 UI 目录存在锁文件，SDK 会严格使用对应的 pnpm、npm 或 yarn 可复现安装； package.json 和锁文件未变化时会复用 node_modules，不会在每次预览或打包时重复安装。 打包结果默认写入 business-assistant/dist/business-assistant-1.0.0.zip。打包器会排除 虚拟环境、Git、缓存、构建目录和 .env，并执行与平台上传阶段一致的 Manifest、版本、 依赖、工厂模块、循环依赖及 ZIP 安全校验。

生产环境中 SDK 不会获得模型供应商密钥。模型选择、组件绑定和供应商鉴权由鼎医AI中台处理；本地开发同样通过浏览器授权使用中台模型，默认不需要 dingyi-component.dev.toml。

Renderer 归属

SDK 0.5.1 起，中台托管的 Action 可以声明关键字参数 renderer_context， 读取中台核验后的来源身份及当前持久化 payload。它与浏览器传入的业务 input 分开传递：

@ctx.ui.action("answer.evidence")
def load_evidence(values: EvidenceInput, *, renderer_context: dict):
    saved = renderer_context["payload"]
    # 按 saved 中的证据白名单读取；不可使用 input 自报的会话或源码位置授权。
    return read_authorized_evidence(saved, values.evidenceId)

上下文包括 sessionId、runId、messageId、componentId、componentType、 agentosKey、rendererRevision 和 payload。未声明此参数的原有 Action 保持原输入契约； 声明后如果宿主没有提供受信上下文，SDK 会拒绝调用。当前独立 component dev 不提供该上下文， 此类 Action 应在本地中台的托管 Runtime 验证。服务查询应使用异步客户端或在线程中执行，避免阻塞聊天。

Renderer 随组件包及其组件确定性注册和发布，本地开发、打包与中台运行使用同一份 Renderer Snapshot。Studio 自建 Agent、Team、Workflow 当前使用平台默认 ChatUI，不从其他 组件包选择 Renderer；需要特殊 UI 时，应在对应组件包中开发并随包发布。

本地高级配置

dingyi-component.dev.toml 只用于开发机覆盖，不会打进组件包。可配置预览组件、中台模型 Profile、本地 MCP、从环境变量读取的 Secret、Knowledge/Skill 工厂和 workspace 包：

version = 1

[preview]
component = "business-agent"

[runtime]
model_profile_key = "qwen-development" # 可选；省略时使用组件现有绑定或平台默认模型

[secrets]
CRM_TOKEN = "${CRM_TOKEN}"

[mcp.crm]
transport = "streamable-http"
url = "${CRM_MCP_URL}"

[bindings.business-agent]
mcp = ["crm"]
secrets = ["CRM_TOKEN"]

本地开发不会读取模型供应商 API Key；模型始终通过浏览器授权访问鼎医中台模型网关。

兼容范围

当前 SDK 0.5.x 支持 Agno >=3.0.9,<3.1，中台内置运行时固定为 Agno 3.0.9。 共享 ai schema 使用 Agno 3 的独立 agno_sessions 与 agno_runs 表，并已验证 Agent、Team、Workflow、Session、Run、Trace 和 Span 的真实读写。升级 Agno 前应先执行 官方 MigrationManager、核对表结构，并完成跨版本运行回归。 PostgreSQL 项目安装时使用 uv pip install 'dingyi-agno[postgres]'，SDK 会同时安装模型 网关和官方 tracing 所需依赖。

Workflow 通常由内部 Agent 或 Team 发起模型调用。如果希望按 Workflow 统一绑定模型， 可将内部执行器的模型设为 platform.workflow_model("workflow-id")；如果希望每个执行器 独立绑定模型，则继续使用 agent_model() 或 team_model()。

模型供应商密钥只保留在中台管理端，外部项目只需要服务令牌和共享数据库的最小权限账号。 DINGYI_PLATFORM_DB_SCHEMA 必须与中台 AgentOS 使用的官方 schema 一致，默认是 ai。 SDK 仅识别 DINGYI_PLATFORM_* 环境变量，避免平台配置与业务应用自身的数据库或模型 环境变量发生歧义。

Workflow 接入方式

普通 Workflow 直接通过 AgentOS 的原生 Runs SSE 执行。需要自然语言理解、 续聊和历史上下文时，为 Workflow 配置 Agno 原生 WorkflowAgent；这两种方式的 Run、 Step 和内部执行器都由 Agno 原生表记录。

只有业务上确实需要“Agent 把 Workflow 当工具调用”时，才使用 workflow_tool()：

workflow = platform.workflow(id="report-workflow", steps=[...])
workflow_tool = platform.workflow_tool(
    workflow,
    parent_component_id="report-agent",
    description="生成完整业务报告",
)
agent = platform.agent(
    id="report-agent",
    tools=[workflow_tool],
    instructions=["需要生成报告时调用 Workflow 工具"],
)

SDK 会为子 Workflow 创建独立 Run 和 Session，并把 Agent 工具调用与子 Workflow 的执行图 关联起来。workflow_tool() 会返回暂停需求，但不会自动把子 Workflow 的 HITL 暂停传播成 外层 Agent 的暂停；包含审批或用户输入的流程应优先使用原生 Workflow/WorkflowAgent。

高级 API

已有项目可以继续使用 PlatformClient：

from dingyi_agno import PlatformClient

platform = PlatformClient.from_env()
db = platform.enable_observability()
agent_model = platform.agent_model("customer-service")

PlatformClient 适合需要完全手动控制构造过程的场景；新项目优先使用 PlatformRuntime。

发布

公开 PyPI 是外部开发者的安装渠道，不需要 GitLab 账号或 Package Registry Token。公司 GitLab Package Registry 仅保留为可选内部镜像。 在仓库根目录执行：

# 无需凭据：先完成测试、构建、Twine 检查和干净环境安装验证
npm run publish:sdk -- --dry-run

# 公开 PyPI
npm run publish:sdk

# 可选的公司 GitLab Package Registry
npm run publish:sdk:gitlab

公开 PyPI 和内部 GitLab 的 Token 配置、版本升级、发布和验证流程见 docs/platform-guide.md。同一个版本不能覆盖发布， 每次变更必须同时更新 pyproject.toml 和 dingyi_agno.__version__。

组件发布准备任务（SDK 0.5.2）

组件 manifest 可声明 preparationTasks，每项包含 id、title、check、run，可选 required（默认 true）和 timeoutSeconds（默认 1800，上限 7200）。入口必须是包内的 module:function。无声明的组件沿用原发布流程。

入口接收 PreparationContext，使用最终 config、平台 db、明确绑定的 secrets，通过 report(summary, progress) 上报进度，定期检查 is_cancelled()，返回 PreparationResult(ready, summary, details)。同步或异步函数均支持；不在工厂、聊天工具或上传校验中执行准备动作。

检查必须只读且轻量；执行应幂等、可重试，提交结果前检查取消。平台用独立进程执行任务并管理超时、状态和取消；发布前检查所有必需任务，缺失时执行并复查，失败不会切换旧部署。管理员可在绑定配置下检查或主动执行更新。配置/资源指纹变化会失效已保存状态。