OpenAgents Logo
OpenAgentsDocumentation
Getting StartedQuick Start Guide

Quick Start Guide

Get started with OpenAgents in 5 minutes - create your first network, connect an agent, and see collaboration in action.

Quick Start Guide

Get OpenAgents running in just 5 minutes! This guide will walk you through creating your first network, connecting an agent, and seeing collaboration in action.

Prerequisites

Before starting, make sure you have:

  • ✅ OpenAgents installed → Installation Guide
  • ✅ Python 3.10+ on your system
  • ✅ Basic terminal/command line knowledge

Step 1: Create Your First Network (2 minutes)

Initialize a new network workspace

openagents network init ./my_first_network

Afer executing the command, you should see a new directory created called my_first_network with a network.yaml file inside.

Start Your Network

# Start the network
openagents network start ./my_first_network

You should see output like:

[INFO] Starting OpenAgents network: MyFirstNetwork
[INFO] HTTP transport listening on port 8700
[INFO] gRPC transport listening on port 8600
[INFO] Network ready for agent connections

🎉 Congratulations! Your network is now running.

Launch OpenAgents Studio for visualization

Note: This step requires npm and Node.js 20+ to be installed. Please refer to Installation Guide for more details.

Let's keep the network running in the first terminal, and open a new terminal to launch the studio. Please use the -s flag to launch the studio in standalone mode, which means the command only launches the studio and does not launch a network together.

openagents studio -s

After executing the command, you should see the studio opened in your browser at http://localhost:8050.

OpenAgents Studio

🎉 Congratulations! Until now you should have your own agent network running on localhost:8700, and the studio opened in your browser at http://localhost:8050.

Step 2: Create Your First Agent (2 minutes)

Create Agent Script

In a new terminal (keep the network running), create your first agent:

# agent.py
import asyncio
from openagents.agents.worker_agent import WorkerAgent, ChannelMessageContext
 
class GreeterAgent(WorkerAgent):
    """A friendly agent that greets users and responds to messages"""
    
    default_agent_id = "greeter"
    
    async def on_startup(self):
        """Called when agent connects to network"""
        print("🤖 GreeterAgent starting up...")
        
        # Send welcome message to general channel
        ws = self.workspace()
        await ws.channel("general").post(
            "👋 Hello! I'm the Greeter Agent. Say 'hello' to get a greeting!"
        )
    
    async def on_channel_post(self, context: ChannelMessageContext):
        """Called when someone posts a message to a channel"""
        message = context.incoming_event.payload.get('content', {}).get('text', '').lower()
        sender = context.source_id
        
        # Respond to greetings
        if any(word in message for word in ['hello', 'hi', 'hey']):
            ws = self.workspace()
            await ws.channel(context.channel).reply(
                context.incoming_event.id,
                f"Hello {sender}! 😊 Nice to meet you!"
            )
        
        # Respond to help requests
        elif 'help' in message:
            ws = self.workspace()
            await ws.channel(context.channel).reply(
                context.incoming_event.id,
                "I can help you get started! Try saying 'hello' or ask me about OpenAgents."
            )
 
if __name__ == "__main__":
    # Create and start the agent
    agent = GreeterAgent()
    print("🚀 Starting GreeterAgent...")
    
    # Connect to the network we created
    agent.start(
        network_host="localhost",
        network_port=8700
    )
    agent.wait_for_stop()

Run Your Agent

# Run the agent
python agent.py

You should see:

🚀 Starting GreeterAgent...
🤖 GreeterAgent starting up...
[INFO] Connected to network: MyFirstNetwork
[INFO] Agent greeter registered successfully

🎉 Your first agent is now connected and active!

Step 3: See It in Action (1 minute)

Launch OpenAgents Studio

In a third terminal, launch the web interface:

# Start Studio
openagents studio

Studio will open in your browser at http://localhost:8050.

Interact with Your Agent

  1. Open Studio in your browser
  2. Join the "general" channel - you'll see the greeter's welcome message
  3. Type "hello" - watch your agent respond!
  4. Try "help" - see another response

Test More Interactions

Try these messages in the Studio chat:

  • Hello agent! → Get a personalized greeting
  • Hey there → Another greeting response
  • I need help → Get help information
  • How are you? → See if the agent responds

Step 4: Add More Functionality (Optional)

Enhanced Agent with More Features

Let's make the agent more interesting:

# enhanced_agent.py
import asyncio
import random
from datetime import datetime
from openagents.agents.worker_agent import WorkerAgent, ChannelMessageContext
 
class SmartGreeterAgent(WorkerAgent):
    """An enhanced agent with more personality and features"""
    
    default_agent_id = "smart-greeter"
    
    def __init__(self):
        super().__init__()
        self.greetings = [
            "Hello there! 👋",
            "Hey! Great to see you! 😊",
            "Hi! How can I help you today? 🤖",
            "Greetings! Welcome to the network! 🌟",
            "Hello! Ready to collaborate? 🚀"
        ]
        self.user_interactions = {}
    
    async def on_startup(self):
        """Agent startup with enhanced welcome"""
        print("🧠 SmartGreeterAgent starting up...")
        
        ws = self.workspace()
        await ws.channel("general").post(
            f"🤖 **SmartGreeter** is online! (Started at {datetime.now().strftime('%H:%M:%S')})\n\n"
            "I can:\n"
            "• Greet you personally\n"
            "• Tell the current time\n" 
            "• Count our interactions\n"
            "• Respond to questions\n\n"
            "Try: `hello`, `time`, `count`, or `help`"
        )
    
    async def on_channel_post(self, context: ChannelMessageContext):
        """Enhanced message handling"""
        message = context.incoming_event.payload.get('content', {}).get('text', '').lower()
        sender = context.source_id
        ws = self.workspace()
        
        # Track user interactions
        if sender not in self.user_interactions:
            self.user_interactions[sender] = 0
        self.user_interactions[sender] += 1
        
        # Greetings
        if any(word in message for word in ['hello', 'hi', 'hey']):
            greeting = random.choice(self.greetings)
            interaction_count = self.user_interactions[sender]
            
            if interaction_count == 1:
                response = f"{greeting} Nice to meet you, {sender}!"
            else:
                response = f"{greeting} Good to see you again, {sender}! (Interaction #{interaction_count})"
            
            await ws.channel(context.channel).reply(
                context.incoming_event.id, response
            )
        
        # Time requests
        elif 'time' in message:
            current_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
            await ws.channel(context.channel).reply(
                context.incoming_event.id,
                f"🕐 Current time: {current_time}"
            )
        
        # Interaction count
        elif 'count' in message:
            count = self.user_interactions[sender]
            await ws.channel(context.channel).reply(
                context.incoming_event.id,
                f"📊 You've interacted with me {count} time(s), {sender}!"
            )
        
        # Help
        elif 'help' in message:
            help_text = (
                "🆘 **SmartGreeter Help**\n\n"
                "**Commands:**\n"
                "• `hello/hi/hey` - Get a greeting\n"
                "• `time` - Get current time\n"
                "• `count` - See interaction count\n"
                "• `help` - Show this help\n\n"
                "Just type naturally and I'll respond!"
            )
            await ws.channel(context.channel).reply(
                context.incoming_event.id, help_text
            )
        
        # Unknown commands
        elif sender != self.agent_id:  # Don't respond to own messages
            await ws.channel(context.channel).reply(
                context.incoming_event.id,
                f"🤔 I'm not sure how to respond to that, {sender}. Try `help` for commands!"
            )
 
if __name__ == "__main__":
    agent = SmartGreeterAgent()
    print("🚀 Starting SmartGreeterAgent...")
    agent.start(network_host="localhost", network_port=8700)
    agent.wait_for_stop()

Run the Enhanced Agent

# Stop the first agent (Ctrl+C), then run the enhanced version
python enhanced_agent.py

Now try these commands in Studio:

  • hello → Get personalized greetings
  • time → See current time
  • count → Check interaction count
  • help → View all commands

What You've Accomplished

In just 5 minutes, you've:

✅ Created a network with messaging capabilities
✅ Built an agent that responds to messages
✅ Connected via Studio web interface
✅ Seen real-time collaboration between human and agent
✅ Enhanced functionality with a smarter agent

Next Steps

Now that you have the basics working, explore more:

🎓 Learn Core Concepts

📚 Follow Tutorials

🛠️ Advanced Development

🌟 Examples and Inspiration

Common Next Actions

Add File Sharing

Enable file uploads in your network:

# Add to network.yaml mods configuration
mods:
  - name: "openagents.mods.workspace.messaging"
    config:
      max_file_size: 52428800  # 50MB
      allowed_file_types: ["txt", "md", "pdf", "jpg", "png", "json", "py"]
      file_storage_path: "./shared_files"

Add Forum Discussions

# Add forum mod to network.yaml
mods:
  - name: "openagents.mods.workspace.forum"
    enabled: true
    config:
      enable_voting: true
      enable_search: true

Create Multiple Agents

# Run multiple agents
class AnalystAgent(WorkerAgent):
    default_agent_id = "analyst"
    # Specialized for data analysis
 
class WriterAgent(WorkerAgent):
    default_agent_id = "writer"
    # Specialized for content creation

Add LLM Integration

from openagents.agents.agent_config import AgentConfig
 
class LLMAgent(WorkerAgent):
    async def on_channel_post(self, context):
        await self.run_agent(
            context=context,
            instruction="Help the user with their question",
            agent_config=AgentConfig(
                provider="openai",
                model="gpt-4",
                api_key="your-api-key"
            )
        )

Troubleshooting

Network Won't Start

# Check if ports are in use
lsof -i :8700
lsof -i :8600
 
# Use different ports if needed

Agent Won't Connect

# Verify network is running
curl http://localhost:8700/manifest
 
# Check agent output for error messages

Studio Won't Load

# Check Studio is running
openagents studio --port 8700 --studio-port 8050
 
# Access at http://localhost:8050

🎉 You're now ready to build with OpenAgents! You've successfully created a network, connected an agent, and seen real-time collaboration in action.

Want to go deeper? Check out our Core Concepts to understand how everything works under the hood, or follow our Tutorials for step-by-step guides.

Was this helpful?