Agents

Agents are the intelligent, autonomous entities that power your AI workflows in Marvin. They represent AI models capable of understanding instructions, making decisions, and completing tasks.

import marvin

agent = marvin.Agent(name="Marvin")

​

What are agents?

Agents in Marvin are configurable AI entities, each with its own identity, capabilities, and even personality. They act as the “workers” in your AI workflows, responsible for executing tasks and making decisions based on their assigned instructions and available tools.

You can think of each agent as a portable LLM configuration. When you assign an agent to a task, they will work to complete it according to the instructions and tools you provide.

​

Creating agents

To create an agent, use the Agent class:

import marvin

agent = marvin.Agent(name="Marvin")

A more complex agent can be created by providing additional configuration. This example shows the main configuration options:

import marvin

agent = marvin.Agent(
    name="Data Analyst",
    description="An AI agent specialized in data analysis",
    instructions="Perform data analysis tasks efficiently and accurately.",
    tools=[analyze_data, plot_results],
    model="openai:gpt-4o",
    memories=[knowledge_base],
)

​

Agent properties

​

Name

An agent’s name is an identifier that is visible to other agents in the workflow. It is used to distinguish between agents and for logging and debugging purposes. If no name is provided, one will be randomly chosen from a list of famous AI characters.

​

Description

A description is a brief summary of the agent’s role or specialization. This information is visible to other agents, and helps them understand the agent’s capabilities and expertise.

​

Instructions

Instructions are specific instructions or guidelines for the agent to follow during task execution. These instructions are private and not shared with other agents.

​

Tools

Tools are Python functions that the agent can call to perform specific actions or computations. They are defined as a list of functions when creating an agent, and can be used to enhance the agent’s capabilities. The agent will have access to these tools in every task they are assigned to. If a task defines additional tools, the agent will have access to those as well.

​

Model

Each agent has a model, which is the LLM that powers the agent responses. This allows you to choose the most suitable model for your needs, based on factors such as performance, latency, and cost.

Marvin supports any model that is compatible with Pydantic AI. You can specify models using a string format like “openai:gpt-4” or by providing a Model instance:

import marvin
from pydantic_ai.models import OpenAIModel

# Using a string identifier
agent1 = marvin.Agent(model="openai:gpt-4")

# Using a model instance
model = OpenAIModel(name="gpt-4")
agent2 = marvin.Agent(model=model)

​

Model Settings

You can customize the behavior of an agent’s model using the model_settings parameter. This allows you to configure settings like temperature, top_p, etc:

import marvin

agent = marvin.Agent(
    name="Creative Writer",
    model="openai:gpt-4o",
    model_settings={"temperature": 0.8}
)

​

Memories

Agents can be configured with memories that provide additional context or knowledge. These memories persist across tasks and can be used to store and retrieve relevant information:

import marvin
from marvin.memory import Memory

knowledge_base = Memory(key="documentation")

agent = marvin.Agent(
    name="Support Agent",
    memories=[knowledge_base]
)

​

Delegates

Agents can be configured with a list of other agents that they can delegate work to. This is particularly useful when working with teams of agents:

import marvin

researcher = marvin.Agent(name="Researcher")
writer = marvin.Agent(name="Writer")
editor = marvin.Agent(
    name="Editor",
    delegates=[researcher, writer]
)

​

Teams

In Marvin, agents can be organized into teams to work together on tasks. A team is a way to govern how agents collaborate.

For a comprehensive guide on teams, see the Teams documentation page.

​

Swarms

A swarm is a team of multiple agents that can freely collaborate and delegate tasks to each other. This is useful for complex tasks that require different types of expertise:

import marvin
from marvin import Agent, Swarm

researcher = Agent(name="Researcher")
writer = Agent(name="Writer")
editor = Agent(name="Editor")

team = Swarm(members=[researcher, writer, editor])

result = team.run("Write a report about AI")

​

Other Team Types

Marvin supports several team configurations beyond Swarms:

• RoundRobinTeam: Rotates through its members in sequence
• RandomTeam: Randomly selects an agent for each turn

See the Teams documentation for more details and examples.

​

Assigning agents to tasks

Agents must be assigned to tasks in order to work on them. You can assign agents by passing them to the agents parameter when creating a task:

import marvin

agent = marvin.Agent(name="Poet")
task = marvin.Task(
    instructions="Write a poem about AI",
    agents=[agent]
)

If no agent is specified, Marvin will use the default agent configured in your settings.

You can also use the agent’s say method for simple conversational interactions:

import marvin

agent = marvin.Agent(name="Assistant")
response = agent.say("What is the meaning of life?")
print(response)