Metadata-Version: 2.4
Name: dingyi-agno
Version: 0.5.0
Summary: Python integration helpers for Dingyi AI Platform and Agno
Author: Dingyi AI Platform
License-Expression: LicenseRef-Proprietary
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: ag-ui-protocol<0.2,>=0.1.19
Requires-Dist: agno<3.1,>=3.0.6
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.28
Requires-Dist: openai<3,>=2.8
Requires-Dist: openinference-instrumentation-agno<0.2,>=0.1.38
Requires-Dist: packaging<26,>=24.2
Requires-Dist: python-multipart<1,>=0.0.26
Requires-Dist: sqlalchemy<3,>=2
Requires-Dist: tomli<3,>=2; python_version < "3.11"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "postgres"
Provides-Extra: dev
Requires-Dist: keyring<26,>=25; extra == "dev"
Requires-Dist: mcp<3,>=2.1; extra == "dev"
Requires-Dist: fastmcp<5,>=4; extra == "dev"
Requires-Dist: python-dotenv<2,>=1; extra == "dev"
Requires-Dist: uvicorn[standard]<1,>=0.35; extra == "dev"
Requires-Dist: watchfiles<2,>=1; extra == "dev"

# dingyi-agno

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

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

```python
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:

```text
/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，不会再创建第二个连接池。

## 配置

```text
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
```

运行诊断：

```bash
dingyi-agno doctor
```

## 组件包开发

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

```bash
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：

```python
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`。

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

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

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

```bash
# 推荐：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`：

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

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

```python
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、入口、版本和制品摘要由
平台自动派生，不需要重复维护。

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

```bash
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`。

```bash
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 归属

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

### 本地高级配置

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

```toml
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.6,<3.1`，中台内置运行时固定为 Agno `3.0.6`。
共享 `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()`：

```python
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`：

```python
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 仅保留为可选内部镜像。
在仓库根目录执行：

```bash
# 无需凭据：先完成测试、构建、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`](../../docs/platform-guide.md#16-sdk-发布)。同一个版本不能覆盖发布，
每次变更必须同时更新 `pyproject.toml` 和 `dingyi_agno.__version__`。
