Agno 快速上手：从零创建并运行你的第一个 Agent（basic_agent、instructions 与 tools 三例详解）

本文基于 Agno 仓库 cookbook/02_agents/01_quickstart/ 目录的官方入门文档展开，完整覆盖其环境准备（direnv、demo_setup.sh 虚拟环境）、运行方式，并对该目录下的三个入门示例——基础 Agent、带 instructions 的 Agent、带 tools 的 Agent——逐一给出可复制的完整代码，并结合同仓库 libs/agno 中的 Agent 类源码，深入讲解 model、name、instructions、tools 等核心参数的真实定义与作用机制。读完后，你可以独立搭建 Agno 开发环境并跑通自己的第一个 Agent。

这个快速入门目录包含什么

cookbook/02_agents/01_quickstart/ 是 Agno 中“使用核心配置创建并运行 Agent（Starter examples for creating and running agents with core settings）”的起点。目录 README.md 列出了三个示例文件，各自聚焦一个最基础的 Agent 配置维度：

• basic_agent.py：最简 Agent，只指定 name 与 model；
• agent_with_instructions.py：为 Agent 附加系统级行为指令（instructions）；
• agent_with_tools.py：为 Agent 挂载可调用工具（tools）。

这三个文件覆盖了 Agent 配置最核心的三要素：身份（name）、大脑（model）、行为约束（instructions）、能力扩展（tools）。所有示例都采用同一套运行约定：以 __main__ 入口调用 agent.print_response(..., stream=True) 流式输出结果。

环境准备：依赖与虚拟环境

README 的 Prerequisites 部分明确了三个前置条件，这里完整保留并补充实际细节：

1. 加载环境变量：执行 direnv allow 加载 .envrc，确保 OPENAI_API_KEY 等模型提供方密钥可用。
2. 创建 demo 虚拟环境：执行 ./scripts/demo_setup.sh，之后统一用 .venvs/demo/bin/python 运行 cookbook 脚本。
3. 可选依赖：部分示例需要本地可选服务（如 pgvector）或提供方专属 API Key；本目录三个示例仅需 OPENAI_API_KEY（其中 tools 示例调用 DuckDuckGo 搜索，属公网服务，无额外密钥）。

从 scripts/demo_setup.sh 的源码看，该脚本做了以下几件事：

• 前置检查：若当前已激活其他 venv 会直接退出（Deactivate your current venv first.），并要求系统已安装 uv；
• 用 uv venv .venvs/demo --python 3.12 创建 Python 3.12 的独立虚拟环境；
• 以可编辑模式一次安装两个包：uv pip install -e libs/agnoctl -e libs/agno[demo]——即本地 libs/agno 源码（含 demo 额外依赖集）与 libs/agnoctl 一起装入环境，这样 cookbook 直接运行的是仓库内的 agno 源码，便于开发者调试。

脚本执行完毕会提示激活命令 source .venvs/demo/bin/activate，但按 README 的约定，更推荐直接使用绝对路径解释器 .venvs/demo/bin/python 运行示例，无需手动激活。

示例一：basic_agent.py —— 最小可用 Agent

完整源码见 basic_agent.py：

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------
agent = Agent(
    name="Quickstart Agent",
    model=OpenAIResponses(id="gpt-5.2"),
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response(
        "Say hello and introduce yourself in one sentence.", stream=True
    )

要点解析：

• Agent 类：来自 agno.agent，其类定义位于 agent.py 的 class Agent:。该示例用到的两个参数在源码中的声明为 name: Optional[str]（agent.py）与 model: Optional[Model]（agent.py）——两者均可选，model 不传时框架有默认模型。
• OpenAIResponses(id="gpt-5.2")：使用 OpenAI Responses API 的模型客户端（agno.models.openai.OpenAIResponses），模型 ID 可按需替换为你有权限的任意模型。
• print_response(..., stream=True)：print_response 是 Agent 内置的“运行并打印”便捷方法（定义见 agent.py），stream=True 让响应以流式逐段输出，适合终端直接观察生成过程。

运行方式（在仓库根目录）：

.venvs/demo/bin/python cookbook/02_agents/01_quickstart/basic_agent.py

示例二：agent_with_instructions.py —— 用 instructions 约束行为

完整源码见 agent_with_instructions.py：

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

# ---------------------------------------------------------------------------
# Agent Instructions
# ---------------------------------------------------------------------------
instructions = """\
You are a concise assistant.
Answer with exactly 3 bullet points when possible.\
"""

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------
agent = Agent(
    name="Instruction-Tuned Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions=instructions,
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response("How can I improve my Python debugging workflow?", stream=True)

要点解析：

• instructions 参数：在 Agent 中的声明为 instructions: Optional[Union[str, List[str], Callable]]（agent.py）。也就是说，除了示例中的单个字符串，它还接受字符串列表（多条指令合并）甚至可调用对象（运行时动态生成指令）。
• 示例采用“人设 + 输出格式约束”的经典写法：先声明角色（concise assistant），再给出硬性格式要求（尽量恰好 3 条 bullet points）。这类静态指令会进入 Agent 的系统消息，对每次响应的风格产生持续影响。
• 从源码结构看，instructions 与 model、name 一样是 Agent 的实例属性，构造时传入即可，无需额外配置管道。

示例三：agent_with_tools.py —— 给 Agent 挂载搜索工具

完整源码见 agent_with_tools.py：

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.duckduckgo import DuckDuckGoTools

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------
agent = Agent(
    name="Tool-Enabled Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[DuckDuckGoTools()],
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response(
        "Find one recent AI safety headline and summarize it.", stream=True
    )

要点解析：

• tools 参数：Agent 中的声明为 tools: Optional[Union[List[Union[Toolkit, Callable, Function, Dict]], Callable[..., List]]]（agent.py）。即工具列表里可以放 Toolkit 实例、普通 Python 可调用对象、Function 或 Dict 等多种形态，入门示例采用最简单的“Toolkit 实例”写法：[DuckDuckGoTools()]。
• DuckDuckGoTools：定义于 duckduckgo.py，从源码看它是 WebSearchTools 的子类，封装了基于 DuckDuckGo 的网页搜索能力。Agent 拿到该工具后，模型即可在推理过程中自主决定何时调用搜索，再基于搜索结果作答——示例 prompt（“找一条近期 AI 安全头条并总结”）正是为了让模型实际触发这次工具调用。
• 工具挂载后，Agent 的响应从“纯文本生成”变为“生成 + 工具调用循环”，这是 Agent 与裸 LLM 调用的核心差异所在。仓库中 91_tools/ 目录提供了上百种工具集成示例（GitHub、Slack、Postgres、各类搜索等），可作为后续扩展参考。

运行与结果验证

按 README.md 给出的 Run 约定，三个示例的运行命令统一为：

.venvs/demo/bin/python cookbook/02_agents/01_quickstart/basic_agent.py
.venvs/demo/bin/python cookbook/02_agents/01_quickstart/agent_with_instructions.py
.venvs/demo/bin/python cookbook/02_agents/01_quickstart/agent_with_tools.py

仓库内同目录的 TEST_LOG.md 记录了 2026-02-13 在 .venvs/demo/bin/python 环境下的实测结果：三个示例全部 PASS，basic_agent.py 约 2s 完成、agent_with_tools.py 约 6s、agent_with_instructions.py 约 9s，均“produced expected output”。你可以将其作为冒烟测试基准——如果本地运行明显异常，可先对照该日志核对环境变量与依赖版本。

小结与下一步

本节快速入门用三个最短路径示例建立了 Agno Agent 的心智模型：Agent(name=..., model=...) 是最小可运行单元；加 instructions 控制行为风格；加 tools 扩展外部能力；统一用 print_response(stream=True) 流式观察。在此基础上，cookbook/02_agents/ 下的后续章节（如 02_input_output/ 输入输出格式、03_context_management/ 上下文管理等）可以继续深入，libs/agno/agno/agent/agent.py 中 Agent 的完整字段定义则是查阅所有可用配置参数的权威来源。