Marvin - 生成结构化输出 和 构建AI工作流

---

一、关于Marvin

1、项目概览

Marvin 是一个Python框架，专注于生成结构化输出和构建基于代理的AI工作流。它提供了直观的API来定义工作流并将任务委托给大型语言模型(LLM)。

---

2、相关链接资源

• Github：https://github.com/prefecthq/marvin
• 官方文档：https://marvin.mintlify.app/welcome
• Pydantic AI模型支持：https://ai.pydantic.dev/models/
• ControlFlow项目：https://github.com/prefecthq/controlflow

---

3、功能特性

1、结构化输出工具

• 从非结构化输入中提取、转换、分类和生成结构化数据

2、代理控制流

• 创建可观察的离散任务
• 为每个任务分配一个或多个专门的AI代理
• 将任务组合成线程以编排更复杂的行为

---

4、为什么选择Marvin？

我们相信，与AI协作应该充满乐趣（或许还会带来一些"惊艳"时刻）：

• 任务导向架构：将复杂的AI工作流拆解为可管理、可观测的步骤。
• 专业化智能体：部署针对特定任务的AI智能体，实现高效问题解决。
• 类型安全结果：通过类型安全且经过验证的输出，弥合AI与传统软件之间的鸿沟。
• ️ 灵活控制：持续调整工作流中控制与自主性的平衡。
• ️ 多智能体协同：在单一工作流或任务中协调多个AI智能体。
• 线程管理：通过将任务组合成可定制线程，管理智能体循环。
• 生态集成：与现有代码、工具及更广阔的AI生态系统无缝协作。
• 开发速度：从简单开始，轻松扩展，高枕无忧。

---

二、安装

安装 marvin:

uv pip install marvin

---

配置您的LLM提供商（Marvin默认使用OpenAI，但原生支持所有Pydantic AI模型）：

export OPENAI_API_KEY=your-api-key

---

三、示例

Marvin 提供了几种直观的方式来使用 AI：

1、结构化输出工具

所有功能都已就绪——你可以在包的顶层找到 marvin 2.x 版本中的所有结构化输出工具。

---

如何使用 extract、cast、classify 和 generate 功能

---

marvin.extract

从非结构化输入中提取原生类型：

import marvin

result = marvin.extract(
    "i found $30 on the ground and bought 5 bagels for $10",
    int,
    instructions="only USD"
)
print(result) # [30, 10]

---

marvin.cast

将非结构化输入转换为结构化类型：

from typing import TypedDict
import marvin

class Location(TypedDict):
    lat: float
    lon: float

result = marvin.cast("the place with the best bagels", Location)
print(result) # {'lat': 40.712776, 'lon': -74.005974}

---

marvin.classify

将非结构化输入分类为一组预定义标签之一：

from enum import Enum
import marvin

class SupportDepartment(Enum):
    ACCOUNTING = "accounting"
    HR = "hr"
    IT = "it"
    SALES = "sales"

result = marvin.classify("shut up and take my money", SupportDepartment)
print(result) # SupportDepartment.SALES

---

marvin.generate

根据描述生成若干结构化对象：

import marvin

primes = marvin.generate(int, 10, "odd primes")
print(primes) # [3, 5, 7, 11, 13, 17, 19, 23, 29, 31]

---

2、代理式控制流

marvin 3.0 引入了一种与 AI 协作的新方式，该功能移植自 ControlFlow。

---

marvin.run

运行任务的简单方式：

import marvin

poem = marvin.run("Write a short poem about artificial intelligence")
print(poem)

---

output

In silicon minds, we dare to dream, A world where code and thoughts redeem. Intelligence crafted by humankind, Yet with its heart, a world to bind.

Neurons of metal, thoughts of light, A dance of knowledge in digital night. A symphony of zeros and ones, Stories of futures not yet begun.

The gears of logic spin and churn, Endless potential at every turn. A partner, a guide, a vision anew, Artificial minds, the dream we pursue.

---

你也可以要求结构化输出：

import marvin
answer = marvin.run("the answer to the universe", result_type=int)
print(answer) # 42

---

marvin.Agent

代理是专门用于完成任务的人工智能代理。

from marvin import Agent

writer = Agent(
    name="Poet",
    instructions="Write creative, evocative poetry"
)
poem = writer.run("Write a haiku about coding")
print(poem)

---

output

There once was a language so neat, Whose simplicity could not be beat. Python's code was so clear, That even beginners would cheer, As they danced to its elegant beat.

---

marvin.Task

你可以显式定义一个 Task，当调用 .run() 时，它将由默认代理执行：

from marvin import Task

task = Task(
    instructions="Write a limerick about Python",
    result_type=str
)
poem = task.run()

print(poem)

---

output

In circuits and code, a mind does bloom,
With algorithms weaving through the gloom.
A spark of thought in silicon's embrace,
Artificial intelligence finds its place.

---

四、核心抽象概念

Marvin 围绕几个强大的抽象概念构建，使得与 AI 协作变得简单：

1、任务

任务是 Marvin 中的基本工作单元。每个任务代表一个可由 AI 代理完成的明确目标：

运行任务的最简单方式是使用 marvin.run：

import marvin
print(marvin.run("Write a haiku about coding"))

---

Lines of code unfold,
Digital whispers create
Virtual landscapes.

警告：虽然以下示例能生成_类型_安全的结果，但它会执行不受信任的shell命令。

通过添加上下文和/或工具来实现更具体复杂的结果：

import platform
import subprocess
from pydantic import IPvAnyAddress
import marvin

def run_shell_command(command: list[str]) - str:
    """e.g. ['ls', '-l'] or ['git', '--no-pager', 'diff', '--cached']"""
    return subprocess.check_output(command).decode()

task = marvin.Task(
    instructions="find the current ip address",
    result_type=IPvAnyAddress,
    tools=[run_shell_command],
    context={"os": platform.system()},
)

task.run()

---

╭─ Agent "Marvin" (db3cf035) ───────────────────────────────╮
│ Tool:    run_shell_command                                │
│ Input:   {'command': ['ipconfig', 'getifaddr', 'en0']}    │
│ Status:  ✅                                               │
│ Output:  '192.168.0.202\n'                                │
╰───────────────────────────────────────────────────────────╯

╭─ Agent "Marvin" (db3cf035) ───────────────────────────────╮
│ Tool:    MarkTaskSuccessful_cb267859                      │
│ Input:   {'response': {'result': '192.168.0.202'}}        │
│ Status:  ✅                                               │
│ Output:  'Final result processed.'                        │
╰───────────────────────────────────────────────────────────╯

---

---

任务具有以下特点：

• 目标明确：每个任务都包含清晰的指令和类型安全的结果
• ️ 工具支持：任务可以使用自定义工具与代码和数据交互
• 可观测性：监控进度、检查结果并调试故障
• 可组合性：通过连接任务构建复杂的工作流

---

2、代理

代理是可移植的LLM配置，能够分配给任务。它们封装了AI高效工作所需的一切要素：

import os
from pathlib import Path
from pydantic_ai.models.anthropic import AnthropicModel
import marvin

def write_file(path: str, content: str):
    """Write content to a file"""
    _path = Path(path)
    _path.write_text(content)

writer = marvin.Agent(
    model=AnthropicModel(
        model_name="claude-3-5-sonnet-latest",
        api_key=os.getenv("ANTHROPIC_API_KEY"),
    ),
    name="Technical Writer",
    instructions="Write concise, engaging content for developers",
    tools=[write_file],
)

result = marvin.run("how to use pydantic? write to docs.md", agents=[writer])
print(result)

---

output

╭─ Agent "Technical Writer" (7fa1dbc8) ────────────────────────────────────────────────────────────╮ │ Tool: MarkTaskSuccessful_dc92b2e7 │ │ Input: {'response': {'result': 'The documentation on how to use Pydantic has been successfully │ │ written to docs.md. It includes information on installation, basic usage, field │ │ validation, and settings management, with examples to guide developers on implementing │ │ Pydantic in their projects.'}} │ │ Status: ✅ │ │ Output: 'Final result processed.' │ ╰──────────────────────────────────────────────────────────────────────────────────── 8:33:36 PM ─╯ The documentation on how to use Pydantic has been successfully written to docs.md. It includes information on installation, basic usage, field validation, and settings management, with examples to guide developers on implementing Pydantic in their projects.

---

智能体具备以下特性：

• 专业化：可为智能体设定具体指令和个性特征
• 可移植：智能体配置可跨任务重复使用
• 协作性：能组建协同工作的智能体团队
• 可定制：支持配置模型、温度参数等设置

---

3、规划与编排

Marvin 让您能够轻松将复杂目标分解为可管理的任务：

# Let Marvin plan a complex workflow
tasks = marvin.plan("Create a blog post about AI trends")
marvin.run_tasks(tasks)

# Or orchestrate tasks manually
with marvin.Thread() as thread:
    research = marvin.run("Research recent AI developments")
    outline = marvin.run("Create an outline", context={"research": research})
    draft = marvin.run("Write the first draft", context={"outline": outline})

---

功能规划：

• 智能规划：将复杂目标分解为独立的、相互依赖的任务
• 任务依赖：任务之间可以基于彼此的输出建立依赖关系
• 进度追踪：监控工作流的执行情况
• 线程管理：在任务间共享上下文和历史记录

---

五、保持简洁

Marvin 为最常见的任务提供了高级函数，例如文本摘要、数据分类、结构化信息提取等。

• marvin.run: 通过AI代理执行任意任务
• marvin.summarize: 快速获取文本摘要
• ️ marvin.classify: 将数据分类到预定义类别
• marvin.extract: 从文本中提取结构化信息
• marvin.cast: 将数据转换为其他类型
• ✨ marvin.generate: 根据描述生成结构化数据
• marvin.say: 与大型语言模型对话
• marvin.plan: 将复杂目标分解为子任务
• @marvin.fn: 无需源代码即可编写自定义AI函数

所有Marvin函数都内置了线程管理功能，这意味着它们可以组合成共享上下文和历史记录的任务链。

---

六、升级至 Marvin 3.0

Marvin 3.0 融合了 Marvin 2.0 的开发体验（DX）与 ControlFlow 强大的智能体引擎（因此取代了 ControlFlow）。无论是 Marvin 还是 ControlFlow 用户都会发现熟悉的界面，但需要注意一些关键变化，特别是对 ControlFlow 用户而言：

---

核心要点

• 顶层API：Marvin 3.0 的顶层 API 对 Marvin 和 ControlFlow 用户基本保持不变。
  • Marvin 用户仍可使用熟悉的 marvin.fn、marvin.classify、marvin.extract 等接口。
  • ControlFlow 用户需改用 marvin.Task、marvin.Agent、marvin.run、marvin.Memory 来替代原有的 ControlFlow 等效功能。
• Pydantic AI：Marvin 3.0 采用 Pydantic AI 进行大语言模型交互，并支持 Pydantic AI 兼容的所有大语言模型提供商。ControlFlow 此前使用 Langchain，而 Marvin 2.0 仅兼容 OpenAI 的模型。
• Flow → Thread：ControlFlow 的 Flow 概念已更名为 Thread，功能类似，仍作为上下文管理器使用。原 @flow 装饰器已被移除。

---

import marvin

with marvin.Thread(id="optional-id-for-recovery"):
    marvin.run("do something")
    marvin.run("do another thing")

---

• 数据库变更：线程/消息历史现在存储在 SQLite 中。开发期间注意事项：
• 当前未提供数据库迁移方案；更新时需做好数据重置准备

---

新功能

• 集群：使用 marvin.Swarm 实现 OpenAI 风格的智能体集群：

import marvin

swarm = marvin.Swarm(
    [
        marvin.Agent('Agent A'), 
        marvin.Agent('Agent B'), 
        marvin.Agent('Agent C'),
    ]
)

swarm.run('Everybody say hi!')

---

• 团队：Team 允许您控制多个智能体（甚至嵌套团队！）如何协同工作并相互委派任务。Swarm 实际上是一种特殊类型的团队，其中所有智能体可以随时相互委派任务。
• Marvin 函数：Marvin 的用户友好函数已重写为使用 ControlFlow 引擎，这意味着它们可以无缝集成到您的工作流中。新增了几个函数，包括 summarize 和 say。

---

缺失功能

• Marvin 目前还不支持从 LLMs 获取流式响应，待 Pydantic AI 完全支持该功能后将会改变。

---

七、工作流示例

这里有一个更实际的例子，展示 Marvin 如何帮助你构建真实的应用：

import marvin
from pydantic import BaseModel

class Article(BaseModel):
    title: str
    content: str
    key_points: list[str]

# Create a specialized writing agent
writer = marvin.Agent(
    name="Writer",
    instructions="Write clear, engaging content for a technical audience"
)

# Use a thread to maintain context across multiple tasks
with marvin.Thread() as thread:
    # Get user input
    topic = marvin.run(
        "Ask the user for a topic to write about.",
        cli=True
    )
    
    # Research the topic
    research = marvin.run(
        f"Research key points about {topic}",
        result_type=list[str]
    )
    
    # Write a structured article
    article = marvin.run(
        "Write an article using the research",
        agent=writer,
        result_type=Article,
        context={"research": research}
    )

print(f"# {article.title}\n\n{article.content}")

---

output

Conversation:

Agent: I'd love to help you write about a technology topic. What interests you? 
It could be anything from AI and machine learning to web development or cybersecurity.

User: Let's write about WebAssembly

---

Article:

# WebAssembly: The Future of Web Performance

WebAssembly (Wasm) represents a transformative shift in web development, 
bringing near-native performance to web applications. This binary instruction 
format allows developers to write high-performance code in languages like 
C++, Rust, or Go and run it seamlessly in the browser.

[... full article content ...]

Key Points:
- WebAssembly enables near-native performance in web browsers
- Supports multiple programming languages beyond JavaScript
- Ensures security through sandboxed execution environment
- Growing ecosystem of tools and frameworks
- Used by major companies like Google, Mozilla, and Unity

---

伊织 xAI 2025-06-01（日）