dingyi-agno

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

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 so they can be used by the platform's embedded chat:

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

Existing interfaces are preserved. Pass enable_agui=False only when the service intentionally does not expose an interactive chat surface.

外部组件仍然是标准 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

组件包开发

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

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）和 Renderer 预览。它会加载本地组件工厂、执行真实 Renderer Action，并通过与线上相同的 SSE 协议提供聊天接口；前端可从 VITE_DINGYI_LOCAL_RUNTIME_URL 调用运行时。没有模型配置时可用 --mock-model，需要本地会话与运行记录时加 --persist。例如：

dingyi-agno component dev ./business-assistant --mock-model --persist

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 与 .env 读取开发者显式配置的模型和资源。不要将这些文件打进组件包。

兼容范围

当前 SDK 0.3.x 支持 Agno >=3.0,<3.1，中台内置运行时固定为 Agno 3.0.0。 共享 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 的原生 Workflow WebSocket 执行。需要自然语言理解、 续聊和历史上下文时，为 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 的 Token 配置、版本升级、发布和验证流程见 docs/sdk-public-pypi.md。内部 GitLab 发布方式见 docs/sdk-gitlab-registry.md。同一个版本不能覆盖发布， 每次变更必须同时更新 pyproject.toml 和 dingyi_agno.__version__。