Quickstart

This guide will help you get started with Agentle by creating your first agent and exploring basic functionality.

Creating Your First Agent

Let’s start by creating a simple agent:

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

# Create a generation provider (Google AI in this example)
provider = GoogleGenaiGenerationProvider(
    api_key=os.environ.get("GOOGLE_API_KEY")  # Get API key from environment variable
)

# Create a simple agent
agent = Agent(
    name="Quick Start Agent",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="You are a helpful assistant who provides concise, accurate information."
)

# Run the agent
response = agent.run("What are the three laws of robotics?")

# Print the response
print(response.text)

Save this code to a file (e.g., quickstart.py) and run it:

python quickstart.py

Adding Tools

Now let’s enhance our agent by adding a tool:

def get_weather(location: str) -> str:
    """
    Get the current weather for a location.

    Args:
        location: The city or location to get weather for

    Returns:
        A string describing the weather
    """
    # In a real application, you would call a weather API here
    weather_data = {
        "New York": "Sunny, 75°F",
        "London": "Rainy, 60°F",
        "Tokyo": "Cloudy, 65°F",
        "Paris": "Partly cloudy, 70°F",
        "Sydney": "Clear, 80°F",
    }
    return weather_data.get(location, f"Weather data not available for {location}")

# Create an agent with a tool
weather_agent = Agent(
    name="Weather Assistant",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="You are a helpful assistant that can answer questions about the weather.",
    tools=[get_weather]  # Pass the function as a tool
)

# The agent will automatically use the tool when appropriate
response = weather_agent.run("What's the weather like in Tokyo?")
print(response.text)

# Ask a question that should trigger tool use
response = weather_agent.run("Can you tell me the weather in London and Paris?")
print(response.text)

Creating Structured Outputs

Let’s create an agent that returns strongly-typed results using Pydantic:

from pydantic import BaseModel
from typing import List, Optional

# Define your output schema
class WeatherForecast(BaseModel):
    location: str
    current_temperature: float
    conditions: str
    forecast: List[str]
    humidity: Optional[int] = None

# Create an agent with structured output
structured_agent = Agent(
    name="Weather Agent",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="You are a weather forecasting assistant. Provide accurate forecasts.",
    response_schema=WeatherForecast  # Define the expected response structure
)

# Run the agent
response = structured_agent.run("What's the weather like in San Francisco?")

# Access structured data with type hints
weather = response.parsed
print(f"Weather for: {weather.location}")
print(f"Temperature: {weather.current_temperature}°C")
print(f"Conditions: {weather.conditions}")
print("Forecast:")
for day in weather.forecast:
    print(f"- {day}")
if weather.humidity is not None:
    print(f"Humidity: {weather.humidity}%")

Adding Static Knowledge

Let’s create an agent with domain-specific knowledge:

from agentle.agents.knowledge.static_knowledge import StaticKnowledge

# Create an agent with static knowledge
travel_expert = Agent(
    name="Japan Travel Expert",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="You are a Japan travel expert who provides detailed information about Japanese destinations.",
    # Provide static knowledge from multiple sources
    static_knowledge=[
        # Include knowledge from a local document (if you have this file)
        # StaticKnowledge(content="data/japan_travel_guide.pdf", cache=3600),

        # Include direct text knowledge
        "Tokyo is the capital of Japan and one of the most populous cities in the world.",
        "Cherry blossom season in Japan typically runs from late March to early April.",
        "Mount Fuji is Japan's tallest mountain at 3,776 meters and is considered one of Japan's three sacred mountains.",
        "Kyoto was the imperial capital of Japan for more than 1,000 years and is famous for its temples, shrines, and traditional wooden houses."
    ]
)

# The agent will incorporate the knowledge when answering
response = travel_expert.run("What should I know about visiting Tokyo in cherry blossom season?")
print(response.text)

Creating a Multi-Agent Pipeline

Now let’s create a pipeline of specialized agents:

from agentle.agents.agent_pipeline import AgentPipeline

# Create specialized agents
research_agent = Agent(
    name="Research Agent",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="""You are a research agent focused on gathering information.
    Be thorough and prioritize accuracy over speculation."""
)

analysis_agent = Agent(
    name="Analysis Agent",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="""You are an analysis agent that identifies patterns.
    Highlight meaningful relationships and insights from the data."""
)

summary_agent = Agent(
    name="Summary Agent",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="""You are a summary agent that creates concise summaries.
    Present key findings in a logical order with accessible language."""
)

# Create a pipeline
pipeline = AgentPipeline(
    agents=[research_agent, analysis_agent, summary_agent],
    debug_mode=True  # Enable to see intermediate steps
)

# Run the pipeline
result = pipeline.run("Research the impact of artificial intelligence on healthcare")
print("\nFinal Result:")
print(result.text)

Creating a Web API

Let’s deploy an agent as a web API:

from agentle.agents.asgi.blacksheep.agent_to_blacksheep_application_adapter import AgentToBlackSheepApplicationAdapter
import uvicorn

# Create your agent
code_assistant = Agent(
    name="Code Assistant",
    description="An AI assistant specialized in helping with programming tasks.",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="""You are a helpful programming assistant.
    You can answer questions about programming languages, help debug code,
    explain programming concepts, and provide code examples.""",
)

# Convert the agent to a BlackSheep ASGI application
app = AgentToBlackSheepApplicationAdapter().adapt(code_assistant)

# Run the API server
if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

To test this API:

# In a new terminal
curl -X POST "http://localhost:8000/api/v1/agents/code_assistant/run" \
    -H "Content-Type: application/json" \
    -d '{"input": "Write a Python function to calculate the Fibonacci sequence"}'

Creating a Streamlit Interface

Let’s create a chat interface for our agent:

from agentle.agents.ui.streamlit import AgentToStreamlit

# Create your agent
travel_agent = Agent(
    name="Travel Guide",
    description="A helpful travel guide that answers questions about destinations.",
    generation_provider=provider,
    model="gemini-2.0-flash",
    instructions="""You are a knowledgeable travel guide who helps users plan trips.""",
)

# Convert the agent to a Streamlit app
streamlit_app = AgentToStreamlit(
    title="Travel Assistant",
    description="Ask me anything about travel destinations and planning!",
    initial_mode="presentation",  # Can be "dev" or "presentation"
).adapt(travel_agent)

# Run the Streamlit app
if __name__ == "__main__":
    streamlit_app()

Save this as streamlit_app.py and run:

streamlit run streamlit_app.py

Next Steps

Now that you’ve created your first agents, you can:

  1. Learn more about Agents and their capabilities

  2. Explore Tools for extending agent functionality

  3. Discover how to use Structured Outputs for type-safe responses

  4. Learn about Agent Composition for creating more complex systems

  5. See how to enhance agents with Knowledge Integration

For a comprehensive overview of all features, check out the documentation sections in the sidebar.