developing-genkit-python

Genkit Python

使用一套 SDK，在 Python 中构建 AI 功能——生成、流式处理、工具、工作流和多轮 Agent。

前置条件

• Python 3.10+ 和 uv（安装）
• Genkit CLI：如果缺少 genkit --version，请运行 npm install -g genkit-cli

要创建新应用？请参阅设置。要查看模式？请参阅示例。

Hello World

from genkit import Genkit
from genkit_google_genai import GoogleAI

ai = Genkit(
    plugins=[GoogleAI()],
    model='googleai/gemini-flash-latest',
)

async def main():
    response = await ai.generate(prompt='Tell me a joke about Python.')
    print(response.text)

if __name__ == '__main__':
    ai.run_main(main())

Agent（Beta）

支持历史记录、类型化状态、人工审批、分支和后台任务的多轮聊天。从这里开始：Agent。

chat = agent.chat()
res = await chat.send('Hello')           # AgentResponse
turn = chat.send_stream('Hello')         # AgentTurn — .stream / .response

更多内容：会话 · 人在回路中 · 分支 · 后台任务 · 状态 · 制品 · 自定义 · HTTP

导入

• Google AI：from genkit_google_genai import GoogleAI
• Agent：from genkit.agent import InMemorySessionStore, ...
• 中间件：from genkit_middleware import Middleware, ToolApproval, ...
• FastAPI：from genkit_fastapi import serve_agent, serve_flow
• 评估：from genkit_evaluators import register_genkit_evaluators

工作流

1. Agent 还是工作流？ 如果任务是对话式、多轮的，或被描述为“Agent”“助手”或“聊天机器人”，请使用 ai.define_agent 构建（参见 Agent），而不是在工作流中手动编写 generate + 工具循环。只有在单次、无状态生成时才使用普通工作流。
2. 设置 GEMINI_API_KEY。使用带前缀的模型 ID（googleai/gemini-flash-latest）。
3. 对于 Genkit 应用，请通过 ai.run_main(main()) 进入（尤其是在 genkit start 下运行时）。参见常见错误。
4. 使用开发工作流运行（genkit start + Dev UI）。
5. 通过跟踪记录进行验证，不要盲目运行。直接运行应用（uv run）不会捕获开发跟踪记录。有关如何运行应用并捕获跟踪记录，请参阅 Genkit CLI。
6. 遇到问题？先查看常见错误。

Genkit CLI（推荐）

genkit start 会以无侵入的方式包装任何使用 Genkit 库的 Python 程序，在不做任何更改的情况下运行程序，同时捕获每个 Genkit 操作的跟踪记录，让你能够证明工具确实被调用，并从终端检查模型的输入和输出，即使是无头检查也可以。它会转发标准输入和标准输出，因此依赖 stdin/stdout 的交互式 CLI 工具也能正常工作。直接运行应用（uv run）会跳过跟踪记录捕获，让你只能盲目调试。

主要用法（默认）： 在常用运行命令前加上 genkit start --。这样会收集程序运行的任何 Genkit 代码的遥测数据，无论它是由开发 UI、你自己的 Web 服务器/Web UI 还是普通脚本触发的：

genkit start -- uv run src/main.py
genkit start --noui -- uv run src/main.py   # same, without the Dev UI (still a persistent server)

genkit start 会一直运行，直到你按 Ctrl+C 将其停止。这对于常见场景来说是预期且正确的做法：例如 Web/移动应用调用的服务器，或由你自行退出的交互式 CLI。--noui 只会关闭 Dev UI；它并非单次运行命令，也不会自行退出。在自动化/非交互式场景中，不要将 genkit start 用作阻塞步骤；这种情况下请使用 flow:run（如下）。

非交互式用法（Agent/CI）： 在 -- 前添加全局标志 --non-interactive，这样 CLI 会使用默认值，并且不会因提示而阻塞（例如首次运行时的分析数据收集提示）：genkit start --non-interactive -- uv run src/main.py（flow:run 也适用）。

运行 flow（flow:run）： 从 CLI 按名称调用指定的 flow。在 -- 后附上运行命令，以便仅为此次运行启动运行时（命令会按原样运行以注册你的 flows）：

genkit flow:run myFlow '{"data": "input"}' -- uv run src/main.py

此命令会自行终止：它会运行一次 flow，打印一个 Trace ID，然后退出，因此适合进行快速的非交互式检查（与 genkit start 不同）。注意：flow:run 运行的是 flows（@ai.flow()），而不是 Agent；你无法直接对 Agent（ai.define_agent）运行 flow:run。要从 CLI 测试 Agent，请将一次交互封装在一个临时 flow 中并运行它（参见 Agents）。

使用跟踪记录进行调试： 这是查看提示词、模型输入/输出、工具调用、延迟和错误的最快方式。在任何 genkit start 运行后，都可以从终端检查跟踪记录：

genkit trace:list                        # find recent trace IDs
genkit trace:get <traceId>               # full trace details (inputs, outputs, tool calls, errors)
genkit trace:get <traceId> --format json # machine-readable JSON, safe to pipe into jq or other parsers

如需机器可读的输出，请传入 --format json，以获取可通过管道传递给 jq 或其他解析器的纯净 JSON。默认输出面向人工阅读（含横幅/日志行，大型跟踪记录可能会被截断），因此不要直接将这种格式通过管道传递；请使用 --format json、grep 或 Dev UI 跟踪记录查看器。

完整的检查清单和 Dev UI 操作指南，请参见 Dev Workflow。

参考资料

• 示例：结构化输出、流式传输、flows、工具、嵌入。
• 设置：新项目初始化和插件。
• 常见错误：遇到问题时请先阅读。
• FastAPI：HTTP、genkit_fastapi_handler、并行 flows。
• Dotprompt：.prompt 文件和辅助工具。
• 评估：评估器和数据集。
• 开发工作流：genkit start、Dev UI、检查清单。
• Agent（Beta）：多轮 API。