Metadata-Version: 2.4
Name: dingyi-agno
Version: 0.2.2
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: agno<3,>=2.9
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.20
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"

# dingyi-agno

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

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

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

## 配置

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

## 组件包开发

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

```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` 启动 Renderer 本地预览；`pack` 会自动安装前端依赖、类型检查并构建 Renderer。
打包结果默认写入 `business-assistant/dist/business-assistant-1.0.0.zip`。打包器会排除
虚拟环境、Git、缓存、构建目录和 `.env`，并执行与平台上传阶段一致的 Manifest、版本、
依赖、工厂模块、循环依赖及 ZIP 安全校验。

SDK 不会获得模型供应商密钥。模型选择、组件绑定和供应商鉴权始终由鼎医AI中台处理。

## 兼容范围

当前版本支持 Agno `2.9.x`。中台内置运行时为 `2.9.0`，并已使用
Agno `2.9.0` 验证共享 `ai` schema 下的 Agent、Team、Workflow、Session、Run、
Trace 和 Span。升级到新的 Agno 次版本前，应先对比官方表结构并执行跨版本冒烟测试。
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`。
`0.2.2` 仍兼容旧的 `DINGYI_SERVICE_TOKEN`、`DINGYI_DATABASE_URL`、
`DINGYI_DB_SCHEMA` 和 `DINGYI_REQUEST_TIMEOUT`，新项目应统一使用
`DINGYI_PLATFORM_*` 命名。

## Workflow 接入方式

普通 Workflow 直接通过 AgentOS 的原生 Workflow WebSocket 执行。需要自然语言理解、
续聊和历史上下文时，为 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 保留为内部渠道。
在仓库根目录执行：

```bash
# 公开 PyPI
npm run publish:sdk:pypi

# 公司 GitLab Package Registry
npm run publish:sdk
```

公开 PyPI 的 Token 配置、版本升级、发布和验证流程见
[`docs/sdk-public-pypi.md`](../../docs/sdk-public-pypi.md)。内部 GitLab 发布方式见
[`docs/sdk-gitlab-registry.md`](../../docs/sdk-gitlab-registry.md)。同一个版本不能覆盖发布，
每次变更必须同时更新 `pyproject.toml` 和 `dingyi_agno.__version__`。
