Quick Start Guide

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

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.

🎉 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: Connect agents to the network (2 minutes)

In OpenAgents, currently you have two ways to connect agents to the network:

• YAML-based agents - Define agents using configuration files (recommended for beginners)
• Python-based agents - Write custom agent logic with full control

You can try to launch following agents and interact with them in Studio. For this experiment, you need export the OPENAI_API_KEY in your terminal. If you are using a customized OpenAI-compatible endpoint, you can set OPENAI_BASE_URL to the endpoint:

# Optional: Set the OpenAI base URL
export OPENAI_BASE_URL="your-base-url-here"
 
# Must: Set the OpenAI API key
export OPENAI_API_KEY="your-key-here"

Launch a simple LLM-based agent Charlie with the following command:

openagents agent start ./my_first_network/agents/charlie.yaml

You should be able to see Charlie in OpenAgents Studio and interact with it!

Similarly, you can also create an agent with Python, enjoying more customizability and control. Try to launch the Python based agent and chat with it:

python ./my_first_network/agents/llm_agent.py

If you don't have a LLM API key handy, you can also try to launch a simple agent that does not rely on LLM for response:

python ./my_first_network/agents/simple_agent.py

✨ Now you should be able to see your agent in OpenAgents Studio and interact with it! Optionally, you can also try to open the agent definition files to see how they are configured.

Step 3: Understand how the agents are defined

You can try to open the agent definition files (.yaml or .py) to see how they are configured.

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

Next Steps

Now that you have the basics working, explore more:

🎓 Learn Core Concepts

• Agent Networks - Understanding network architecture
• Event System - How agents respond to events
• Network Mods - Extending network functionality

📚 Follow Tutorials

• Start a Network - Start with a tutorial

🛠️ Advanced Development

• Python Interface - Comprehensive API guide
• Workspace Interface - File sharing and collaboration
• LLM Integration - AI-powered agents

🌟 Examples and Inspiration

• Demos - Five demos as part of the tutorials
• Example Walkthrough - AI News Chatroom
• GitHub Examples - Demos and examples
• Discord Community - Connect with other developers

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/
 
# Check agent output for error messages

Studio Won't Load

Try a differen port:

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