Understand Web Server

The web server is a lightweight Go-based HTTP server designed to handle incoming requests efficiently. It manages the lifecycle of agent processes, including their initiation and termination.

The playground/demo UI is specifically built to interface seamlessly with the web server, providing a user-friendly interaction layer. Alternatively, the server can be accessed directly using tools like curl or any other HTTP client.

Request & Response Examples

The server provides a simple layer for managing agent processes. The API resources are described below.

API Resources

• POST /start

• POST /stop

• POST /ping

POST /start

This API initializes an agent using the specified graph and override properties. The agent will join the designated channel and subscribe to the UID used by your browser or device for RTC connectivity.

Param	Description
request_id	Any uuid for tracing purpose
channel_name	The channel name must match the one your browser or device joins. For effective communication, the agent must remain in the same channel as your browser or device.
user_uid	The UID used by your browser or device for RTC must be provided, as the agent requires this UID to subscribe to your audio stream.
bot_uid	Optional, the uid bot used to join rtc
graph_name	The graph to be used when starting agent, will find in property.json
properties	Additional properties can be specified to override those in property.json. These overrides will not modify the original property.json file but will apply only to the instance of the agent during startup.
timeout	This setting defines the duration the agent will remain active without receiving any pings. If the timeout is set to -1, the agent will not terminate due to inactivity. By default, the timeout is 60 seconds, but it can be customized by adjusting the WORKER_QUIT_TIMEOUT_SECONDS variable in your .env file.

Example:

curl 'http://localhost:8080/start' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "request_id": "c1912182-924c-4d15-a8bb-85063343077c",
    "channel_name": "test",
    "user_uid": 176573,
    "graph_name": "camera_va_openai_azure",
    "properties": {
      "openai_chatgpt": {
        "model": "gpt-4o"
      }
    }
  }'

POST /stop

This API stops the agent you started

Param	Description
request_id	Any uuid for tracing purpose
channel_name	Channel name, the one you used to start the agent

Example:

curl 'http://localhost:8080/stop' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "request_id": "c1912182-924c-4d15-a8bb-85063343077c",
    "channel_name": "test"
  }'

POST /ping

This API sends a ping to the server to confirm that the connection is still active. If you set timeout: -1 when starting the agent, pings are not required. Otherwise, the agent will terminate if it does not receive a ping within the specified timeout period (in seconds).

Param	Description
request_id	Any uuid for tracing purpose
channel_name	Channel name, the one you used to start the agent

Example:

curl 'http://localhost:8080/ping' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "request_id": "c1912182-924c-4d15-a8bb-85063343077c",
    "channel_name": "test"
  }'