Tips and tutorials

Tips and tutorials for beginners and experts alike

    Formant Agent Python SDK

    This tutorial gives a very broad overview of the capabilities of the Formant agent Python SDK, as well as linking to examples for each capability. The agent Python SDK interacts directly with the agent and hence it requires the agent to be running. If you want to ingest data without an agent running, refer to our Cloud Python SDK. For more details and latest information, visit our public github repo.


    1. Install formant sdk. It will also install the required dependencies to communicate with the agent's gRPC interface.

    pip install formant


    pip3 install formant

    The formant module works in Python ^2.7 and ^3.6.

    2. Make sure Formant Agent is running. Refer to installing agent for more information.

    systemctl status formant-agent | grep Active:

    Instantiating the Formant Agent client

    Each of the following requires an instantiated, connected Formant agent API client. That can be done with the following snippet:

    from formant.sdk.agent.v1 import Client as FormantClient
    fclient = FormantClient()

    If your client find and connects to the Formant agent, a simple log will print confirming the connection:

    INFO: Agent communication established.

    Ingesting data

    Use the following methods of the client to ingest data into Formant:


    Each method takes a stream name as its first argument, and the data value as its second. For instance, fclient.post_numeric("Distance traveled", 0.23) would post a value of 0.23 to the stream "Distance traveled".


    Handling commands

    Use the register_command_request_callback and send_command_response methods to handle commands sent from the Formant application on your device. Refer to handling commands example for usage.

    Reading application configuration

    Use the get_app_config method to retrieve application configuration values. For instance, fclient.get_app_config("Walk mode", None) returns the string value for the application configuration key "Walk mode" if it exists, and None otherwise. Refer to read app config example for details.


    Sending real-time data from the agent to Formant's teleop interface

    Status Indicators

    Use post_bitset with stream name "Status". For instance:

    fclient.post_bitset("Status", {
        "FLIR online": False,
        "Motors responsive:" True,
        "Walk mode": False,
        "Camera mode": True,

    The bitset will be streamed to the Formant teleop interface in real-time when a teleop session is active.


    Use post_image to stream images. If configured on the Formant app, the image stream will be encoded to a video stream by the Formant agent. Refer to Sending images for a basic example.

    Receiving and handling real-time data sent from Formant's teleop interface to the device

    Buttons and joystick

    Use the register_teleop_callback method. Example:

    def handle_teleop_controls(datapoint):
        if == "Buttons":
        elif == "Joystick":

    Control datapoints will be streamed to the provided callback. Control datapoints with the stream name "Buttons" will contain Bitsets with the button control information. Joystick control datapoints have a user-configured stream name (although "Joystick" is a common choice) and they will contain Twists.

    Refer to our public protos for the exact data model of Bitset and Twist.

    Unregister a callback function with unregister_teleop_callback.

    Please refer to the Handling and sending teleop example for more information.

    Creating events

    Use the create_event method to create new events with levels of severity. Create an in-app notification with the notify keyword argument. Please refer to the Create event example for more information.

    © 2020 Formant • 1999 Bryant St · San Francisco, CA 94110