Skip to main content

​
Overview

MeshAgent is an end-to-end platform for building, deploying, and hosting AI agents. MeshAgent integrates AI agents and human teams in real time by bundling LLM orchestration, tool integration, real-time messaging, observability, and deployment so you can ship and share agents in minutes instead of weeks. To stay up to date with MeshAgent releases, ask questions, and share feedback with our team, join our Discord Server. We also publish blogs highlighting major updates from each new release.

​
In this guide you will learn how to:

  1. Create a MeshAgent account and project in MeshAgent Studio
  2. Install the MeshAgent CLI
  3. Connect to your first MeshAgent Room and start a useful process-based agent from the CLI

​
Prerequisites

Before you start, make sure your machine matches the appropriate requirements. If you’ve never set up Python, pip, or uv before, follow the Machine Setup Guide first, then return here.

​
Key Concepts

  • Projects: Groups related Rooms and the Agents that serve them. It is best to create a different Project for each use case.
  • Rooms: A dedicated space for humans and Agents to collaborate in real time.
  • Agents: MeshAgent provides process-backed agents that support multiple channels including chat, mail, queues, and toolkit-style calls while keeping one shared identity, rules setup, and tool configuration. Once deployed, agents are automatically available as a project service (available in all rooms in the project) or a room service (available only in the room they’re deployed to).

​
Setup Guide

​
Step 1: Create an account and project:

  1. In a browser, go to meshagent.com. Sign up or sign into MeshAgent Studio.
  2. Create a new project from MeshAgent Studio or using the MeshAgent CLI meshagent project create my-new-project
  3. Ensure your project has credits to start a room. Go to the Billing page to check your credits in the project. All new accounts start with $5.

​
Step 2: Install MeshAgent

Choose your preferred method: 
brew tap meshagent/homebrew-meshagent
# install the latest version
brew install meshagent
# Display the help
meshagent --help

​
Option 2: Virtual environment installation (for development with Python SDK)

To install the CLI in a virtual environment: Ensure you are in the appropriate project folder and have activated your virtual environment. (The virtual environment is active when the terminal prompt starts with venv.) If you need help with your machine setup check out our Machine Setup Guide for Python. Once activated, you can install all the MeshAgent packages, or exclusively the MeshAgent CLI. 
pip install "meshagent[cli]" # or "meshagent[all]"

​
Step 3: Use the MeshAgent CLI to Connect to a Project

Authenticate and activate a project. 
# A browser window will open for OAuth.
# Next the terminal will ask you to select or create a project.
meshagent setup
You are now authenticated and ready to use the CLI!

​
Step 4: Create a mailbox for the mail channel

Since this example includes the mail channel, create the mailbox before you start the process:
bash
meshagent mailbox create \
  --address my-first-agent@mail.meshagent.com \
  --room gettingstarted \
  --queue my-first-agent@mail.meshagent.com

​
Step 5: Start an agent

Let’s start one process-based agent in a new room and give it a few useful built-in tools. This example includes all four primary channels: chat, mail, queue, and toolkit.
bash
meshagent process join \
  --room gettingstarted \
  --agent-name my-first-agent \
  --channel chat \
  --channel mail:my-first-agent@mail.meshagent.com \
  --channel queue:my-first-agent \
  --channel toolkit:my-first-agent \
  --threading-mode default-new \
  --thread-dir ".threads/my-first-agent" \
  --model gpt-5.4 \
  --web-search \
  --require-storage \
  --rule "You are a helpful first agent. Answer clearly, use web search when needed, and save important artifacts to storage."

​
Step 6: Talk to your agent

  1. Open studio.meshagent.com
  2. Join the gettingstarted session.
  3. In the participants tab you will see my-first-agent appear. Select it from the participants list and begin chatting. Try asking it to search the web or save something to storage.
Congrats, you just ran your first agent! This agent will be available in the Room while you’re running it from your terminal. To stop it, run Ctrl+C. If you want it to persist, deploy it as a project or room service.

​
Step 7: Try the other channels

Send the agent an email at my-first-agent@mail.meshagent.com. Send work through the queue:
bash
meshagent room queue send \
  --room gettingstarted \
  --queue my-first-agent \
  --json '{"prompt":"Summarize the current room activity and save a note."}'
Invoke the agent through its toolkit channel:
bash
meshagent room agent invoke-tool \
  --room gettingstarted \
  --toolkit my-first-agent \
  --tool run_my_first_agent_task \
  --arguments '{"prompt":"Draft a short welcome message for a new customer."}'

​
Next Steps