PraisonAI Deploy 实战指南一条命令将 agents.yaml 部署为 API、Docker 容器与云服务AWS / Azure / GCP【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAIPraisonAI 生态中praisonai-deploy是负责把写好的 Agent 真正跑起来的部署工具链它从一份agents.yaml出发统一支持本地 API 服务器、Docker 容器以及 AWS / Azure / GCP 三大云平台的部署编排并提供doctor体检、plan预演、status查询、destroy销毁的完整生命周期管理。读完本文你将掌握praisonai deploy全量命令的用法、deploy配置段的字段语义、Python API 的调用方式以及从 YAML 到生产环境的端到端部署路径。一、praisonai-deploy 的定位与整体架构根据 src/praisonai-deploy/README.md 的说明praisonai-deploy是 PraisonAI 的部署工具包Deployment tooling覆盖API 服务器、Docker 镜像、云平台AWS、Azure、GCP三种部署形态由praisonai主包中的部署能力独立抽取而来见 pyproject.toml 中的描述 extracted from the praisonai wrapper。从源码结构看包内模块分工清晰main.py —Deploy统一门面类按部署类型分发deploy / plan / doctor / status / destroyschema.py —agents.yaml中deploy段的解析与校验models.py — 基于 Pydantic 的配置与结果模型APIConfig、DockerConfig、CloudConfig、DeployResult等api.py — 生成并启动 Flask API 服务器docker.py — 生成 Dockerfile、构建/运行/推送镜像、容器状态与销毁doctor.py — 部署前环境体检providers/ — 云平台提供者AWS ECS、Azure Container Apps、GCP Cloud Run 等通过可插拔注册表管理。Deploy类按DeployTypeapi/docker/cloud三种枚举值见 models.py分发到_deploy_api/_deploy_docker/_deploy_cloud其中云部署通过get_provider(self.config.cloud)拿到具体提供者实例后执行整体是一套统一入口 策略分发的架构。二、安装与运行环境2.1 安装方式README 提供了三种安装口径pip install praisonai-deploy pip install praisonai-deploy[api] # 附带 Flask API 服务器生成能力 pip install praisonai[deploy] # 完整 umbrella 包含 wrapper shims基础包仅包含编排能力生成、构建、plan、doctor[api]额外安装 Flask 相关依赖。查看 pyproject.toml 可知apiextra 声明了flask3.0.0与flask-cors4.0.0praisonai[deploy]用于在完整 umbrella 安装中启用部署能力并保持praisonai.deploy.*旧导入路径可用。环境约束requires-python 3.10,3.15包的核心依赖为praisonaiagents1.6.126、rich13.7、typer0.12.0、click8.4.2、PyYAML6.0、pydantic2.0。2.2 宿主 CLI 依赖重要前提README 明确本包不内嵌任何云 SDK无 boto3、无 Azure SDK云部署直接调用宿主机器上的 CLI 工具CLI用途docker构建与运行容器、Compose 栈awsAWS ECS 部署azAzure Container Apps 部署gcloudGCP Cloud Run 部署因此部署前需保证对应 CLI 已安装、已登录/已配置凭证否则deploy会失败——这正是doctor命令存在的意义详见第八节。2.3 运行时依赖生成的服务器README 特别强调了一个容易踩坑的细节由 deploy 生成的 API 服务器和 Docker 镜像在运行时会安装完整的praisonaifull wrapper因为它们嵌入from praisonai import PraisonAI来执行 Agent。deploy 包本身只负责编排generate、build、plan、doctor容器内部需要pip install praisonai flask gunicorn。这一点在 docker.py 生成的 Dockerfile 中也可以印证RUN pip install --no-cache-dir praisonai flask flask-cors gunicorn。三、CLI 命令全览3.1 入口命令在安装了完整 umbrellapraisonai的环境下部署命令挂在主 CLI 之下praisonai deploy run --file agents.yaml praisonai deploy doctor --all praisonai deploy validate --file agents.yaml praisonai deploy plan --file agents.yaml praisonai deploy status --file agents.yaml praisonai deploy destroy --file agents.yaml --yes praisonai deploy docker agents.yaml --tag v1 praisonai deploy aws agents.yaml --region us-east-1独立的控制台脚本不依赖 umbrellapraisonai-deploy --help该入口在 pyproject.toml 中声明为praisonai-deploy praisonai_deploy.__main__:main底层是基于 Typer 构建的命令组见 cli/commands/deploy.py。3.2 子命令与参数速查结合 cli/commands/deploy.py 源码命令组包含以下成员命令作用关键参数run按agents.yaml执行部署--file/-f默认agents.yaml、--typeapi/docker/cloud、--provider、--background、--jsondoctor检查部署就绪度--file/-f、--provider、--all、--verbose/-v、--jsoninit生成带 deploy 配置的示例agents.yaml--file/-f默认agents.yaml、--type默认api、--providervalidate校验 deploy 配置--file/-f、--jsonplan预演部署计划不实际执行--file/-f、--jsonstatus查询当前部署状态--file/-f、--json、--verbose/-vdestroy销毁/删除部署--file/-f、--yes/-y、--force、--jsonapi本地 API 部署run --type api别名位置参数文件、--background、--jsoncloud云部署run --type cloud别名位置参数文件、--provider必填dockerDocker 容器部署位置参数文件、--tag/-taws部署到 AWS位置参数文件、--region/-razure部署到 Azure位置参数文件、--resource-group/-ggcp部署到 Google Cloud位置参数文件、--project/-pfly部署到 Fly.io位置参数文件、--region/-rrailway部署到 Railway位置参数文件render部署到 Render位置参数文件compose up/down启动/停止 agents API Postgres Compose 栈--file/-f、--stack-dir、--foreground、--volumes/-v、--jsoncreate从 starter 模板脚手架化部署项目--template/-t必填、--dir/-d默认.helmhelm upgrade的薄封装--chartgateway 或 agents-api、--release/-r、--namespace/-n、--install/--no-install所有子命令都支持--json结构化输出便于脚本与 CI 集成。四、agents.yaml 中的 deploy 配置详解4.1 校验规则schema.py中的validate_agents_yaml(file_path)是解析入口规则如下见 schema.py文件必须存在且能通过yaml.safe_load解析必须包含deploy键否则返回None此时Deploy.from_yaml会抛出ValueError: No deploy configuration founddeploy段必须是mapping字典标量或列表如deploy: docker会被判定为格式错误deploy段只允许type、api、docker、cloud、agents五个键未知键直接报错防止dockerr:这类拼写错误被静默忽略后以默认值部署type必填取值只能是api、docker、cloud。4.2 三种部署类型的配置模型所有配置字段均由 Pydantic 模型定义见 models.py字段与默认值如下APIConfigtype: api字段默认值说明host127.0.0.1服务器监听地址port8005服务器端口workers1工作进程数cors_enabledtrue是否启用 CORSauth_enabledtrue是否启用认证auth_tokennull认证令牌未设置时自动生成reloadfalse开发模式自动重载DockerConfigtype: docker字段默认值说明image_namepraisonai-app镜像名taglatest镜像标签base_imagepython:3.11-slim基础镜像expose[8005]暴露端口列表registrynull镜像仓库 URL配置后 tag 会带仓库前缀pushfalse构建后是否推送仓库build_argsnull额外 Docker 构建参数CloudConfigtype: cloud字段默认值说明provider必填aws/azure/gcp也支持fly/railway/renderregion必填部署区域service_name必填服务/应用名imagenull容器镜像 URLcpu256CPU 分配memory512内存MBmin_instances1最小实例数max_instances10最大实例数env_varsnull环境变量字典cluster_namenullAWS ECS 集群名task_definitionnullAWS 任务定义resource_groupnullAzure 资源组subscription_idnullAzure 订阅 IDproject_idnullGCP 项目 ID4.3 三种类型的示例配置init命令生成的模板与 examples/deploy/ 下的真实示例完全对应API 类型参考 agents-api.yamldeploy: type: api api: host: 0.0.0.0 port: 8005 workers: 2 cors_enabled: true auth_enabled: false reload: falseDocker 类型参考 agents-docker.yamldeploy: type: docker docker: image_name: praisonai-analyst tag: v1.0.0 base_image: python:3.11-slim expose: - 8005 registry: ghcr.io/myorg push: false # 可选配置容器内生成的服务端 api: host: 0.0.0.0 port: 8005 auth_enabled: true注意 Docker 类型下可选的api兄弟段用于配置生成的服务端host/port/auth/cors语义与type: api一致见 schema.py。Cloud 类型AWS参考 agents-aws.yamldeploy: type: cloud cloud: provider: aws region: us-east-1 service_name: praisonai-service cpu: 256 memory: 512 min_instances: 1 max_instances: 10 # image: your-registry/praisonai-app:latest # cluster_name: praisonai-clusterAzure 示例额外需要resource_group与subscription_idGCP 示例需要project_id见 agents-azure.yaml 与 agents-gcp.yaml。五、Python API 使用README 给出了最简用法from praisonai_deploy import Deploy deploy Deploy.from_yaml(agents.yaml) result deploy.deploy() status deploy.status()Deploy支持两种构造方式见 main.py# 方式一从 YAML推荐 deploy Deploy.from_yaml(agents.yaml) # 方式二编程式构造 from praisonai_deploy import Deploy, DeployConfig, DeployType config DeployConfig(typeDeployType.API) deploy Deploy(config, agents_fileagents.yaml) result deploy.deploy()实例方法一览方法说明deploy(backgroundFalse)按配置类型执行部署返回DeployResultplan()返回部署计划字典不实际执行API 返回 host/port/workersDocker 返回镜像/端口Cloud 返回提供者计划doctor()按类型执行体检API 检查本地端口与 YAMLDocker 追加 Docker 可用性检查Cloud 交给提供者未知类型执行全量检查status()返回DeployStatusAPI 类型通过探测端口判断运行状态ServiceState.RUNNING/STOPPED/UNKNOWNDocker 通过docker inspectCloud 通过提供者查询destroy(forceFalse)销毁部署并返回DestroyResultAPI 跨平台查找并终止占用端口的进程Docker 停止并移除容器force时同时删除镜像Cloud 交给提供者praisonai_deploy包对外还暴露了get_deployment_status(agents_file...)工具函数返回state/url/message/service_name/provider/healthy字典便于 MCP 与工具集成见init.py。关于旧路径兼容README 明确praisonai.deploy.*旧导入路径在安装praisonaiwrapper 后仍然可用迁移期无需改动存量代码。六、API 服务器部署实战6.1 工作流程type: api的部署链路_deploy_api→start_api_server见 api.pygenerate_api_server_code()生成一个完整的 Flask 应用源码源码写入每次调用独立的私有临时目录tempfile.mkdtemp(prefixpraisonai_api_)权限 0700防止共享主机上其他用户预创建或替换生成文件自动尝试pip install flask flask-cors使用将运行服务器的同一解释器继承父进程环境如OPENAI_API_KEY按background标志以子进程方式前台或后台启动。6.2 生成的服务器端点生成的 Flask 应用见 api.py提供三个端点GET /health— 健康检查返回{status: ok, service: praisonai-api}POST /chat— 接收{message: ...}通过importlib.import_module(praisonai).run(agents_file, cli_config{topic: message})执行 Agent 并返回响应缺少message返回 400执行异常返回 500GET /agents— 返回可用 Agent 列表与agent_file。6.3 认证与 CORS生成的服务器内置 Bearer Token 认证auth_enabled: true时若未配置auth_token启动时会用secrets.token_urlsafe(32)自动生成令牌并打印到 stderr认证采用secrets.compare_digest常量时间比较防时序攻击运行时可用环境变量覆盖配置而无需重新生成文件PRAISONAI_API_AUTH非disabled即启用与PRAISONAI_API_TOKEN方便运维轮换令牌cors_enabled控制是否注入CORS(app)。部署 API 时可参考 agents-api.yaml 将host设为0.0.0.0以对外提供服务。七、Docker 部署实战7.1 生成的 Dockerfiletype: docker的部署链路_deploy_docker见 main.py依次执行生成并保存 Dockerfile → 生成 API 服务端代码 → 准备构建上下文 → 构建镜像 →可选推送 → 运行容器替换同名旧容器。生成的 Dockerfile见 docker.py包含几个值得注意的工程细节COPY只复制agents.yaml与生成的api_server.py使用 basename使绝对宿主路径在构建上下文中可用安装praisonai flask flask-cors gunicorn对应 README 的运行时依赖说明为每个expose端口生成EXPOSE指令内置HEALTHCHECK每 30s 探测/health启动命令使用gunicorn 且--timeout 120——源码注释解释了原因Agent 的 LLM 工作负载冷启动导入 首次模型往返经常超过 gunicorn 默认的 30s导致首个/chat请求中途 worker 被 SIGKILL。DEFAULT_GUNICORN_TIMEOUT 120是特意调大的。7.2 环境变量透传运行容器时宿主环境中以下变量会被透传进容器见 docker.pyOPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、PRAISONAI_API_TOKEN。另外当 API 配置了auth_enabled: false时会注入PRAISONAI_API_AUTHdisabled到容器环境。7.3 容器命名与生命周期容器名由{image_name}-{tag}派生非法字符如team/app中的/会被替换为-docker_container_namedocker.py保证符合 Docker 命名规范。deploy docker agents.yaml --tag v1可覆盖镜像 tagstatus通过docker inspect映射running/exited/created/dead到ServiceStatedestroy先docker stop再docker rm--force时追加docker rmi删除镜像。完整可运行的 Docker 示例见 agents-docker.yaml。八、云平台部署AWS / Azure / GCP8.1 提供者注册表与可扩展性云提供者通过注册表管理见 providers/_registry.py内置aws、azure、gcp、fly、railway、render六个提供者懒加载同时支持通过praisonai.deploy.providersentry-point 组注册第三方提供者。因此models.CloudProvider枚举只代表内置提供者真正的校验权威是list_cloud_providers()——这正是coerce_cloud_provider先查枚举、再查注册表的原因见 models.py。三个 provider 的 entry-point 声明可见 pyproject.toml。8.2 各提供者行为对比README 原文Provider行为AWS ECS仅更新路径全新部署greenfield需要预先存在的 VPC/服务配置AzureContainer Apps创建/更新GCPCloud Run创建或更新8.3 AWS ECSFargateAWSProvider 基于 ECS Fargate 实现plan()输出四步计划创建 ECS 集群如不存在→ 注册任务定义 → 创建/更新 ECS 服务 → 等待服务稳定deploy()依次执行aws ecs create-cluster、aws ecs register-task-definitionawsvpc网络模式 FARGATE兼容性容器端口 8005随后尝试aws ecs update-service若服务不存在则返回失败提示需手工预置 VPC/子网/安全组后走更新路径——与 README 的 Update-only path 一致status()通过describe-services将ACTIVE/DRAINING/INACTIVE映射到服务状态destroy(force)先将 desired count 置 0再delete-serviceforce时追加delete-cluster。8.4 Azure Container AppsAzureProvider 面向 Container Apps若配置了subscription_id所有az命令追加--subscription参数确保资源落在指定订阅而非az默认订阅doctor()除 CLI 登录检查外还会校验subscription_id与当前环境订阅是否匹配不匹配会给出az account set修复建议防止资源静默创建到错误订阅并检查资源组是否存在。8.5 GCP Cloud RunGCPProvider 面向 Cloud Rundoctor()会检查run.googleapis.comAPI 是否已启用未启用给出gcloud services enable run.googleapis.com建议plan()中内存会格式化为512Mi形式镜像默认推导为gcr.io/{project_id}/{service_name}:latest支持创建或更新create-or-update。8.6 云部署前置检查执行praisonai deploy doctor --all会一次性检查Python 版本≥3.9、端口可用性、agents.yaml有效性、Docker 可用性以及三个云 CLI 的登录/配置状态详见 doctor.py 中的check_aws_cli/check_azure_cli/check_gcp_cli。部署前建议先跑一遍 doctor定位环境缺失项。九、doctor 体检与故障排查doctor是 deploy 的健康体检命令核心数据结构为DoctorCheckResultname/passed/message/fix_suggestion与聚合的DoctorReport提供total_checks / passed_checks / failed_checks / all_passed属性。检查项汇总如下检查通过条件失败修复建议Python Version版本 ≥ 3.9升级 PythonPort {port}端口未被占用停止占用进程或换端口agents.yaml文件存在且 deploy 配置有效praisonai deploy init生成或修复配置Dockerdocker --version可执行安装 DockerAWS CLIaws sts get-caller-identity成功aws configureAzure CLIaz account show成功且订阅匹配az login/az account setGCP CLIgcloud config get-value project有值gcloud initdoctor --all对应run_all_checks会执行本地 Docker 全部云 CLI 检查指定--provider只跑对应厂商检查。失败项自带fix_suggestion可直接按提示修复。十、进阶Compose、Helm 与 Starter 模板除了单一容器/单服务部署仓库还提供了生产级基础设施资产位于 src/praisonai-deploy/infra/注意这些资产不随 PyPI wheel 发布仅在 monorepo checkout 中可用。10.1 Docker Compose 生产栈infra/compose/agents-stack/ 提供agents API pgvector Postgres的生产级 Compose 栈见其 READMEpraisonai deploy compose up --file agents.yaml # 或显式指定栈目录 praisonai deploy compose up --stack-dir ./src/praisonai-deploy/infra/compose/agents-stack --file agents.yaml praisonai deploy compose down栈内两个服务apiFlask/health与/chat运行生成的api_server.py与postgrespgvector/pgvector:pg16支撑 memory/RAG 工作负载。CLI 会在compose up前于项目目录生成api_server.py。关键环境变量包括API_PORT默认 8005、POSTGRES_PASSWORD必填无默认值首次compose up时 CLI 会自动生成强密码写入项目.env与OPENAI_API_KEY透传给 API 容器。安全默认Postgres 默认只绑定127.0.0.1。10.2 Helm Chartinfra/helm/praisonai-agents-api/ 提供平台级 Helm ChartAPI Postgresvalues.yaml 支持配置 replicaCount、镜像仓库、agents.content内联 agents.yaml、auth默认启用支持existingSecret与PRAISONAI_API_TOKEN密钥名、pgvector Postgres含 8Gi 持久化以及 ingress。使用方式praisonai deploy helm --chart agents-api --release praisonai-api # 或直接 helm helm install praisonai-api ./src/praisonai-deploy/infra/helm/praisonai-agents-api \ --set auth.existingSecretpraisonai-api-authGatewayC9的 Helm Chart 位于 praisonai-bot/infra/helm/praisonai-gateway在完整 monorepo checkout 中会被自动发现见 infra/README.md。10.3 Starter 模板infra/starters/ 提供五种开箱即用的模板索引见 templates.yamldocker-api本地 APIcompose-ready、docker-composeAPI Postgres 栈、flyfly.toml agents.yaml、railwayrailway.json agents.yaml、renderrender.yaml agents.yaml。脚手架命令praisonai deploy create --template docker-compose --dir ./my-projectinfra 资产还支持环境变量覆盖默认查找路径PRAISONAI_INFRA_ROOT、PRAISONAI_COMPOSE_STACK、PRAISONAI_HELM_ROOT、PRAISONAI_STARTERS_ROOT见 infra/README.md。十一、Monorepo 开发与回归门禁作为 monorepo 中的独立包从源码目录可编辑安装cd src/praisonai-deploy uv pip install -e .pyproject.toml中[tool.uv.sources]将praisonaiagents指向本地../praisonai-agents保证开发时使用仓库内版本。README 列出的回归门禁scripts/check_c14_deploy_imports.sh— 检查 deploy 包的导入边界src/praisonai/tests/PRAISONAI_DEPLOY_MANIFEST.md— 包所有权边界说明src/praisonai-deploy/tests/— 包内单元测试覆盖 CLI 命令、schema 校验、Docker、doctor、provider 注册表等如 tests/test_cli.py 对 api/docker/aws 命令的 handler 调用验证。十二、端到端工作流速览将以上能力串起来一次典型部署的完整闭环如下# 1. 生成带 deploy 配置的 agents.yaml或手写 deploy 段 praisonai deploy init --type api --file agents.yaml # 2. 校验配置 praisonai deploy validate --file agents.yaml # 3. 体检环境 praisonai deploy doctor --all # 4. 预演部署计划 praisonai deploy plan --file agents.yaml # 5. 实际部署三选一本地 API / Docker / 云 praisonai deploy run --file agents.yaml --type api praisonai deploy docker agents.yaml --tag v1 praisonai deploy aws agents.yaml --region us-east-1 # 6. 查询状态 praisonai deploy status --file agents.yaml # 7. 销毁 praisonai deploy destroy --file agents.yaml --yes全程无需手写 Flask 应用、Dockerfile 或云资源模板——praisonai-deploy负责生成、编排与生命周期管理你只需要维护一份agents.yaml。若需深入源码建议从 main.py统一入口与 schema.py配置解析开始阅读。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PraisonAI Deploy 实战指南一条命令将 agents.yaml 部署为 API、Docker 容器与云服务AWS / Azure / GCP【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAIPraisonAI 生态中praisonai-deploy是负责把写好的 Agent 真正跑起来的部署工具链它从一份agents.yaml出发统一支持本地 API 服务器、Docker 容器以及 AWS / Azure / GCP 三大云平台的部署编排并提供doctor体检、plan预演、status查询、destroy销毁的完整生命周期管理。读完本文你将掌握praisonai deploy全量命令的用法、deploy配置段的字段语义、Python API 的调用方式以及从 YAML 到生产环境的端到端部署路径。一、praisonai-deploy 的定位与整体架构根据 src/praisonai-deploy/README.md 的说明praisonai-deploy是 PraisonAI 的部署工具包Deployment tooling覆盖API 服务器、Docker 镜像、云平台AWS、Azure、GCP三种部署形态由praisonai主包中的部署能力独立抽取而来见 pyproject.toml 中的描述 extracted from the praisonai wrapper。从源码结构看包内模块分工清晰main.py —Deploy统一门面类按部署类型分发deploy / plan / doctor / status / destroyschema.py —agents.yaml中deploy段的解析与校验models.py — 基于 Pydantic 的配置与结果模型APIConfig、DockerConfig、CloudConfig、DeployResult等api.py — 生成并启动 Flask API 服务器docker.py — 生成 Dockerfile、构建/运行/推送镜像、容器状态与销毁doctor.py — 部署前环境体检providers/ — 云平台提供者AWS ECS、Azure Container Apps、GCP Cloud Run 等通过可插拔注册表管理。Deploy类按DeployTypeapi/docker/cloud三种枚举值见 models.py分发到_deploy_api/_deploy_docker/_deploy_cloud其中云部署通过get_provider(self.config.cloud)拿到具体提供者实例后执行整体是一套统一入口 策略分发的架构。二、安装与运行环境2.1 安装方式README 提供了三种安装口径pip install praisonai-deploy pip install praisonai-deploy[api] # 附带 Flask API 服务器生成能力 pip install praisonai[deploy] # 完整 umbrella 包含 wrapper shims基础包仅包含编排能力生成、构建、plan、doctor[api]额外安装 Flask 相关依赖。查看 pyproject.toml 可知apiextra 声明了flask3.0.0与flask-cors4.0.0praisonai[deploy]用于在完整 umbrella 安装中启用部署能力并保持praisonai.deploy.*旧导入路径可用。环境约束requires-python 3.10,3.15包的核心依赖为praisonaiagents1.6.126、rich13.7、typer0.12.0、click8.4.2、PyYAML6.0、pydantic2.0。2.2 宿主 CLI 依赖重要前提README 明确本包不内嵌任何云 SDK无 boto3、无 Azure SDK云部署直接调用宿主机器上的 CLI 工具CLI用途docker构建与运行容器、Compose 栈awsAWS ECS 部署azAzure Container Apps 部署gcloudGCP Cloud Run 部署因此部署前需保证对应 CLI 已安装、已登录/已配置凭证否则deploy会失败——这正是doctor命令存在的意义详见第八节。2.3 运行时依赖生成的服务器README 特别强调了一个容易踩坑的细节由 deploy 生成的 API 服务器和 Docker 镜像在运行时会安装完整的praisonaifull wrapper因为它们嵌入from praisonai import PraisonAI来执行 Agent。deploy 包本身只负责编排generate、build、plan、doctor容器内部需要pip install praisonai flask gunicorn。这一点在 docker.py 生成的 Dockerfile 中也可以印证RUN pip install --no-cache-dir praisonai flask flask-cors gunicorn。三、CLI 命令全览3.1 入口命令在安装了完整 umbrellapraisonai的环境下部署命令挂在主 CLI 之下praisonai deploy run --file agents.yaml praisonai deploy doctor --all praisonai deploy validate --file agents.yaml praisonai deploy plan --file agents.yaml praisonai deploy status --file agents.yaml praisonai deploy destroy --file agents.yaml --yes praisonai deploy docker agents.yaml --tag v1 praisonai deploy aws agents.yaml --region us-east-1独立的控制台脚本不依赖 umbrellapraisonai-deploy --help该入口在 pyproject.toml 中声明为praisonai-deploy praisonai_deploy.__main__:main底层是基于 Typer 构建的命令组见 cli/commands/deploy.py。3.2 子命令与参数速查结合 cli/commands/deploy.py 源码命令组包含以下成员命令作用关键参数run按agents.yaml执行部署--file/-f默认agents.yaml、--typeapi/docker/cloud、--provider、--background、--jsondoctor检查部署就绪度--file/-f、--provider、--all、--verbose/-v、--jsoninit生成带 deploy 配置的示例agents.yaml--file/-f默认agents.yaml、--type默认api、--providervalidate校验 deploy 配置--file/-f、--jsonplan预演部署计划不实际执行--file/-f、--jsonstatus查询当前部署状态--file/-f、--json、--verbose/-vdestroy销毁/删除部署--file/-f、--yes/-y、--force、--jsonapi本地 API 部署run --type api别名位置参数文件、--background、--jsoncloud云部署run --type cloud别名位置参数文件、--provider必填dockerDocker 容器部署位置参数文件、--tag/-taws部署到 AWS位置参数文件、--region/-razure部署到 Azure位置参数文件、--resource-group/-ggcp部署到 Google Cloud位置参数文件、--project/-pfly部署到 Fly.io位置参数文件、--region/-rrailway部署到 Railway位置参数文件render部署到 Render位置参数文件compose up/down启动/停止 agents API Postgres Compose 栈--file/-f、--stack-dir、--foreground、--volumes/-v、--jsoncreate从 starter 模板脚手架化部署项目--template/-t必填、--dir/-d默认.helmhelm upgrade的薄封装--chartgateway 或 agents-api、--release/-r、--namespace/-n、--install/--no-install所有子命令都支持--json结构化输出便于脚本与 CI 集成。四、agents.yaml 中的 deploy 配置详解4.1 校验规则schema.py中的validate_agents_yaml(file_path)是解析入口规则如下见 schema.py文件必须存在且能通过yaml.safe_load解析必须包含deploy键否则返回None此时Deploy.from_yaml会抛出ValueError: No deploy configuration founddeploy段必须是mapping字典标量或列表如deploy: docker会被判定为格式错误deploy段只允许type、api、docker、cloud、agents五个键未知键直接报错防止dockerr:这类拼写错误被静默忽略后以默认值部署type必填取值只能是api、docker、cloud。4.2 三种部署类型的配置模型所有配置字段均由 Pydantic 模型定义见 models.py字段与默认值如下APIConfigtype: api字段默认值说明host127.0.0.1服务器监听地址port8005服务器端口workers1工作进程数cors_enabledtrue是否启用 CORSauth_enabledtrue是否启用认证auth_tokennull认证令牌未设置时自动生成reloadfalse开发模式自动重载DockerConfigtype: docker字段默认值说明image_namepraisonai-app镜像名taglatest镜像标签base_imagepython:3.11-slim基础镜像expose[8005]暴露端口列表registrynull镜像仓库 URL配置后 tag 会带仓库前缀pushfalse构建后是否推送仓库build_argsnull额外 Docker 构建参数CloudConfigtype: cloud字段默认值说明provider必填aws/azure/gcp也支持fly/railway/renderregion必填部署区域service_name必填服务/应用名imagenull容器镜像 URLcpu256CPU 分配memory512内存MBmin_instances1最小实例数max_instances10最大实例数env_varsnull环境变量字典cluster_namenullAWS ECS 集群名task_definitionnullAWS 任务定义resource_groupnullAzure 资源组subscription_idnullAzure 订阅 IDproject_idnullGCP 项目 ID4.3 三种类型的示例配置init命令生成的模板与 examples/deploy/ 下的真实示例完全对应API 类型参考 agents-api.yamldeploy: type: api api: host: 0.0.0.0 port: 8005 workers: 2 cors_enabled: true auth_enabled: false reload: falseDocker 类型参考 agents-docker.yamldeploy: type: docker docker: image_name: praisonai-analyst tag: v1.0.0 base_image: python:3.11-slim expose: - 8005 registry: ghcr.io/myorg push: false # 可选配置容器内生成的服务端 api: host: 0.0.0.0 port: 8005 auth_enabled: true注意 Docker 类型下可选的api兄弟段用于配置生成的服务端host/port/auth/cors语义与type: api一致见 schema.py。Cloud 类型AWS参考 agents-aws.yamldeploy: type: cloud cloud: provider: aws region: us-east-1 service_name: praisonai-service cpu: 256 memory: 512 min_instances: 1 max_instances: 10 # image: your-registry/praisonai-app:latest # cluster_name: praisonai-clusterAzure 示例额外需要resource_group与subscription_idGCP 示例需要project_id见 agents-azure.yaml 与 agents-gcp.yaml。五、Python API 使用README 给出了最简用法from praisonai_deploy import Deploy deploy Deploy.from_yaml(agents.yaml) result deploy.deploy() status deploy.status()Deploy支持两种构造方式见 main.py# 方式一从 YAML推荐 deploy Deploy.from_yaml(agents.yaml) # 方式二编程式构造 from praisonai_deploy import Deploy, DeployConfig, DeployType config DeployConfig(typeDeployType.API) deploy Deploy(config, agents_fileagents.yaml) result deploy.deploy()实例方法一览方法说明deploy(backgroundFalse)按配置类型执行部署返回DeployResultplan()返回部署计划字典不实际执行API 返回 host/port/workersDocker 返回镜像/端口Cloud 返回提供者计划doctor()按类型执行体检API 检查本地端口与 YAMLDocker 追加 Docker 可用性检查Cloud 交给提供者未知类型执行全量检查status()返回DeployStatusAPI 类型通过探测端口判断运行状态ServiceState.RUNNING/STOPPED/UNKNOWNDocker 通过docker inspectCloud 通过提供者查询destroy(forceFalse)销毁部署并返回DestroyResultAPI 跨平台查找并终止占用端口的进程Docker 停止并移除容器force时同时删除镜像Cloud 交给提供者praisonai_deploy包对外还暴露了get_deployment_status(agents_file...)工具函数返回state/url/message/service_name/provider/healthy字典便于 MCP 与工具集成见init.py。关于旧路径兼容README 明确praisonai.deploy.*旧导入路径在安装praisonaiwrapper 后仍然可用迁移期无需改动存量代码。六、API 服务器部署实战6.1 工作流程type: api的部署链路_deploy_api→start_api_server见 api.pygenerate_api_server_code()生成一个完整的 Flask 应用源码源码写入每次调用独立的私有临时目录tempfile.mkdtemp(prefixpraisonai_api_)权限 0700防止共享主机上其他用户预创建或替换生成文件自动尝试pip install flask flask-cors使用将运行服务器的同一解释器继承父进程环境如OPENAI_API_KEY按background标志以子进程方式前台或后台启动。6.2 生成的服务器端点生成的 Flask 应用见 api.py提供三个端点GET /health— 健康检查返回{status: ok, service: praisonai-api}POST /chat— 接收{message: ...}通过importlib.import_module(praisonai).run(agents_file, cli_config{topic: message})执行 Agent 并返回响应缺少message返回 400执行异常返回 500GET /agents— 返回可用 Agent 列表与agent_file。6.3 认证与 CORS生成的服务器内置 Bearer Token 认证auth_enabled: true时若未配置auth_token启动时会用secrets.token_urlsafe(32)自动生成令牌并打印到 stderr认证采用secrets.compare_digest常量时间比较防时序攻击运行时可用环境变量覆盖配置而无需重新生成文件PRAISONAI_API_AUTH非disabled即启用与PRAISONAI_API_TOKEN方便运维轮换令牌cors_enabled控制是否注入CORS(app)。部署 API 时可参考 agents-api.yaml 将host设为0.0.0.0以对外提供服务。七、Docker 部署实战7.1 生成的 Dockerfiletype: docker的部署链路_deploy_docker见 main.py依次执行生成并保存 Dockerfile → 生成 API 服务端代码 → 准备构建上下文 → 构建镜像 →可选推送 → 运行容器替换同名旧容器。生成的 Dockerfile见 docker.py包含几个值得注意的工程细节COPY只复制agents.yaml与生成的api_server.py使用 basename使绝对宿主路径在构建上下文中可用安装praisonai flask flask-cors gunicorn对应 README 的运行时依赖说明为每个expose端口生成EXPOSE指令内置HEALTHCHECK每 30s 探测/health启动命令使用gunicorn 且--timeout 120——源码注释解释了原因Agent 的 LLM 工作负载冷启动导入 首次模型往返经常超过 gunicorn 默认的 30s导致首个/chat请求中途 worker 被 SIGKILL。DEFAULT_GUNICORN_TIMEOUT 120是特意调大的。7.2 环境变量透传运行容器时宿主环境中以下变量会被透传进容器见 docker.pyOPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、PRAISONAI_API_TOKEN。另外当 API 配置了auth_enabled: false时会注入PRAISONAI_API_AUTHdisabled到容器环境。7.3 容器命名与生命周期容器名由{image_name}-{tag}派生非法字符如team/app中的/会被替换为-docker_container_namedocker.py保证符合 Docker 命名规范。deploy docker agents.yaml --tag v1可覆盖镜像 tagstatus通过docker inspect映射running/exited/created/dead到ServiceStatedestroy先docker stop再docker rm--force时追加docker rmi删除镜像。完整可运行的 Docker 示例见 agents-docker.yaml。八、云平台部署AWS / Azure / GCP8.1 提供者注册表与可扩展性云提供者通过注册表管理见 providers/_registry.py内置aws、azure、gcp、fly、railway、render六个提供者懒加载同时支持通过praisonai.deploy.providersentry-point 组注册第三方提供者。因此models.CloudProvider枚举只代表内置提供者真正的校验权威是list_cloud_providers()——这正是coerce_cloud_provider先查枚举、再查注册表的原因见 models.py。三个 provider 的 entry-point 声明可见 pyproject.toml。8.2 各提供者行为对比README 原文Provider行为AWS ECS仅更新路径全新部署greenfield需要预先存在的 VPC/服务配置AzureContainer Apps创建/更新GCPCloud Run创建或更新8.3 AWS ECSFargateAWSProvider 基于 ECS Fargate 实现plan()输出四步计划创建 ECS 集群如不存在→ 注册任务定义 → 创建/更新 ECS 服务 → 等待服务稳定deploy()依次执行aws ecs create-cluster、aws ecs register-task-definitionawsvpc网络模式 FARGATE兼容性容器端口 8005随后尝试aws ecs update-service若服务不存在则返回失败提示需手工预置 VPC/子网/安全组后走更新路径——与 README 的 Update-only path 一致status()通过describe-services将ACTIVE/DRAINING/INACTIVE映射到服务状态destroy(force)先将 desired count 置 0再delete-serviceforce时追加delete-cluster。8.4 Azure Container AppsAzureProvider 面向 Container Apps若配置了subscription_id所有az命令追加--subscription参数确保资源落在指定订阅而非az默认订阅doctor()除 CLI 登录检查外还会校验subscription_id与当前环境订阅是否匹配不匹配会给出az account set修复建议防止资源静默创建到错误订阅并检查资源组是否存在。8.5 GCP Cloud RunGCPProvider 面向 Cloud Rundoctor()会检查run.googleapis.comAPI 是否已启用未启用给出gcloud services enable run.googleapis.com建议plan()中内存会格式化为512Mi形式镜像默认推导为gcr.io/{project_id}/{service_name}:latest支持创建或更新create-or-update。8.6 云部署前置检查执行praisonai deploy doctor --all会一次性检查Python 版本≥3.9、端口可用性、agents.yaml有效性、Docker 可用性以及三个云 CLI 的登录/配置状态详见 doctor.py 中的check_aws_cli/check_azure_cli/check_gcp_cli。部署前建议先跑一遍 doctor定位环境缺失项。九、doctor 体检与故障排查doctor是 deploy 的健康体检命令核心数据结构为DoctorCheckResultname/passed/message/fix_suggestion与聚合的DoctorReport提供total_checks / passed_checks / failed_checks / all_passed属性。检查项汇总如下检查通过条件失败修复建议Python Version版本 ≥ 3.9升级 PythonPort {port}端口未被占用停止占用进程或换端口agents.yaml文件存在且 deploy 配置有效praisonai deploy init生成或修复配置Dockerdocker --version可执行安装 DockerAWS CLIaws sts get-caller-identity成功aws configureAzure CLIaz account show成功且订阅匹配az login/az account setGCP CLIgcloud config get-value project有值gcloud initdoctor --all对应run_all_checks会执行本地 Docker 全部云 CLI 检查指定--provider只跑对应厂商检查。失败项自带fix_suggestion可直接按提示修复。十、进阶Compose、Helm 与 Starter 模板除了单一容器/单服务部署仓库还提供了生产级基础设施资产位于 src/praisonai-deploy/infra/注意这些资产不随 PyPI wheel 发布仅在 monorepo checkout 中可用。10.1 Docker Compose 生产栈infra/compose/agents-stack/ 提供agents API pgvector Postgres的生产级 Compose 栈见其 READMEpraisonai deploy compose up --file agents.yaml # 或显式指定栈目录 praisonai deploy compose up --stack-dir ./src/praisonai-deploy/infra/compose/agents-stack --file agents.yaml praisonai deploy compose down栈内两个服务apiFlask/health与/chat运行生成的api_server.py与postgrespgvector/pgvector:pg16支撑 memory/RAG 工作负载。CLI 会在compose up前于项目目录生成api_server.py。关键环境变量包括API_PORT默认 8005、POSTGRES_PASSWORD必填无默认值首次compose up时 CLI 会自动生成强密码写入项目.env与OPENAI_API_KEY透传给 API 容器。安全默认Postgres 默认只绑定127.0.0.1。10.2 Helm Chartinfra/helm/praisonai-agents-api/ 提供平台级 Helm ChartAPI Postgresvalues.yaml 支持配置 replicaCount、镜像仓库、agents.content内联 agents.yaml、auth默认启用支持existingSecret与PRAISONAI_API_TOKEN密钥名、pgvector Postgres含 8Gi 持久化以及 ingress。使用方式praisonai deploy helm --chart agents-api --release praisonai-api # 或直接 helm helm install praisonai-api ./src/praisonai-deploy/infra/helm/praisonai-agents-api \ --set auth.existingSecretpraisonai-api-authGatewayC9的 Helm Chart 位于 praisonai-bot/infra/helm/praisonai-gateway在完整 monorepo checkout 中会被自动发现见 infra/README.md。10.3 Starter 模板infra/starters/ 提供五种开箱即用的模板索引见 templates.yamldocker-api本地 APIcompose-ready、docker-composeAPI Postgres 栈、flyfly.toml agents.yaml、railwayrailway.json agents.yaml、renderrender.yaml agents.yaml。脚手架命令praisonai deploy create --template docker-compose --dir ./my-projectinfra 资产还支持环境变量覆盖默认查找路径PRAISONAI_INFRA_ROOT、PRAISONAI_COMPOSE_STACK、PRAISONAI_HELM_ROOT、PRAISONAI_STARTERS_ROOT见 infra/README.md。十一、Monorepo 开发与回归门禁作为 monorepo 中的独立包从源码目录可编辑安装cd src/praisonai-deploy uv pip install -e .pyproject.toml中[tool.uv.sources]将praisonaiagents指向本地../praisonai-agents保证开发时使用仓库内版本。README 列出的回归门禁scripts/check_c14_deploy_imports.sh— 检查 deploy 包的导入边界src/praisonai/tests/PRAISONAI_DEPLOY_MANIFEST.md— 包所有权边界说明src/praisonai-deploy/tests/— 包内单元测试覆盖 CLI 命令、schema 校验、Docker、doctor、provider 注册表等如 tests/test_cli.py 对 api/docker/aws 命令的 handler 调用验证。十二、端到端工作流速览将以上能力串起来一次典型部署的完整闭环如下# 1. 生成带 deploy 配置的 agents.yaml或手写 deploy 段 praisonai deploy init --type api --file agents.yaml # 2. 校验配置 praisonai deploy validate --file agents.yaml # 3. 体检环境 praisonai deploy doctor --all # 4. 预演部署计划 praisonai deploy plan --file agents.yaml # 5. 实际部署三选一本地 API / Docker / 云 praisonai deploy run --file agents.yaml --type api praisonai deploy docker agents.yaml --tag v1 praisonai deploy aws agents.yaml --region us-east-1 # 6. 查询状态 praisonai deploy status --file agents.yaml # 7. 销毁 praisonai deploy destroy --file agents.yaml --yes全程无需手写 Flask 应用、Dockerfile 或云资源模板——praisonai-deploy负责生成、编排与生命周期管理你只需要维护一份agents.yaml。若需深入源码建议从 main.py统一入口与 schema.py配置解析开始阅读。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考