Tools and Context

Tools and context are two powerful ways to enhance Marvin’s capabilities, allowing agents to perform actions beyond their built-in abilities and access additional information when completing tasks.

Tools: Extending Agent Capabilities

Tools are Python functions that agents can call during task execution. They allow agents to:

Access external systems and APIs
Perform calculations or data processing
Interact with files, databases, or other resources
Execute custom business logic

import marvin
import requests

def search_web(query: str) -> str:
    """Search the web for information about the given query."""
    response = requests.get(f"https://api.search.com?q={query}")
    return response.json()["results"]

# Use the tool in a task
result = marvin.run(
    "Research the latest developments in quantum computing",
    tools=[search_web]
)

When an agent has access to a tool, it can decide when and how to use it based on the task requirements. The agent sees the tool’s name, docstring, and signature, and can call it with appropriate arguments.

Creating Effective Tools

The best tools are:

Focused: Each tool should do one thing well
Well-documented: Clear docstrings help the agent understand when and how to use the tool
Type-hinted: Type annotations help the agent understand what inputs and outputs to expect

from typing import Annotated
from pydantic import Field

# Define custom types with descriptions
ZipCode = Annotated[str, Field(description="A 5-digit US ZIP code")]
Temperature = Annotated[float, Field(description="Temperature in Fahrenheit")]

def get_weather(location: ZipCode) -> Temperature:
    """Get the current temperature for the specified ZIP code."""
    # Implementation details...
    return 72.5

Providing Tools

Tools can be provided at different levels:

# To a specific task
task_result = marvin.run("Check the weather", tools=[get_weather])

# To an agent (available for all tasks the agent performs)
weather_agent = marvin.Agent(
    name="WeatherBot",
    instructions="You provide weather information",
    tools=[get_weather, get_forecast]
)

# To a thread (available for all tasks in the thread)
with marvin.Thread() as thread:
    thread.tools = [get_weather, get_forecast]
    marvin.run("What's the weather like?")
    marvin.run("Will it rain tomorrow?")

Context: Providing Additional Information

Context is additional information you provide to a task or agent to help it generate better responses. Unlike tools (which are functions the agent can call), context is static data that informs the agent’s understanding.

import marvin

# Provide context to a task
response = marvin.run(
    "Summarize the patient's condition",
    context={
        "medical_records": "Patient presents with fever (101.2°F), cough, and fatigue...",
        "patient_history": "42-year-old male with history of asthma...",
        "lab_results": "White blood cell count elevated at 12,000..."
    }
)

Context can include:

Background information
User preferences or history
Data to analyze or reference
Previous conversation history
System state or configuration

Using Context Effectively

For best results with context:

Be selective: Include only relevant information to avoid overwhelming the agent
Structure appropriately: Organize complex context into clear sections
Use descriptive keys: Name context variables clearly so the agent understands what each piece represents

# Example of well-structured context
context = {
    "user_profile": {
        "name": "Alex",
        "preferences": ["science fiction", "technology", "hiking"],
        "reading_level": "advanced"
    },
    "previous_recommendations": [
        "The Three-Body Problem",
        "Project Hail Mary"
    ]
}

recommendation = marvin.run(
    "Recommend a book Alex might enjoy",
    context=context
)

Context in Prompts

You can reference context directly in your prompts using string formatting:

import marvin

user_data = {"name": "Jamie", "goal": "lose weight"}

plan = marvin.run(
    "Create a fitness plan for {name} who wants to {goal}",
    context=user_data
)

Combining Tools and Context

Tools and context work together to create powerful AI workflows:

import marvin
import pandas as pd

def analyze_data(data: list[dict]) -> dict:
    """Analyze the provided data and return statistics."""
    df = pd.DataFrame(data)
    return {
        "mean": df.mean().to_dict(),
        "median": df.median().to_dict(),
        "correlation": df.corr().to_dict()
    }

# Combine tools and context
sales_data = [
    {"product": "A", "price": 10, "units": 100},
    {"product": "B", "price": 15, "units": 50},
    # ...more data
]

analysis = marvin.run(
    "Analyze our sales data and recommend pricing strategy",
    tools=[analyze_data],
    context={
        "sales_data": sales_data,
        "business_goal": "Increase revenue by 20% this quarter",
        "competitor_prices": {"A": 12, "B": 14}
    }
)

In this example:

The context provides the data and business information
The tool gives the agent the ability to perform statistical analysis
Together, they enable the agent to make informed recommendations

Best Practices

Security: Only provide tools that you’re comfortable with the agent using
Error handling: Ensure tools handle errors gracefully and provide helpful error messages
Complexity: Start with simple tools and context, then add complexity as needed
Testing: Test your tools independently before providing them to agents
Observability: Monitor tool usage to understand how agents are using them

By effectively combining tools and context, you can create AI workflows that leverage both the reasoning capabilities of large language models and the precision of traditional code.

Get Started

Concepts

Integrations

Functions

Patterns

Community

Tools and Context

Tools: Extending Agent Capabilities

Creating Effective Tools

Providing Tools

Context: Providing Additional Information

Using Context Effectively

Context in Prompts

Combining Tools and Context

Best Practices

​Tools: Extending Agent Capabilities

​Creating Effective Tools

​Providing Tools

​Context: Providing Additional Information

​Using Context Effectively

​Context in Prompts

​Combining Tools and Context

​Best Practices

Tools: Extending Agent Capabilities

Creating Effective Tools

Providing Tools

Context: Providing Additional Information

Using Context Effectively

Context in Prompts

Combining Tools and Context

Best Practices