Agno AgentOS 配置全指南：用 AgentOSConfig（Python/YAML）声明 UI 元数据与数据域并验证渲染结果

Agno AgentOS 配置全指南：用 AgentOSConfig（Python/YAML）声明 UI 元数据与数据域并验证渲染结果

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

AgentOSConfig是 Agno AgentOS 中控制“运行中的 OS 如何向控制平面（control plane）展示其组件与数据域”的配置入口。本指南基于 cookbook 中 08_os_config 完整示例，讲解如何用 Python 对象与 YAML 文件声明同一套配置——包括available_models、按 Agent 组织的manifestUI 元数据以及命名 session/memory 数据域——并通过GET /config接口验证 AgentOS 实际渲染出的结果。读完你将掌握 AgentOS 的配置模型、两种配置方式的适用场景，以及如何让控制平面 UI 与运行时组件（Agent、数据库）精准对齐。

AgentOS 配置模型速览：控制平面如何看到你的 OS

在 Agno 中，AgentOS 是一个运行中的“操作系统”，控制平面（如 Web UI 或 API 客户端）需要知道这台 OS 上有哪些组件（Agent / Team / Workflow）、提供哪些模型选项，以及会话、记忆等数据分别存在哪张“域”里。AgentOSConfig就是这一层“展示配置”的载体，它与运行时对象解耦：Python 依旧创建运行时 Agent 与数据库，AgentOSConfig只负责描述它们在控制平面中的呈现方式。

配置模型定义在 libs/agno/agno/os/config.py，核心数据结构如下：

在AgentOSConfig中，manifest是一个以 Agent/Team/Workflow 的id为键的字典，值是Manifest对象（从源码注释可确认其用途为 AgentOS 专属 UI 元数据，与发送给模型的Agent.description无关）。session/memory等域配置下挂dbs列表，每个DatabaseConfig通过db_id指向真实的数据库对象，再通过domain_config.display_name给出该库在此域中的人性化名称。

示例文件结构：同一概念的两种声明 + 一套验证手段

本示例的三个文件演示“同一定义、双轨声明、统一验证”：

两个 Python 文件结构相同：默认以 serve 模式启动 AgentOS 应用；加上--demo参数后，则作为 HTTP 客户端访问GET /health与GET /config，断言渲染结果并打印输出。也就是说，这套示例自带了“运行—自检”闭环。

前置条件与双终端运行方式

配置检查不需要任何外部凭据。只有当你想真正运行配置中的 Agent 时，才需要设置OPENAI_API_KEY。

本示例采用“服务端 + 校验客户端”的双终端模式。先启动 Python 配置版服务（终端 1）：

.venvs/demo/bin/python cookbook/05_agent_os/08_os_config/config_basics.py

再在终端 2 运行--demo客户端去抓取并校验渲染出的配置：

.venvs/demo/bin/python cookbook/05_agent_os/08_os_config/config_basics.py --demo

YAML 配置版的运行方式完全一致，只是换成对应脚本：

# 终端 1：启动 YAML 配置的 AgentOS .venvs/demo/bin/python cookbook/05_agent_os/08_os_config/yaml_config.py # 终端 2：以 --demo 模式校验渲染结果 .venvs/demo/bin/python cookbook/05_agent_os/08_os_config/yaml_config.py --demo

关于服务端口，可查看AgentOS.serve()（libs/agno/agno/os/app.py）的签名：默认host="localhost"、port=7777，并支持通过环境变量AGENT_OS_HOST与AGENT_OS_PORT覆盖。客户端侧则通过AGENT_OS_BASE_URL（默认http://localhost:7777）定位服务端——示例代码里正是用os.getenv("AGENT_OS_BASE_URL", "http://localhost:7777")取得该地址。

用 Python 对象声明 AgentOSConfig：config_basics.py 拆解

config_basics.py 首先创建真实的运行时对象——一个 SQLite 数据库和一个 Agent：

db = SqliteDb( id=DB_ID, # DB_ID = "os-config-db" db_file="tmp/os_config.db", ) operations_agent = Agent( id=AGENT_ID, # AGENT_ID = "operations-agent" name="Operations Agent", model=OpenAIResponses(id="gpt-5.5"), db=db, instructions="Answer operations questions clearly and concisely.", add_history_to_context=True, num_history_runs=3, update_memory_on_run=True, markdown=True, )

接着把该 Agent 的展示信息与数据库的域归属写进AgentOSConfig：

os_config = AgentOSConfig( available_models=["gpt-5.5"], manifest={ AGENT_ID: Manifest( description="Answers operational questions and summarizes next steps.", labels=["operations", "production"], quick_prompts=[ "Summarize the current operational priorities.", "Turn these notes into an action plan.", "What should I investigate first?", ], ) }, session=SessionConfig( dbs=[ DatabaseConfig( db_id=DB_ID, domain_config=SessionDomainConfig( display_name="Operations conversations" ), ) ] ), memory=MemoryConfig( dbs=[ DatabaseConfig( db_id=DB_ID, domain_config=MemoryDomainConfig(display_name="Operations preferences"), ) ] ), )

最后把配置对象通过config=参数传给AgentOS，取得 ASGI 应用并启动：

agent_os = AgentOS( id="python-config-os", description="AgentOS configured with Python objects.", db=db, agents=[operations_agent], config=os_config, ) app = agent_os.get_app()

这里值得特别注意两处语义（README 已明确说明，也符合 config.py 中Manifest的注释）：

• manifest的键是显式的 Agent IDoperations-agent。渲染后，labels出现在控制平面组件卡片上，quick_prompts出现在聊天页中。
• available_models控制UI 呈现给用户的模型选项，它不会替换 Agent 自身配置的模型（OpenAIResponses(id="gpt-5.5")依然生效）。

Session 与 memory 条目命名的是同一个真实 SQLite 数据库在不同数据域中的显示身份：同一个db_id="os-config-db"，在会话域显示为 “Operations conversations”，在记忆域显示为 “Operations preferences”。

用 YAML 声明同一份配置：yaml_config.py 与 config.yaml

当运维人员需要在不改动 Python 的前提下调整 UI 元数据时，YAML 更有优势；而当配置需要条件化组装或与类型化的应用常量共享时，Python 更合适。无论哪种方式，Python 仍然负责创建运行时 Agent 与数据库——YAML 配置的只是它们的“呈现层”，因此 YAML 中的 manifest 键和db_id值必须与那些运行时对象严格匹配。

config.yaml 完整声明如下：

available_models: - gpt-5.5 manifest: yaml-operations-agent: description: Answers operational questions and summarizes next steps. labels: - operations - production quick_prompts: - Summarize the current operational priorities. - Turn these notes into an action plan. - What should I investigate first? session: dbs: - db_id: yaml-os-config-db domain_config: display_name: Operations conversations memory: dbs: - db_id: yaml-os-config-db domain_config: display_name: Operations preferences

yaml_config.py 与 Python 版的关键区别，在于传入AgentOS(config=...)的不再是对象，而是一个指向 YAML 文件的路径字符串：

CONFIG_PATH = Path(__file__).with_name("config.yaml") ... agent_os = AgentOS( id="yaml-config-os", description="AgentOS configured from YAML.", db=db, agents=[operations_agent], config=str(CONFIG_PATH), )

选择机制可以这样归纳：传入 YAML 路径config=即采用 YAML 中的值；传入AgentOSConfig对象即采用代码内的值。为了让 YAML 中的 manifest 键yaml-operations-agent能被正确匹配，示例中注册的 Agent 其id也必须是yaml-operations-agent，数据库id必须是yaml-os-config-db——这与 README 强调的“manifest 键与db_id必须与运行时对象匹配”完全一致。

示例还刻意不注册任何消息接口（interfaces）。因为接口是运行时对象，只能通过AgentOS(interfaces=[...])传入，不应在 YAML 中“凭空声明”。相应的，yaml_config.py的校验逻辑里专门检查了rendered["interfaces"]必须为空，若渲染结果出现意外接口会直接抛出RuntimeError。

用 GET /config 验证渲染结果：--demo 客户端做了什么

--demo模式下的show_rendered_config()函数（两个 Python 文件实现相同）是这套示例的“验收器”：通过httpx.Client先请求GET /health，再请求GET /config，随后对 JSON 结果做四类断言：

• available_models被原样保留（Python 版或 YAML 版均应为["gpt-5.5"]）；
• manifest 中的 ID 确实对应一个已注册的 Agent（operations-agent或yaml-operations-agent）；
• session 与 memory 域中的db_id指向真实存在的数据库；
• （仅 YAML 版）interfaces列表为空。

全部通过后打印渲染出的关键信息，例如：

Health: ok AgentOS: python-config-os Available models: ['gpt-5.5'] Manifest labels: ['operations', 'production'] Quick prompts: ['Summarize the current operational priorities.', ...] Session domain: Operations conversations (os-config-db) Memory domain: Operations preferences (os-config-db)

源码级原理：为什么“显式条目优先、其余自动补全”？

README 指出：某个db_id一旦有了显式域条目，该条目就对其拥有优先权；AgentOS 只会自动发现并追加那些“还没有任何条目”的数据库。这条规则可以在源码中得到印证——app.py 中的_get_session_config与_get_memory_config的实现模式完全一致：先取出配置里的dbs并收集已有条目的db_id集合，再遍历 AgentOS 自身发现到的全部数据库（self.dbs.items()），仅当某db_id不在已有条目中时才追加一个DatabaseConfig，其domain_config.display_name默认取db_id本身，并把该库对应的 session/memory 表名收集进tables。也就是说：

• 显式声明的display_name（如 “Operations conversations”）会原样呈现；
• 未声明的库会以db_id作为展示名被自动补进控制平面，保证 UI 不会漏掉任何真实数据源。

同族的_get_learning_config、_get_knowledge_config、_get_metrics_config、_get_evals_config、_get_traces_config（app.py）也遵循相同的“配置优先 + 自动发现兜底”原则，只是各自面向不同的数据域。

input_schema 与聊天表单：控制平面如何渲染结构化输入

配置不止影响展示文案，还影响控制平面如何收集用户输入。README 提到：Agent、Team 或 Workflow 都可以定义input_schema。聊天 UI 的工作链路是：

1. 通过/config发现当前 OS 上有哪些组件；
2. 拉取所选组件的 detail 响应；
3. 用其 JSON schema 渲染出结构化的表单（而不是自由文本框）。

一个完整的例子在 09_serving_workflows/with_input_schema.py：它演示了一个声明input_schema的 Workflow，并配合实时的GET /workflows/{id}检查来确认 schema 被正确下发。这说明AgentOSConfig负责“元数据层”，而input_schema负责“交互层”，两层共同决定了控制平面聊天的体验。

实测记录：LIVE 测试验证

该示例附有 TEST_LOG.md，记录了两份 Python 文件在 Agno 源码 commit37496c5ccd3be632cdbb97a9111a4a09999850fb上的 LIVE 实测结果（均 PASS）：

• config_basics.py：通过AGENT_OS_PORT/AGENT_OS_BASE_URL环境变量把服务覆盖到端口 7787 后启动，再用--demo客户端校验。GET /health返回ok；GET /config返回 OS IDpython-config-os、Agent IDoperations-agent、可用模型gpt-5.5、两个 manifest 标签、三个快捷提示词，以及显式声明的 session/memory 域os-config-db（分别命名为Operations conversations与Operations preferences）。
• yaml_config.py：同样在 7787 端口上启动并通过校验。GET /config完整保留了 YAML 中的 manifest 与gpt-5.5模型列表，把yaml-operations-agent正确关联到已注册 Agent，session/memory 域只返回真实存在的yaml-os-config-db，且接口列表为空。

日志还记录了额外的工程校验：两个脚本以本工作树libs/agno构建应用成功、递归模式校验 2 个 Python 文件 0 违规、Ruff format/check 通过、陈旧模型/emoji/废弃接口扫描无命中。这意味着本示例不仅可运行，其代码风格与 API 用法也与当前仓库源码保持一致。

小结：何时选 Python、何时选 YAML

把本示例的取舍浓缩成一张决策表：

掌握这套机制后，你就可以让 Agno AgentOS 的控制平面呈现与运行时拓扑始终保持一致，并通过GET /config随时做“配置即验证”的自检。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno