Skip to main content
Welcome to Marvin! This quickstart guide will walk you through the three main ways to use Marvin to create AI-powered applications. You’ll learn how to:
  1. Use quick one-liners with marvin.run()
  2. Work with specialized agents using agent.run()
  3. Control tasks directly with task.run()
  4. Add advanced features like context and threads
This guide assumes you have already installed marvin. See the installation docs for instructions.

​
Quick One-Liners

The fastest way to use Marvin is with marvin.run(): 
import marvin

# Run a simple task
print(marvin.run("Write a haiku about Python programming"))

# With a specific result type
numbers = marvin.run(
    "Generate five random numbers between 1 and 10",
    result_type=list[int]
)

Indented lines flow
Functions dance with elegance
Code becomes poetry

[3, 7, 2, 9, 5]

​
Specialized Agents

Create and use specialized agents for specific types of tasks: 
from marvin import Agent

# Create a specialized agent
writer = Agent(
    name="Technical Writer",
    instructions="Write clear, engaging content for developers"
)

# Use the agent directly
article = writer.run(
    "Write a short article about Python type hints",
    result_type=str
)

print(article)

Type Hints in Python: A Clear Path to Better Code

Python's type hints bring clarity and safety to your code without sacrificing its dynamic nature. Introduced in Python 3.5, type hints allow developers to explicitly declare variable and function types, making code more maintainable and easier to understand.

Here's a quick example:

def greet(name: str) -> str:
    return f"Hello, {name}!"

Type hints help catch errors early, improve IDE support, and make your code self-documenting. While optional, they're becoming an essential tool in modern Python development.

​
Task Control

For full control over your AI workflows, create and run tasks directly: 
import httpx
from marvin import Task
from pydantic import BaseModel

def check_weather(location: str) -> str:
    url = f"https://wttr.in/{location}?format=%C+%t"
    return httpx.get(url).text

# Define a structured output type
class WeatherForecast(BaseModel):
    temperature: float
    conditions: str
    precipitation_chance: float | str = "unknown"

# Create a task with specific requirements
task = Task(
    instructions="Get the weather for San Francisco",
    result_type=WeatherForecast,
    tools=[check_weather]  # Custom tools
)

# Run the task
forecast = task.run()
print(forecast)

temperature=50.0 conditions='Partly cloudy' precipitation_chance='unknown'

​
Advanced Features

All three approaches support advanced features like context, threads, and tools: 
import marvin
from marvin import Agent, Task

# Context improves results
data = "The patient reports mild fever and fatigue."
diagnosis = marvin.run(
    "Suggest possible conditions",
    context={"medical_notes": data}
)

# Threads maintain conversation history
with marvin.Thread() as thread:
    # Ask multiple related questions
    marvin.run("What is quantum computing?")
    marvin.run("How does that relate to classical computing?")
    marvin.run("What are its practical applications?")

# Teams of agents can collaborate
researcher = Agent("Researcher")
writer = Agent("Technical Writer")
editor = Agent("Editor")

with marvin.Thread() as thread:
    research = researcher.run("Research quantum computing")
    draft = writer.run("Write an article", context={"research": research})
    final = editor.run("Edit the article", context={"draft": draft})

​
What’s Next?

You’ve seen the main ways to work with Marvin. To learn more:
  • Read about Tasks to understand how to structure AI workflows
  • Learn about Agents to create specialized AI workers
  • Explore Threads for managing conversation context
  • Check out Models to work with structured data