Inputs

Agentle agents can process a wide variety of input types out-of-the-box, making it simple to work with different data formats without complex conversions.

Basic Input Types

Here are the most common input types you can pass to the run method:

from agentle.agents.agent import Agent
from agentle.generations.providers.google.google_genai_generation_provider import GoogleGenaiGenerationProvider

# Create a basic agent
agent = Agent(
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="You are a versatile assistant that can analyze different types of data."
)

# String input (simplest case)
agent.run("What is the capital of Japan?")

# Pandas DataFrame
import pandas as pd
df = pd.DataFrame({
    "Country": ["Japan", "France", "USA"],
    "Capital": ["Tokyo", "Paris", "Washington DC"],
    "Population": [126.3, 67.8, 331.9]
})
agent.run(df)  # Automatically converts to markdown table

# Image input (for multimodal models)
from PIL import Image
img = Image.open("chart.png")
agent.run(img)  # Automatically handles image format

# Dictionary/JSON
user_data = {
    "name": "Alice",
    "interests": ["AI", "Python", "Data Science"],
    "experience_years": 5
}
agent.run(user_data)  # Automatically formats as JSON

Advanced Input Types

Agentle also supports more specialized input formats:

# NumPy array
import numpy as np
data = np.array([[1, 2, 3], [4, 5, 6]])
agent.run(data)  # Automatically formats array

# Date and time
from datetime import datetime
agent.run(datetime.now())  # Formatted as ISO string

# File path
from pathlib import Path
agent.run(Path("report.txt"))  # Reads and processes file content

# Pydantic model
from pydantic import BaseModel

class UserProfile(BaseModel):
    name: str
    age: int
    interests: list[str]

profile = UserProfile(name="Bob", age=28, interests=["AI", "Robotics"])
agent.run(profile)  # Automatically formats model as JSON

# File-like objects
from io import StringIO, BytesIO
text_io = StringIO("This is some text data from a stream")
agent.run(text_io)  # Reads content from StringIO

Custom Message Structures

For more control, you can create custom message structures:

from agentle.generations.models.messages.user_message import UserMessage
from agentle.generations.models.messages.assistant_message import AssistantMessage
from agentle.generations.models.messages.developer_message import DeveloperMessage
from agentle.generations.models.message_parts.text import TextPart

# Create a conversation with multiple message types
messages = [
    # System instructions (not visible to the user)
    DeveloperMessage(parts=[
        TextPart(text="You are a helpful travel assistant that speaks in a friendly tone.")
    ]),

    # User's initial message
    UserMessage(parts=[
        TextPart(text="I'm planning a trip to Japan in April.")
    ]),

    # Previous assistant response in the conversation
    AssistantMessage(parts=[
        TextPart(text="That's a wonderful time to visit Japan! Cherry blossoms should be in bloom.")
    ]),

    # User's follow-up question
    UserMessage(parts=[
        TextPart(text="What cities should I visit for the best cherry blossom viewing?")
    ])
]

# Pass the complete conversation to the agent
result = agent.run(messages)

Multi-Part Messages

Each message can contain multiple parts of different types, enabling rich multimodal interactions:

from agentle.generations.models.messages.user_message import UserMessage
from agentle.generations.models.message_parts.text import TextPart
from agentle.generations.models.message_parts.file import FilePart
from agentle.generations.tools.tool import Tool

# Define a simple weather tool
def get_weather(location: str) -> str:
    """Get weather for a location"""
    return f"Simulated weather data for {location}"

# Create a message with different part types
message = UserMessage(
    parts=[
        # Text part for regular text input
        TextPart(text="Can you analyze this image and data?"),

        # File part for image analysis (multimodal models)
        FilePart(
            data=open("vacation_photo.jpg", "rb").read(),
            mime_type="image/jpeg"
        ),
    ]
)

# Run the agent with the multi-part message
result = agent.run(message)

Context Object

For maximum control, you can create a Context object to manage complete conversations:

from agentle.agents.context import Context
from agentle.generations.models.messages.user_message import UserMessage
from agentle.generations.models.messages.developer_message import DeveloperMessage
from agentle.generations.models.message_parts.text import TextPart
from agentle.agents.step import Step

# Create a custom context with specific messages
context = Context(
    messages=[
        DeveloperMessage(parts=[
            TextPart(text="You are a travel planning assistant with expertise in budgeting.")
        ]),
        UserMessage(parts=[
            TextPart(text="I want to plan a 7-day trip to Europe with a $3000 budget.")
        ])
    ],
    # Optionally track conversation steps
    steps=[
        Step(type="user_input", content="Initial travel budget query")
    ]
)

# Run the agent with the custom context
result = agent.run(context)

Automatic Type Conversion

Agentle automatically handles type conversion for most input types:

  1. DataFrames are converted to markdown tables

  2. Images are encoded appropriately for multimodal models

  3. JSON/dictionaries are formatted as JSON strings

  4. NumPy arrays are formatted to be readable

  5. File paths are read and content is extracted

  6. Pydantic models are serialized to JSON

  7. File-like objects have their content extracted

This automatic conversion simplifies working with different data types and allows you to focus on your application logic rather than data formatting.