Agents¶

The core building block of Agentle is the Agent class. This page explains how to create and customize agents for different use cases.

Basic Agent Creation¶

Here’s how to create a basic agent:

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

# Create a general-purpose agent
agent = Agent(
    name="Basic Agent",
    description="A helpful assistant for general purposes.",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="You are a helpful assistant who provides accurate information."
)

Agent Parameters¶

The Agent class accepts the following key parameters:

Parameter	Description
`name`	A unique name for the agent
`description`	Optional description of the agent’s purpose and capabilities
`generation_provider`	The provider that handles generation (e.g., GoogleGenaiGenerationProvider)
`model`	The specific model to use (e.g., “gemini-2.0-flash”)
`instructions`	Detailed instructions that guide the agent’s behavior
`tools`	Optional list of tools/functions the agent can use
`response_schema`	Optional Pydantic model for structured outputs
`static_knowledge`	Optional knowledge sources to enhance the agent’s capabilities
`document_parser`	Optional custom parser for knowledge documents

Using ModelKind for Provider Independence¶

Agentle provides a powerful abstraction called ModelKind that decouples your code from specific provider model names. Instead of using provider-specific model identifiers, you can use standardized capability categories:

from agentle.agents.agent import Agent
from agentle.generations.providers.google.google_generation_provider import GoogleGenerationProvider

# Using provider-specific model name
agent1 = Agent(
    generation_provider=GoogleGenerationProvider(),
    model="gemini-2.0-flash",  # Only works with Google
    instructions="You are a helpful assistant."
)

# Using ModelKind for provider-agnostic code
agent2 = Agent(
    generation_provider=GoogleGenerationProvider(),
    model="category_standard",  # Works with any provider
    instructions="You are a helpful assistant."
)

Available ModelKind Categories¶

ModelKind	Description
`category_nano`	Smallest, fastest, most cost-effective models (e.g., GPT-4.1 nano)
`category_mini`	Small but capable models (e.g., GPT-4.1 mini, Claude Haiku)
`category_standard`	Mid-range, balanced performance (e.g., Claude Sonnet, Gemini Flash)
`category_pro`	High performance models (e.g., Gemini Pro, GPT-4 Turbo)
`category_flagship`	Best available models from each provider (e.g., Claude Opus, GPT-4.5)
`category_reasoning`	Specialized for complex reasoning tasks
`category_vision`	Optimized for multimodal capabilities with image/video processing
`category_coding`	Specialized for programming tasks
`category_instruct`	Fine-tuned for instruction following

Benefits of ModelKind¶

Using ModelKind provides several important benefits:

Provider Independence: Your code works with any AI provider without modification
Future-Proof: When providers release new models, only the internal mapping tables need to be updated
Capability-Based Selection: Select models based on capabilities rather than provider-specific names
Simplified Failover: When using FailoverGenerationProvider, each provider automatically maps to its equivalent model

# Create a failover provider with multiple underlying providers
from agentle.generations.providers.failover.failover_generation_provider import FailoverGenerationProvider
from agentle.generations.providers.google.google_generation_provider import GoogleGenerationProvider
from agentle.generations.providers.openai.openai import OpenaiGenerationProvider

failover = FailoverGenerationProvider(
    generation_providers=[
        GoogleGenerationProvider(),
        OpenaiGenerationProvider(api_key="your-openai-key")
    ]
)

# Using a specific model would fail with providers that don't support it
# agent = Agent(generation_provider=failover, model="gpt-4o")  # Will fail for Google

# Using ModelKind ensures compatibility across all providers
agent = Agent(
    generation_provider=failover,
    model="category_pro",  # Mapped to appropriate model by each provider
    instructions="You are a helpful assistant."
)

How ModelKind Works¶

Behind the scenes, Agentle uses a decorator that:

Intercepts calls to the provider’s create_generation_async method
Checks if the model parameter is a ModelKind value
Calls the provider’s map_model_kind_to_provider_model method to get the provider-specific model name
Substitutes this mapped value before the actual provider method is called

Each provider implements its own mapping function to translate ModelKind values to the most appropriate model for that provider.

Creating Specialized Agents¶

You can create agents specialized for particular domains by customizing the instructions and other parameters:

# Create a travel agent
travel_agent = Agent(
    name="Travel Guide",
    description="A helpful travel guide that answers questions about destinations.",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="""You are a knowledgeable travel guide who helps users plan trips.
    You provide information about destinations, offer travel tips, suggest itineraries,
    and answer questions about local customs, attractions, and practical travel matters."""
)

# Create a coding assistant
coding_agent = Agent(
    name="Coding Assistant",
    description="An expert in writing and debugging code across multiple languages.",
    generation_provider=GoogleGenaiGenerationProvider(),
    model="gemini-2.0-flash",
    instructions="""You are a coding expert who helps with programming tasks.
    You can write code, debug issues, explain concepts, and provide best practices
    across languages like Python, JavaScript, Java, C++, and others."""
)

Running Agents¶

The primary way to interact with agents is through the run method:

# Simple string input
result = agent.run("What is the capital of France?")
print(result.text)

# With a custom message
from agentle.generations.models.messages.user_message import UserMessage
from agentle.generations.models.message_parts.text import TextPart

message = UserMessage(parts=[TextPart(text="Tell me about Paris")])
result = agent.run(message)
print(result.text)

Agent Response Structure¶

When you call agent.run(), you get back a response object with these key properties:

Property	Description
`text`	The text response from the agent
`parsed`	The structured output (if a response_schema was provided)
`generation`	The complete generation object with the agent’s response

Advanced Agent Configuration¶

For more advanced use cases, you can:

Add tools to enable function calling capabilities
Incorporate static knowledge from documents or URLs
Define structured output schemas with Pydantic
Combine agents into pipelines or teams
Deploy agents as APIs or UIs

These topics are covered in detail in their respective documentation sections.