Agno Infra 实战指南：用 ag/agno CLI 统一管理 Agent 基础设施（AWS、Docker 与本地环境）

Agno Infra 实战指南用 ag/agno CLI 统一管理 Agent 基础设施AWS、Docker 与本地环境【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agnoAgno Infra 是 agno 仓库中面向 Agent 应用的基础设施管理框架它把 AWS、Docker 和本地环境的基础设施编排统一收敛到ag/agno两个命令背后。本文以 libs/agno_infra/README.md 为主线结合libs/agno_infra/agno下的 CLI、Infra 配置与 base 抽象源码讲解安装、模板建站、部署/销毁等完整操作流程并深入到资源分组、环境过滤与失败容忍等实现机制读完即可用模板方式部署和管理一套 Agent 基础设施。什么是 Agno InfraAgno Infra 是一个轻量级的「Agentic Infrastructure」管理框架与命令行工具定位是the programming language for agentic infrastructurepyproject.toml 中的描述。它解决的核心问题是一个 Agent 应用往往需要数据库、缓存、消息队列、推理服务等多个配套组件而这些组件散落在 AWS、Docker 等不同平台手工管理成本高且容易出错。Agno Infra 通过一套统一的资源抽象和 CLI把这些组件的创建、启动、更新与销毁标准化。核心特性多平台支持同一套命令编排 AWS、Docker 与本地环境面向 Agent 设计资源建模围绕 AI Agent 的部署场景展开模板化起步内置多种预置基础设施模板一键克隆工程骨架统一 CLIag与agno是同一入口的两个别名覆盖全部基础设施操作资源管理对数据库、网络、存储、计算资源提供生命周期管理应用支持内置 FastAPI、Streamlit、Celery、Django、PostgreSQL含 pgvector、Redis 等常见应用与中间件。从源码看ag和agno都映射到同一个入口函数这一点在 pyproject.toml 的[project.scripts]中定义[project.scripts] ag agno.cli.entrypoint:agno_cli agno agno.cli.entrypoint:agno_cli入口函数agno_cli在 entrypoint.py 中创建并挂载了infra子命令组其 help 文本给出的推荐使用流程是ag infra create从模板创建一个新的基础设施工程ag infra up启动基础设施ag infra down停止基础设施。安装与依赖说明pip 安装基础安装pip install agno-infra按平台能力安装可选依赖# AWS 支持引入 boto3 pip install agno-infra[aws] # Docker 支持引入 docker SDK pip install agno-infra[docker] # 开发环境mypy、ruff、pytest、pytest-asyncio pip install agno-infra[dev]环境要求与运行时依赖Python 版本README 声明 Python 3.7pyproject.toml 的约束为requires-python 3.7,4classifier 覆盖到 Python 3.12。AWS 场景需要配置有效的 AWS 凭证boto3通过awsextra 引入。Docker 场景需要 Docker 引擎处于运行状态。运行期核心依赖由dependencies定义pydantic与pydantic-settings配置建模、typerCLI 框架、rich终端美化输出、httpxHTTP 客户端、gitpython模板 git 克隆、python-dotenv.env 加载、tomli/python-multipart等。另外可关注tests目录中的测试资源与 scripts 下的辅助脚本可作为本地验证与二次开发的参考。快速开始从模板创建工程创建基础设施工程# 创建基于 Docker 模板的 Agent 基础设施工程 ag create my-agent-infra --template agent-infra-docker # 进入工程目录 cd my-agent-infra需要说明的是README 中展示的是ag create的简写形态而当前仓库中实际注册的子命令为ag infra create二者指向相同的模板创建逻辑见 infra_cli.py 中的create命令。因此更严谨的写法是ag infra create my-agent-infra --template agent-infra-dockercreate命令支持的参数包括-n/--name工程目录名、-t/--template模板名与-u/--url自定义模板仓库地址并可通过-d/--debug打开调试日志。模板机制与内置模板从 operator.py 的create_infra_from_template实现可以看出模板创建本质上是一次git cloneCLI 先把模板仓库克隆到cwd/name然后删除克隆下来的.git目录rmdir_recursive再把工程注册进本地 CLI 配置。若工程包含infra目录还会自动把infra/example_secrets复制为infra/secrets避免用户手动拷贝敏感配置。enums.py 中定义了三种内置模板模板值含义对应的模板名称映射agentos-dockerDocker 部署模板agentos-docker默认agentos-awsAWS 部署模板agentos-awsagentos-railwayRailway 平台模板agentos-railway交互模式下如果既不传--template也不传--urlCLI 会打印上述模板列表并让用户选择默认选中agentos-docker。模板名非法时会抛出异常并提示可选项。若工程目录已存在create会报错并中止避免覆盖已有代码。创建过程做了什么整个创建流程可以拆解为五步对应 operator.py 中create_infra_from_template的实现初始化/加载本地 CLI 配置AgnoCliConfig确保~下的 agno 配置可用解析模板或 URL得到待克隆的仓库地址将模板仓库克隆到cwd/name并清理.git若是非纯 Docker 工程自动从infra/example_secrets复制出infra/secrets将新工程写入 CLI 配置并设为active工程。成功后 CLI 会提示下一步操作cd进工程后执行ag infra up启动、ag infra down停止。统一 CLI常用操作一览ag的完整操作集合比 README 中列出的更多当前仓库的infra子命令组infra_cli.py包括命令作用等价语义ag infra create从模板创建工程相当于 README 中的ag createag infra up启动/创建全部或过滤后的资源对应ag deployag infra down停止/删除全部或过滤后的资源对应ag destroyag infra patch更新patch资源增量更新ag infra restart重启资源先down再up中间 sleep 2 秒ag infra config打印当前 active 工程的配置查看infra_name、infra_root_pathag infra delete从 CLI 记录中删除工程不删物理文件注销记录注意README 中的ag status、ag templates在当前仓库的infra子命令组中暂无对应命令实现实际操作时以本文表格中的命令为准。资源过滤ENV:INFRA:GROUP:NAME:TYPEup、down、patch、restart都支持两种过滤方式且可以叠加位置参数 resource_filter格式为ENV:INFRA:GROUP:NAME:TYPE字段可按需省略。例如ag infra up dev只部署 dev 环境ag infra up prd:aws只部署 prd 环境下的 AWS 资源ag infra up prd:::s3匹配 prd 环境下 name 含s3的资源。命名选项-e/--env、-i/--infra、-g/--group、-n/--name、-t/--type五种过滤维度作用于每个资源上的env、infra、group、name、类型字段这些字段定义在 base.py 的InfraBase中。当过滤选项未显式给出时up/down会回落到InfraSettings中的default_env默认dev与default_infra。常用选项所有资源生命周期命令都支持-dr/--dry-run只打印将要执行的资源而不真正执行-y/--yes跳过交互确认-f/--force强制创建/更新/删除忽略缓存-p/--pull按需拉取镜像-d/--debug打印调试日志。Docker Compose 兼容若当前目录或 active 工程目录下发现docker-compose.yml之类的 compose 文件up/down会转而调用docker compose up -d --build/docker compose down见 infra_cli.py 与 utils.py这也是本地快速起步的路径之一。工程结构与资源抽象目录布局README 给出的包结构对应libs/agno_infra/agno下的实际目录agno/ ├── aws/ # AWS 资源管理 │ ├── resource/ # AWS 资源类型EC2、RDS、S3 等 │ └── app/ # AWS 应用部署FastAPI、Streamlit、Django、Celery ├── docker/ # Docker 资源管理 │ ├── resource/ # Docker 资源容器、网络、卷、镜像 │ └── app/ # Docker 应用FastAPI、Streamlit、Postgres/pgvector、Redis 等 ├── base/ # 基类与接口 ├── cli/ # 命令行入口entrypoint、infra_cli、config、operator ├── infra/ # 基础设施核心config、settings、operator、enums └── utilities/ # 工具集yaml_io、load_env、py_io、resource_filter 等在仓库中aws/、docker/目录下实际各包含resource/与app/两个子目录app侧已有fastapi/、streamlit/、celery/、django/aws以及postgres/含 pgvector、redis/、whoami/docker等实现。三层抽象InfraBase / InfraResources / InfraConfig从 base.py 与 config.py 看整个框架建立在三层 pydantic 模型之上InfraBasebase.py所有资源/应用的公共基类。携带name、group、env、infra、enabled等过滤字段以及skip_create/skip_read/skip_update/skip_delete、recreate_on_update、use_cache、force等生命周期控制开关还包含等待语义wait_for_create/update/delete、waiter_delay、waiter_max_attempts与 env/secrets 注入能力env_vars、env_file、secrets_file。InfraResourcesresources.py一组一起管理的基础设施资源聚合apps与resources两个列表提供create_resources、delete_resources、update_resources、save_resources四个批量操作接口。InfraConfigconfig.py工程级配置记录infra_root_path负责发现infra/settings.py、递归加载infra目录下所有 Python 文件中定义的资源对象并按env/infra过滤、注入InfraSettings。InfraSettings工程全局设置settings.py 中的InfraSettings是工程内所有资源共享的配置关键字段如下类别字段说明标识infra_name、infra_root、infra_repo工程名、根路径、git 仓库地址默认过滤default_env默认dev、default_infraag infra up/down未指定过滤时的回落值镜像image_repo默认agnohq、image_name、build_images、push_images、skip_image_cache、force_pull_imagesDocker 镜像构建与推送策略多环境test_env/test_key、dev_env/dev_key、stg_env/stg_key、prd_env/prd_key四套环境名与 keykey 未指定时自动生成为{infra_name}-{env}失败容忍continue_on_create_failure默认 False、continue_on_delete_failure默认 True、continue_on_patch_failure默认 False单个资源失败后是否继续处理后续资源缓存use_cache默认 True资源已存在时跳过重复创建AWSaws_region、aws_profile、aws_subnet_ids、aws_public_subnets、aws_private_subnets、aws_az1~aws_az5、aws_security_group_ids、efs_file_system_id、efs_access_point_id区域、子网、可用区、安全组与 EFS 持久化配置值得注意的默认行为aws_subnet_ids为空时会自动把aws_public_subnets aws_private_subnets合并进去_validate_and_set_subnet_ids因此只需声明公网/私网子网即可。支持资源与应用一览AWS 资源计算EC2 实例、ECS 集群、ECS 服务存储S3 桶、EBS 卷数据库RDS 实例与集群网络VPC、子网、安全组、负载均衡器安全IAM 角色与策略、ACM 证书分析EMR 集群、Glue 爬虫缓存ElastiCache 集群。Docker 资源容器完整的容器生命周期管理网络自定义 Docker 网络卷持久化与临时卷镜像镜像管理。应用类型FastAPIREST API 应用Streamlit数据科学与机器学习仪表盘Celery分布式任务处理DjangoWeb 应用PostgreSQL带 pgvector 支持的数据库Redis缓存与消息代理。这些应用在仓库中均有对应实现类例如 docker 侧的 fastapi.py、pgvector.py、redis.pyaws 侧的 django.py 等读者可进一步阅读源码了解每个应用类型支持的字段。底层工作流up / down / patch 如何运转以ag infra up为例operator.py 的start_infra其执行链路是确定目标工程依次检查「当前目录是否已注册的 Infra 工程」→「当前目录是否存在infra目录则自动 setup」→「CLI 配置中的 active 工程」都找不到则打印可用工程列表并退出infra_cli.py 的up命令加载环境变量set_local_env()把AGNO_INFRA_ROOT、AGNO_INFRA_DIR、AGNO_INFRA_NAME写入进程环境并在缺省时用InfraSettings.aws_region兜底AWS_REGION见 constants.py 与 config.py加载资源分组get_resources(env, infra, ordercreate)递归扫描infra目录下所有.py文件跳过ignore、test、tests、config目录与__init__.py收集InfraResources对象按infra、env依次过滤跳过enabledFalse的组最后注入InfraSettings按序创建对每个资源组调用create_resources(group_filter, name_filter, type_filter, dry_run, auto_confirm, force, pull)统计成功/总数并打印汇总若有失败会提示Some resources failed to create, please check logs结束dry_run或全部成功后返回。ag infra down走同样的链路但get_resources使用orderdelete即按删除顺序倒序处理并对每个组调用delete_resourcesag infra patch则调用update_resources。三者共同复用了InfraConfig的资源发现与过滤逻辑这也是整个框架统一编排的核心所在。配置、调试与常见运维技巧打印与切换工程ag infra config打印 active 工程的infra_name与infra_root_pathag infra delete -infra name从 CLI 记录中删除某工程注意只删记录不删磁盘文件。调试与安全确认在真实变更前先ag infra up -dr --debug做 dry-run 预览避免误操作部署/销毁前若不希望交互确认使用-y/--yes对敏感配置模板会自动生成infra/secrets从example_secrets复制应把真实密钥放于此目录并通过secrets_file注入资源避免硬编码。环境隔离通过dev、stg、prd等env过滤值可以在同一套工程定义下分别部署不同环境每个环境使用各自的*_env/*_key与.env文件实现一套定义、多环境复用。结语Agno Infra 用「模板工程 统一 CLI pydantic 资源模型」的组合把 Agent 应用的基础设施部署从多平台碎片化操作收敛为ag infra create/up/down/patch几个命令。其核心价值在于通过InfraConfig自动发现infra目录下的资源定义配合env/infra/group/name/type五维过滤与InfraSettings全局配置让 AWS、Docker 与本地环境的资源可以声明式地创建、更新与销毁。若需更深入的能力建议继续阅读 libs/agno_infra/agno 下的aws/、docker/、base/与infra/源码以及仓库根目录 README.md 了解 Agno 平台的整体定位。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考