Tasks

Define an objective, validate its result, and inspect its state

A Task holds instructions, a result type, context, and the agent assigned to it. marvin.run creates and runs a task in one call; construct a task yourself when you need dependencies or access to its state.

import marvin
from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str

task = marvin.Task(
    "Extract the contact",
    result_type=Contact,
    context={"text": "Email Ada at [e-mail]"},
)
contact = task.run()
assert task.is_successful()

result_type defaults to str. It accepts Python types, Pydantic models, dataclasses, and classification labels. The model must produce a value that passes validation; this does not verify the truth of its answer.

Dependencies

import marvin

outline = marvin.Task("Outline a short guide to Python type hints")
draft = marvin.Task("Write the guide using the outline", depends_on=[outline])
marvin.run_tasks([outline, draft])
print(draft.result)

The orchestrator waits for dependencies before running a task. See running tasks for execution and failure handling.

Agents, tools, and context

Use agents=[agent] to assign an agent, tools=[function] to expose Python functions, and context={...} to supply data. Context is included in the prompt; it is not string interpolation or a tool result.

Use one agent per task. Teams are deprecated; coordinate agents with separate tasks or Python calls.

State and validation

A task’s state is pending, running, successful, failed, or skipped. Inspect it through is_pending, is_running, is_successful, is_failed, and is_skipped. A completed task exposes its value or failure text through result.

Use Pydantic field constraints or a result_validator for application rules. See task results for examples. Set allow_fail=True or allow_skip=True to let the agent choose those outcomes. By default, running a failed task raises an error; raise_on_failure=False lets you inspect its state yourself.