Skip to main content
In this guide, we’ll build a research assistant agent that can search the web, analyze information, and create reports. By the end, you’ll understand the core concepts of building agents with Slide.
Requirements: Python 3.11 or higher

​
What We’re Building

We’ll create an agent that can:
  • Search for information on any topic
  • Analyze and summarize findings
  • Save research reports to files
  • Remember previous conversations
1

Set Up Your Project

First, create a new project directory:
mkdir research-agent
cd research-agent
Install the required packages:
2

Create Your First Agent

Create a file called agent.py:
import asyncio
from tyler import Agent, Thread, Message, EventType
from lye import WEB_TOOLS, FILES_TOOLS

async def main():
    # Create your agent
    agent = Agent(
        name="research-assistant",
        model_name="gpt-4o",
        purpose="To help with research by finding, analyzing, and summarizing information",
        tools=[
            *WEB_TOOLS,     # Can search and fetch web content
            *FILES_TOOLS    # Can read and write files
        ]
    )
    
    # Create a conversation thread
    thread = Thread()
    thread.add_message(Message(
        role="user",
        content="Research the latest developments in renewable energy and create a summary"
    ))
    
    # Watch the agent work in real-time
    print("🔍 Researching renewable energy...\n")
    async for event in agent.stream(thread):
        # Show content as it's generated
        if event.type == EventType.LLM_STREAM_CHUNK:
            print(event.data['content_chunk'], end="", flush=True)
        # Show when tools are used
        elif event.type == EventType.TOOL_SELECTED:
            print(f"\n\n🔧 Using {event.data['tool_name']}...", flush=True)
        elif event.type == EventType.TOOL_RESULT:
            print(f"✓ Done\n", flush=True)

if __name__ == "__main__":
    asyncio.run(main())
Choosing between .stream() and .run():
  • Use agent.stream(thread) for:
    • Chat interfaces and real-time UIs
    • Watching the agent work (great for debugging)
    • Progressive UI updates as content generates
  • Use await agent.run(thread) for:
    • Batch processing and automation
    • Testing (when you just need the final result)
    • Simple scripts where streaming isn’t needed
Most interactive applications will want .stream() - it’s what makes agents feel alive!
3

Run Your Agent

  • uv
  • python
uv run agent.py
When you run the agent, here’s what happens:
  1. Thread Creation: A conversation thread is created to hold messages
  2. Message Processing: The agent receives your message and plans its approach
  3. Tool Usage: The agent uses web search tools to find information
  4. Response Generation: The agent synthesizes findings into a response

​
Understanding What Happened

When you stream, you get real-time events showing everything your agent does: 
async def main():
    thread = Thread()
    thread.add_message(Message(
        role="user",
        content="What are the top 3 renewable energy breakthroughs in 2024?"
    ))
    
    # Stream events to see everything in real-time
    async for event in agent.stream(thread):
        if event.type == EventType.LLM_REQUEST:
            print("🤔 Agent is thinking...")
        elif event.type == EventType.TOOL_SELECTED:
            print(f"🔧 Calling {event.data['tool_name']}...")
        elif event.type == EventType.TOOL_RESULT:
            print(f"✓ Got results")
        elif event.type == EventType.LLM_STREAM_CHUNK:
            # Print response as it's generated
            print(event.data['content_chunk'], end="", flush=True)
        elif event.type == EventType.EXECUTION_COMPLETE:
            print("\n\n✅ Done!")
Non-streaming alternative: If you just want the final result without watching the process:
result = await agent.run(thread)
print(result.content)
This is useful for batch processing or automation where you don’t need real-time updates.

​
Add Persistence to Your Agent

Let’s upgrade the agent to maintain conversation history: 
import asyncio
from tyler import Agent, Thread, Message, ThreadStore, FileStore
from lye import WEB_TOOLS, FILES_TOOLS

async def create_agent_with_persistence():
    # Set up persistent storage
    thread_store = await ThreadStore.create("sqlite+aiosqlite:///research.db")
    file_store = await FileStore.create(base_path="./research_files")
    
    # Create agent with persistence
    agent = Agent(
        name="research-assistant",
        model_name="gpt-4",
        purpose="To help with research and maintain our conversation history",
        tools=[*WEB_TOOLS, *FILES_TOOLS],
        thread_store=thread_store,
        file_store=file_store
    )
    
    return agent, thread_store

async def main():
    agent, thread_store = await create_agent_with_persistence()
    
    # Try to resume previous conversation
    thread_id = "main-research"
    try:
        thread = await thread_store.get_thread(thread_id)
        print("📚 Resuming previous research session...")
        print(f"   Found {len(thread.messages)} previous messages")
    except:
        thread = Thread(id=thread_id)
        print("🆕 Starting new research session...")
    
    # Add new message
    message = Message(
        role="user",
        content="What did we discuss last time? If this is our first conversation, tell me about yourself."
    )
    thread.add_message(message)
    
    # Process
    result = await agent.run(thread)
    
    # Save the conversation
    await thread_store.save_thread(result.thread)
    
    # Print response
    for msg in result.new_messages:
        if msg.role == "assistant":
            print(f"\n🤖 {msg.content}")

if __name__ == "__main__":
    asyncio.run(main())

​
Interactive Research Session

Let’s create an interactive version where you can have a conversation: 
async def interactive_session():
    agent, thread_store = await create_agent_with_persistence()
    
    # Load or create thread
    thread_id = "interactive-research"
    try:
        thread = await thread_store.get_thread(thread_id)
        print("📚 Resuming previous session...")
    except:
        thread = Thread(id=thread_id)
        print("🆕 Starting new session...")
        print("💡 Try asking me to research any topic!")
    
    print("\nType 'exit' to end the session\n")
    
    while True:
        # Get user input
        user_input = input("You: ")
        if user_input.lower() in ['exit', 'quit']:
            break
        
        # Add message to thread
        message = Message(role="user", content=user_input)
        thread.add_message(message)
        
        # Process with agent
        print("\n🤖 Thinking...", end="", flush=True)
        result = await agent.run(thread)
        
        # Clear thinking message
        print("\r" + " " * 20 + "\r", end="")
        
        # Display response
        for msg in result.new_messages:
            if msg.role == "assistant":
                print(f"🤖 Assistant: {msg.content}\n")
            elif msg.role == "tool":
                print(f"   [Used {msg.name}]")
        
        # Save conversation
        await thread_store.save_thread(result.thread)
        thread = result.thread
    
    print("\n👋 Session saved. See you next time!")

if __name__ == "__main__":
    asyncio.run(interactive_session())

​
Understanding Tools

Let’s explore what tools your agent can use: 
# See available tools
from lye import WEB_TOOLS, FILES_TOOLS, IMAGE_TOOLS

print("🔧 Web Tools:")
for tool in WEB_TOOLS:
    print(f"   - {tool['definition']['name']}: {tool['definition']['description']}")

print("\n📁 File Tools:")
for tool in FILES_TOOLS:
    print(f"   - {tool['definition']['name']}: {tool['definition']['description']}")
You can also give your agent specific tools: 
from lye.web import search, fetch
from lye.files import write_file

agent = Agent(
    name="focused-researcher",
    model_name="gpt-4",
    purpose="To search and save information",
    tools=[search, fetch, write_file]  # Only these specific tools
)

​
Debugging Your Agent

​
Basic Logging

Enable detailed logging to see what your agent is doing: 
import logging

# Enable debug logging
logging.basicConfig(level=logging.INFO)

​
Advanced tracing with Weave

For comprehensive debugging and observability, Slide integrates with Weights & Biases Weave. Weave provides:
  • Visual traces of every agent action and decision
  • LLM call tracking with inputs, outputs, and token usage
  • Tool execution monitoring to see which tools were called and their results
  • Performance insights to identify bottlenecks
  • Error tracking with full context
import weave

# Initialize Weave tracing
weave.init("my-research-agent")

# Now all agent operations will be traced automatically
# View traces at https://wandb.ai/your-username/my-research-agent
Weave traces are invaluable for debugging complex agent behaviors. You can see exactly what prompts were sent to the LLM, what tools were called, and how the agent made its decisions.

​
Next steps

You’ve built your first agent! Here’s what to explore next:

Adding More Tools

Give your agent more capabilities

Streaming Responses

Build real-time interactive agents

Testing Your Agent

Ensure your agent behaves correctly

Deploy to Slack

Turn your agent into a Slack agent

​
Tips for Success

The purpose parameter significantly affects agent behavior. Be specific:
# Good
purpose="To research technology topics and create detailed, well-sourced reports"

# Too vague
purpose="To help with stuff"
Only give your agent the tools it needs:
# For a research agent
tools=[*WEB_TOOLS, *FILES_TOOLS]

# For an image analysis agent
tools=[*IMAGE_TOOLS, *FILES_TOOLS]

# For a data processing agent
tools=[*FILES_TOOLS]
Always handle potential errors:
try:
    result = await agent.run(thread)
except Exception as e:
    print(f"❌ Error: {e}")
    # Handle gracefully
Your agent can handle various file types out of the box. For enhanced capabilities:
  • Scanned PDFs: Install poppler for OCR support
This is optional - your agent will work fine without it for most use cases.