Skip to main content
Room services are scoped to a specific room and persist across sessions. They’re ideal when users need to customize services for example, providing their own system prompt or API key. This example shows how to create a simple chatbot that lets users provide a custom system prompt when they add it to their room. We’ll create a containerized MeshAgent-native service using a ServiceTemplate so users can configure the system prompt when they add it to their room. To learn more about project vs room services and understand when to use each see intro to services and containers.

​
Example

Let’s create a simple chatbot that allows users to give it a system prompt when deploying. To deploy this we’ll create three files:
  • main.py: A MeshAgent-native chatbot service using ServiceHost
  • Dockerfile: Packages the service as a container
  • meshagent.yaml: A ServiceSpec that allows users to set a custom system prompt for the agent when deploying it to their room.

​
main.py

import os
import asyncio
import logging
from meshagent.agents.chat import ChatBot
from meshagent.api.services import ServiceHost
from meshagent.openai import OpenAIResponsesAdapter
from meshagent.otel import otel_config

# Enable OpenTelemetry logging and tracing for the agent
otel_config(service_name="chatbot-service")
log = logging.getLogger("chatbot-service")

# Pass a system prompt, custom rules / instructions, that you want the agent to follow.
system_prompt = os.getenv("SYSTEM_PROMPT")
rules = [system_prompt] if system_prompt else []
# print(f"starting service with rule: {system_prompt}", flush=True)

# ServiceHost runs an HTTP server that exposes agents or tools as webhook endpoints and manages their lifecycle
# Port defaults to an available port if not assigned
host = ServiceHost()

# Register an agent with the host. The @host.path decorator maps the
# endpoint "/agent" to this agent class. When the host receives a
# “room.call” webhook on that path, it will spawn an instance of
# MyChatBot and connect it to the calling room.

@host.path(path="/agent", identity="chatbot")
class MyChatBot(ChatBot):
    # ChatBot is a conversational, text-based agent that maintains context of the conversation and routes messages to a language model
    def __init__(self):
        super().__init__(
            name="chatbot",
            rules=rules,
            llm_adapter=OpenAIResponsesAdapter(),  # Connect to an OpenAI model that uses the Responses API (e.g. GPT 4.1, o3)
        )

# Run the host. It starts listening for webhook calls and gracefully
# shuts down when the process receives a termination signal.
asyncio.run(host.run())

​
Dockerfile

Dockerfile
FROM meshagent/python-sdk-slim:latest

COPY . /src

WORKDIR /src

ENTRYPOINT [ "python3", "main.py" ]

​
meshagent.yaml

yaml
kind: Service
version: v1
metadata:
  name: chatbot
  description: "A chatbot that takes a system prompt at runtime"                 
agents:
  - name: chatbot
    description: "Room-scoped conversational agent"
    annotations:
      meshagent.agent.type: "ChatBot"
ports:
- num: "*"                    # automatically assign an available MESHAGENT_PORT for the agent to run on 
  type: http
  liveness: "/"               # ensure the service is alive before connecting to the room
  endpoints:
  - path: /agent              # service path to call and run the agent on
    meshagent:
      identity: chatbot         # name of the agent as it shows up in the Room
container:
  image: "myrepository/chatbot-image:1"
  command: python3 main.py      # command executed inside the container
  environment:                  # passes variables into the container
    - name: SYSTEM_PROMPT
      value: "Always reply to the user with a fun fact" # customize the system prompt before deploying

​
Build and Push the Container

Build and push your container to a registry:
bash
docker buildx build . \
  -t "myrepository/chatbot-image:1" \
  --platform linux/amd64 \
  --push
Note: We recommend docker buildx because it supports cross-platform builds, pushes directly to your registry in one step, and enables optional layer caching for much faster CI builds.

​
Deploy the Room Specific Service

From the terminal in the directory with your yaml file run:
bash
meshagent setup # authenticate to MeshAgent if not already
meshagent service create --file meshagent.yaml --room=myroom
You can also deploy the service to a specific room through MeshAgent Studio by selecting the room menu, selecting Service, then New Service, and filling in the details. For more details on deployment see the deploying services documentation.

​
Use the Service

  1. Open your room in MeshAgent Studio
  2. The chatbot will appear in the participants tab and you can begin talking to the agent

​
Verify the Service is Running

From the Developer Console at the bottom half of the room UI
  • Check the Containers tab, you’ll see your container with MeshAgent as the starter
  • Check the Logs tab for startup messages from your service
Now that your service is deployed try it out in MeshAgent Studio. Enter the room you deployed the service to, you will be prompted to supply a system prompt for the agent, once you do the service will start and you’ll see the chatbot in the participants tab. Room services are managed by MeshAgent: If you update the service configuration during the session, MeshAgent automatically updates the running service. If you delete the room service, it’s removed from the room. Whatever room services you have saved will match what’s running - MeshAgent keeps them in sync. Containers run on demand, and will not automatically restart the next time you go into the room. If you want a container with your configuration to save and start automatically the next time the room starts, you will need to deploy a project wide service to manage the containers. Otherwise you can start containers as needed through the CLI/API. For more information on room and project services see: