1. 原始项目地址 Shubhamsaboo/awesome-llm-apps: Collection of awesome LLM apps with AI Agents and RAG using OpenAI, Anthropic, Gemini and opensource models.
  2. 实践项目地址 large_model_projects/Agent/2025-11-29-agno-demo · chesterwang/large_model_projects

agno 框架

agno_hello_world.py 的role问题 (Kimi的openai接口兼容性)

原始代码为

web_agent = Agent(
    name="Web Researcher",
    model=OpenAIChat(id="kimi-k2-turbo-preview",
                     base_url=OPENAI_API_BASE, 
                     api_key=OPENAI_API_KEY),
    tools=[DuckDuckGoTools()],
    instructions=["Always include sources in your response."],
    debug_mode=True,
    markdown=True,
)

print("--- Agent Running ---")
web_agent.print_response("What are the latest key features of the Agno (Phidata) framework?", stream=True)

运行报错如下

agno.exceptions.ModelProviderError: invalid request: unsupported role ROLE_UNSPECIFIED。

经过debug发现 OpenAI和KIMI 的api对于 message role的 规范有一定差异。

OpenAI sdk中关于role的代码

# OpenAI 的role
# 参考官方文档 [Model Spec (2025/02/12)](https://model-spec.openai.com/2025-02-12.html#chain_of_command)
# 代码 agno.models.openai.chat
# The role to map the message role to.
default_role_map = {
    "system": "developer",
    "user": "user",
    "assistant": "assistant",
    "tool": "tool",
    "model": "assistant",
}

OpenAI 官方文档中对于role的描述

  • role (required): specifies the source of each message. As described in Instructions and levels of authority and The chain of command, roles determine the authority of instructions in the case of conflicts.
    • system: messages added by OpenAI
    • developer: from the application developer (possibly also OpenAI)
    • user: input from end users, or a catch-all for data we want to provide to the model
    • assistant: sampled from the language model
    • tool: generated by some program, such as code execution or an API call

KIMI 文档中关于 role的描述（from 基本信息 - Moonshot AI 开放平台 - Kimi 大模型 API 服务）

这是一个结构体的列表，每个元素类似如下：{“role”: “user”, “content”: “你好”} role 只支持 system,user,assistant 其一，content 不得为空 另外，对于tool_use的特性，KIMI则支持 rule=tool 的message。

解决方案

  1. 综上所述，临时解决方案是 将 instruction 的内容 塞到 input 变量中，即将instruction的system角色修改为 user角色。 这种方法不可行，猜测是因为即使没有增加instruction内容，在message 格式化的时候，还是会制定 developer部分内容，导致api接口报错。
  2. 最终解决方法，强行指定 role_map，将 developer 改为 system。 程序运行成功。
  3. 附注： dudugo 工具需要搜索网络，需要开启本地科学上网代理。