Marvin – Python AI 开发框架
用类型安全的结构化输出和可编排的多智能体任务，构建可靠的 AI 工作流。
- Star 数
- ★ 6.2k
- 最近更新
- 25 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 45/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- Python 开发者需要从非结构化文本中提取结构化数据（如金额、IP 地址）时，用 marvin.extract 获得类型安全的结果。
- 不适合
- 需要稳定数据库迁移、不能接受开发期数据重置的项目
- 追求确定性输出、无法容忍LLM延迟与不可预测性的场景
这个 Agent 能做什么，适合哪些场景？
Marvin 是 PrefectHQ 推出的 Python 框架，专注于生成结构化输出和构建 agentic AI 工作流。它提供 cast、classify、extract、generate 等结构化数据工具，并引入 Task、Agent、Thread 等核心抽象，帮助开发者将复杂目标拆解为可观测、可组合的任务。Marvin 3.0 基于 Pydantic AI，支持多模型提供商，默认使用 OpenAI，也兼容所有 Pydantic AI 模型。通过 marvin.run 可快速执行任务，支持类型安全的结果输出和工具调用。其架构强调可观测性、可控性与多智能体编排，适合需要精细控制 AI 行为的开发者。
Marvin 提供一组 Python API 实现结构化输出和 agentic 工作流：marvin.extract 从非结构化文本中提取原生类型，marvin.cast 将输入转换为 TypedDict 等结构，marvin.classify 将输入分类到预定义标签，marvin.generate 按描述生成指定数量的结构化对象。核心执行模型是 Task，通过 marvin.Task 定义指令、结果类型和工具，调用 .run() 执行：先由 LLM 推理，可能调用自定义工具（如执行 shell 命令），最后生成类型安全的输出。Agent 封装模型配置、指令和工具，可分配给任务。Thread 作为上下文管理器，在多个任务间共享上下文和消息历史，支持计划（marvin.plan）和多任务编排。所有功能都内置了线程管理，可组合成链式任务。默认使用 OpenAI API，通过环境变量 OPENAI_API_KEY 认证。
- Python 开发者需要从非结构化文本中提取结构化数据（如金额、IP 地址）时，用 marvin.extract 获得类型安全的结果。
- RAG 或数据管道开发者需要将输入标准化为特定 schema 时，使用 marvin.cast 将文本转换为 TypedDict 或 Pydantic 模型。
- 客服系统开发者需要对用户请求自动分类（如账单、人力资源、IT 支持），使用 marvin.classify 映射到枚举标签。
- 需要编排多个 AI 任务的工作流，例如内容创作中先研究、后提纲、再写作，使用 Thread 共享上下文。
- 希望为任务配置专用模型（如 Anthropic Claude）的开发者，可通过 marvin.Agent 自定义模型和指令。
- 需要 AI 执行工具调用（如运行 shell 命令、读写文件）的场景，使用 Task 的 tools 参数。
如何安装或部署这个 Agent？
Marvin 发布在 PyPI 上，推荐使用 uv 安装：uv add marvin。安装后，需要配置 LLM 提供商：默认使用 OpenAI，设置环境变量 OPENAI_API_KEY=your-api-key。Marvin 也原生支持所有 Pydantic AI 模型，可按照模型文档配置。
如何使用这个 Agent？
安装并配置 API 密钥后，在 Python 中导入 marvin。快速开始：调用 marvin.run("Write a short poem about artificial intelligence") 即可执行简单任务，也可指定 result_type 获得结构化输出。定义任务时，使用 marvin.Task 设置 instructions、result_type 和 tools，然后调用 task.run()。创建 Agent 使用 marvin.Agent(name="Poet", instructions="...")，然后 agent.run()。要编排多步工作流，使用 with marvin.Thread(): 包裹 marvin.run 调用，共享上下文。也可使用 marvin.plan 自动分解复杂目标为多个任务。
这个 Agent 有哪些优点和局限？
- 类型安全的结构化输出，通过 Pydantic 模型和类型提示确保结果可用。
- 任务中心架构设计，将复杂工作流拆解为可观测、可调试的步骤。
- 支持多智能体编排和线程管理，便于组合复杂行为。
- 基于 Pydantic AI，可切换多种 LLM 提供商，避免锁定单一模型。
- 提供高层便捷函数（summarize、classify、extract 等）和底层控制 API，适合不同复杂度的需求。
- 默认依赖 OpenAI API，需要网络连接和 API 密钥，可能产生费用。
- Marvin 3.0 数据库使用 SQLite，目前没有数据库迁移机制，开发期间更新可能导致数据重置。
- 相比纯代码控制，引入 LLM 推理可能增加延迟和不可预测性，需要调试工具调用。
- 高级功能（如自定义模型）需要熟悉 Pydantic AI 生态。
这个 Agent 与同类方案有什么区别？
与 ControlFlow 相比，Marvin 3.0 合并了 ControlFlow 的 agentic 引擎，将 Flow 更名为 Thread，并替换底层 LLM 接口为 Pydantic AI（ControlFlow 旧版使用 LangChain）。对于 Marvin 2.0 用户，API 基本保持兼容但转向 Pydantic AI 模型支持。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Marvin – Python AI 开发框架 当前 | 45 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 6.2k | 25 天前 | Python | OpenAI API |
| LightAgent | 60 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 1.2k | 18 天前 | Python | OpenAI API |
| Pydantic Deep Agents | 68 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 1.1k | 12 天前 | Python | OpenAI API · Claude API |
| Fusion 软件工厂 | 71 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 1.3k | 1 天前 | TypeScript | Codex · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：README 中明确警告示例会运行不受信任的 shell 命令，但未提供权限最小化机制或用户确认流程；数据流透明度有限，仅提及 SQLite 存储线程历史；敏感数据处理未专门说明；依赖项未提供安全审计或锁定；外部影响（如文件写入、shell 执行）有示例但无防护；回滚机制未提及；来源归属仅通过 GitHub 仓库和许可证版权声明，但发布者未验证。扣分原因：缺乏权限控制、用户确认、数据流透明、敏感数据保护、依赖安全、外部影响防护、回滚和来源验证。
证据显示：README 和 pyproject.toml 描述一致，API 示例与文档相符；依赖项在 PyPI 上常见且版本明确，但未提供锁定文件；失败消息未专门说明，仅从示例中可见错误处理。扣分原因：失败消息文档不足。
证据显示：README 面向开发者，提供了多种使用场景（结构化输出、代理、任务、线程）；能力边界通过示例说明，但未明确限制；触发精度未详细说明，仅通过示例展示；环境适配支持多种 LLM 提供商和 Python 版本。扣分原因：触发精度和边界说明不足。
证据显示：README 结构清晰，包含安装、示例、核心抽象；安装说明简单明了；命名稳定性未明确承诺；示例丰富，但 FAQ 缺失；已知限制仅提及数据库迁移；许可证为 Apache-2.0，完整；版本变更记录未提供；维护责任未明确。扣分原因：缺少 FAQ、版本变更记录和维护责任说明。
证据显示：输出为结构化数据，可直接使用；边际价值高，提供多种 AI 工作流抽象；成本效益未量化，但依赖项较多。扣分原因：成本效益未评估。
证据显示：README 中的示例未提供可复现的测试；测试文件存在，但未与文档中的声明直接对应；事实与推断未明确区分。扣分原因：声明缺乏可追溯性，测试与文档脱节。
- 源码中未见：执行前用户确认开启或自行加上执行前确认；先在沙箱或测试环境跑通，确认行为后再接入真实数据。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 示例中运行不受信任的 shell 命令，存在安全风险，需谨慎使用。
- 未提供权限最小化或用户确认机制，可能执行意外操作。
- 依赖项未锁定，存在供应链风险。
- 发布者身份未验证，需自行评估信任。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
What's Changed * fix(mcp): merge custom env with os.environ for MCPServerStdio (#1296) - When users set env={"FOO": "bar"} on an MCPServerStdio, the subprocess was spawned with only those vars — missing PATH, HOME, etc., causing a TimeoutError during MCP server initialization. - Now always merges user-specified env on top of os.environ.在 GitHub 查看 ↗ -
发布说明摘录
What's New OpenAI Observability Integration (Beta) Added marvin.beta.observability.openai module that enables tracing Marvin agent calls to OpenAI's observability dashboard. When running inside Prefect flows/tasks, it automatically captures runtime context (flow_run_id, task_run_id, deployment info) and sends it as request metadata. Usage: ```python from prefect import flow, task import marvin from marvin.beta.observability.openai import observable agent = marvin.Agent(name="analyst", model="openai:gpt-4o") @task async def summarize(text: str) -> str: …在 GitHub 查看 ↗ -
发布说明摘录
MCP Server Lifecycle Fix This patch release fixes a critical issue where MCP servers were being restarted for each agent.run() call instead of staying alive for the session. What was happening When using MCP servers with agents, each agent.run() call would: 1. Start the MCP server subprocess 2. Run the agent 3. Stop the MCP server subprocess This caused unnecessary overhead and defeated the purpose of having persistent MCP connections. What this release fixes #1260: MCP servers now persist across multiple agent.run() calls within the same Thread context: …在 GitHub 查看 ↗