agno-agent-starter: Instructions file for Codex

Agno Agent Service 开发规范

AI 工具主规范文档。所有 AI 辅助开发工具（Cursor、Claude Code 等）应参考本文档。

---

核心哲学

1. AgentOS First — 使用 AgentOS 标准 API，不手写 FastAPI 路由
2. Single Agent 优先 — 90% 场景用单 Agent + 工具解决，避免过度使用 Team/Workflow
3. 配置与代码分离 — 模型参数用 ModelConfig 配置，不硬编码

---

项目结构概览

agno-agent-starter/
├── app/                     # 应用代码（User Code 区域）
│   ├── main.py              # AgentOS 入口（脚手架核心，慎改）
│   ├── config.py            # 三层配置加载器（脚手架核心）
│   ├── agents/              # ✏️ Agent 实现（用户扩展区）
│   ├── teams/               # ✏️ Team 实现（用户扩展区）
│   ├── workflows/           # ✏️ Workflow 实现（用户扩展区）
│   ├── models/              # 模型抽象层（脚手架提供）
│   ├── tools/               # 三层工具注册表
│   │   ├── framework/       # 框架级工具（脚手架提供）
│   │   ├── project/         # ✏️ 项目级工具（用户扩展区）
│   │   └── user/            # Agent 专用工具
│   ├── hooks/               # 护栏与生命周期钩子
│   └── mcp/                 # MCP Server（AI Agent 开发工具）
├── api/                     # OpenAPI 规格（自动生成）
├── tests/                   # 单元测试（镜像 app/ 结构）
├── scripts/                 # 脚本工具（含 agno CLI）
└── .cursor/rules/           # Vibe Coding 规则

User Code vs Scaffold Core:

• ✏️ 标记 = 用户扩展区，自由修改
• 无标记 = 脚手架核心，谨慎修改

---

开发规范

命名规则

元素	规则	示例
Agent ID	kebab-case	github-analyzer
文件名	snake_case.py	github_analyzer.py
类名	PascalCase	GitHubAnalyzer
函数/变量	snake_case	analyze_repo
常量	UPPER_SNAKE_CASE	MAX_RETRIES

性能要求

• 禁止在循环中创建 Agent，Agent 实例是重量级对象
• 创建一次，复用多次
• 异步操作使用 async def

代码风格

• 禁止在 print/log 中使用 emoji
• 工具函数返回 str，让模型处理
• 每个模块必须在 __init__.py 注册

---

模型配置

基础用法

from app.models import ModelConfig, create_model

AGENT_MODEL_CONFIG = ModelConfig(
    model_id="google/gemini-2.5-flash-preview-09-2025",
    temperature=0.1,
    max_tokens=16384,
)

model = create_model(AGENT_MODEL_CONFIG)