Marvin 3.x: Structured Outputs and Agentic Tasks in One Python Library

What Marvin Actually Solves

Marvin targets engineers who want LLM outputs that fit into typed Python code without writing prompt-engineering glue. It solves two problems at once. First, it turns unstructured text into native Python types: integers, TypedDicts, enums, and lists of those. Second, it provides a control-flow layer where you define tasks, assign agents, and let the model decide how to complete them. The intended user is a Python developer building AI features into a larger application, not a researcher experimenting with raw model APIs. The README frames it as a framework for "producing structured outputs and building agentic AI workflows," which is a fair description of the two halves of the API surface.

The Structured-Output Utilities Are the Familiar Core

The top-level functions extract, cast, classify, and generate carry over from the 2.x line. Each takes an unstructured input and a target type. extract pulls multiple instances of a type from a string, as in the example where a sentence about money yields [30, 10]. cast coerces a single value into a TypedDict or Pydantic model, with the README showing a Location TypedDict filled from a bagel shop reference. classify maps text to an Enum member, demonstrated with a support department. generate produces a requested number of items from a description, like ten odd primes. These utilities hide the prompt construction and JSON parsing. The result types are checked by Pydantic, so a malformed model response surfaces as an error rather than a silent type mismatch.

Tasks and Agents Replace Free-Form Prompting

The 3.0 additions, ported from ControlFlow, introduce marvin.run, Agent, and Task. marvin.run is a one-liner for a single objective, optionally with a result_type parameter. Agent lets you define a persona with instructions and then call run on that agent. Task is the explicit unit of work: you give it instructions, a result type, optional tools, and optional context, then call .run(). The README shows a Task that finds the current IP address, with a tool that runs shell commands and context that carries the operating system. The terminal output reveals a loop where the agent picks a tool, receives output, and finally calls a MarkTaskSuccessful callback to signal completion. This is a genuinely different pattern from a single LLM call: the model drives the sequence of tool invocations until it believes the task is done.

Installation and Configuration Are Standard but Provider-Specific

The README gives a single install command: uv add marvin. After that you must configure an LLM provider. The default is OpenAI, and the example sets OPENAI_API_KEY as an environment variable. Marvin natively supports all Pydantic AI models, which means the provider selection likely goes through Pydantic AI's configuration layer, though the README does not show the exact keys for non-OpenAI providers. You should plan to read the Pydantic AI model documentation to map your provider's API key to the right environment variable or setting. The lack of a full configuration example in the README is a minor gap for anyone not on OpenAI.

The Warning About Untrusted Shell Commands Is the Real Limitation

The README includes a warning box that says, "While the below example produces type safe results, it runs untrusted shell commands." That is the central failure mode. When you expose a tool like run_shell_command to an agent, the LLM chooses the arguments. In the example, the model runs ipconfig getifaddr en0, which is harmless, but nothing in the framework prevents it from choosing rm -rf or a command that exfiltrates data. The type safety applies to the final result, not to the side effects of tool calls. This makes Marvin a poor fit for any environment where tools have broad permissions or where the input to a task is not fully trusted. You must wrap every tool with its own validation and sandboxing; the library does not do that for you.

Comparing Marvin to a Plain Pydantic AI Workflow

The direct alternative is to use Pydantic AI on its own, since Marvin builds on it. With Pydantic AI alone, you write your own agent loop, define your own tool schemas, and handle result validation manually. Marvin gives you a higher-level API: marvin.run hides the loop, Task manages the tool-calling sequence, and the structured-output functions remove the need to write extraction prompts. The trade-off is control. In raw Pydantic AI you can inspect every model response, set custom retry logic, and decide exactly when a tool is called. Marvin's abstractions make those decisions for you, which speeds up development but reduces transparency. If your workflow needs unusual model parameters or a custom stopping condition, you will likely fight the framework.

Maintenance and License Considerations

Marvin is under the Apache-2.0 license, which permits commercial use, modification, and redistribution with attribution and without a copyleft requirement. That is a permissive license, so adopting it does not force your own code to be open source. The repository shows active maintenance: the latest release, v3.2.7, came out on 2026-03-04, with two earlier releases in January 2026. The project is not archived. Upgrading between minor versions appears to be a normal pip or uv operation, but the jump from 2.x to 3.x was substantial, moving the control flow to a new architecture. If you are on 2.x, expect migration work. The documentation lives at marvin.mintlify.app, separate from the repo, so you should verify that the docs match the installed version before relying on them.

Editorial conclusion

Adopt Marvin if you want a single Python API for structured LLM outputs and a task-centric agent loop, and if you already use Pydantic AI models. Skip it if you need fine-grained control over the underlying model calls or if you cannot tolerate the risk of LLM-chosen tool invocations; verify your provider's tool-calling reliability and your own safety constraints before wiring shell commands into a Task. The library's value stands on its type-safe results and observable task model, so confirm that your use case fits those abstractions before committing.

Official sources

1. License: Apache-2.0
2. PrefectHQ/marvin on GitHub
3. Project website
4. README
5. Releases