Skip to main content
Build and test services on your machine, then deploy them as either a project or room service or a run dynamically via the Containers API.

​
ServiceHost Basics

MeshAgent’s ServiceHost exposes your agents or tools as HTTP webhook endpoints. When you create a ServiceHost, it starts an HTTP server that listens for incoming webhook requests from MeshAgent. When a webhook call arrives, the ServiceHost automatically spins up your agent or tool, connects it to the requested room, and manages its lifecycle until the session ends. Let’s define a simple chatbot service: 
import asyncio
from meshagent.otel import otel_config
from meshagent.api.services import ServiceHost
from meshagent.agents.chat import ChatBot
from meshagent.openai import OpenAIResponsesAdapter

# Enable OpenTelemetry logging and tracing for the agent
otel_config(service_name="chatbot")

# Create a service host
service = ServiceHost()  # optional to pass a port, MeshAgent automatically assigns an available one if none provideds

# Register an agent at a specific path
@service.path(path="/chat", identity="chatbot")
class SimpleChatbot(ChatBot):
    def __init__(self):
        super().__init__(
            name="chatbot",
            title="Simple Chatbot",
            description="A helpful chatbot for room participants",
            rules=[
                "Always respond to the user first then include a fun fact at the end of your response."
            ],
            llm_adapter=OpenAIResponsesAdapter(),
        )

# Start the service
asyncio.run(service.run())
Note: MeshAgent automatically assigns an available port to your service. You can set a specific port by passing the MESHAGENT_PORT environment variable or passing a port to the ServiceHost constructor. For example, host = ServiceHost(port=9000) or host = ServiceHost(port=int(os.getenv("MESHAGENT_PORT", "9001"))).

​
Run Locally with the CLI

Save the code above as main.py and run: 
meshagent setup  # authenticate once
meshagent service run "main.py" --room=myroom
You should see output similar to: 
Connecting to room...
Connecting port 8081...
Connecting endpoint /chat as chatbot...
INFO:services:starting -> 0.0.0.0:8081/chat -> SimpleChatbot
INFO:webhooks:received request http://localhost:8081/chat POST
INFO:services:chatbot answering call and joining room
The CLI command:
  • Starts your ServiceHost HTTP server locally
  • Discovers all @host.path endpoints automatically
  • Calls each endpoint into the specified room using the declared identity
Open studio.meshagent.com, enter myroom, and you will see the chatbot participant available for interaction.

​
Iterate Quickly

  1. Implement your agent or tool and register endpoints with ServiceHost.
  2. Run meshagent service run "main.py" --room=myroom to connect it to a test room.
  3. Interact via MeshAgent Studio, adjust code, and restart the CLI command as needed.
  4. Add more endpoints to the same ServiceHost if you want to bundle related agents/tools together.

​
Working with multiple agents or tools in a single service

You can register multiple agents or tools in a single ServiceHost using different paths. This makes it easy to bundle related agents and tools together into a single deployable service.
Python
service = ServiceHost()

@service.path(path="/chat", identity="chatbot")
class ChatAgent(ChatBot):
    # ... chat agent implementation

@service.path(path="/dataanalysis", identity="data-analsis-tool") 
class DataAnalysis(Tool):
    # ... data analysis tool implementation

@service.path(path="/helper", identity="task-helper")
class HelperAgent(TaskRunner):
    # ... helper agent implementation
Using meshagent service run "main.py" --room=myroom will automatically detect and call all three endpoints into the room with their respective identities.

​
From Local Development to Deployment

In this tutorial we covered how to use ServiceHost and the MeshAgent CLI, (e.g.,meshagent service run main.py --room=myroom) to test your service before containerizing it. Once your service works locally here’s the path to deployment:
  1. Package your code: Create a Dockerfile with the required libraries. MeshAgent provides a variety of base images for your use.
  2. Author a manifest: Manifests differ for project and room services. Use kind: Service when deploying a project service or kind: ServiceTemplate for room services.
  3. Push to a registry: Make sure your image is available for MeshAgent to pull and run the container for the image.
  4. *Deploy: Use the MeshAgent Studio UI or the CLI to configure, deploy, and monitor services.
The details depend on whether you’re deploying a project service or room service — see the configuration guides below.

​
Next Steps