---
updatedAt: 2025-11-11T01:52:33.000Z
---
Fetch the complete documentation index at: https://docs.formant.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Agent SDK installation and overview
The Agent SDK is part of the Formant Python package. The Agent SDK client contains a suite of methods which allow you to ingest telemetry data, receive and respond to commands, teleoperate your device, and more.
> ๐ When should I use the Agent SDK?
>
> You should use the Agent SDK...
>
> * If you are not using ROS and you are using Python in robot-side applications.
> * If you are using ROS, but you want more control over how your application interacts with Formant.
# Installation
### Prerequisite: Install the Formant agent
To use the Agent SDK, the Formant agent must be installed on your device. For more information, see [Install the Formant agent](https://docs.formant.io/docs/getting-started-install-the-formant-agent).
***
The Formant Python package can be installed via `pip`:
```shell
pip install formant
```
# Usage
This section gives a broad overview of the capabilities of the Agent SDK.
> ๐
>
> The full set of methods, syntax, and return values can be found in the [Agent SDK reference](https://docs.formant.io/reference/agent-sdk-reference).
When you ingest data, a stream will automatically be created in Formant if it does not already exist. To create your streams ahead of time, or to configure existing streams, see [Add a non-ROS data stream](https://docs.formant.io/docs/getting-started-add-a-non-ros-data-stream).
## Instantiate the agent client
To use the methods of the Agent SDK, you'll first instantiate the client:
```python
from formant.sdk.agent.v1 import Client as FormantClient
fclient = FormantClient()
```
The client will try to find and connect to the Formant agent. If this is successful, you'll see the following log:
```
INFO: Agent communication established.
```
## Ingest telemetry data
The following methods of the client can be used to ingest data into Formant:
| Method |
| :----------------- |
| `post_image` |
| `post_numeric` |
| `post_numericset` |
| `post_bitset` |
| `post_text` |
| `post_geolocation` |
| `post_battery` |
| `post_json` |
Each method takes a stream name as its first argument, and the data value as its second. For example, this line:
```python
fclient.post_numeric("Distance traveled", 0.23)
```
...would post a value of `0.23` to the stream `"Distance traveled"`.
For more information, see [Telemetry data ingestion](https://docs.formant.io/reference/datapoint-ingestion).
## Handle 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 the examples for usage.
For more information, see [Handling commands](https://docs.formant.io/reference/handling-commands).
## Read application configuration
Use the `get_app_config` method to retrieve application configuration values. For example, in this line:
```python
walk_mode_value = fclient.get_app_config("Walk mode", None)
```
...`walk_mode_value` is set to the string value for the application configuration key `"Walk mode"` if it exists, and `None` otherwise.
For more information, see [Reading application configuration](https://docs.formant.io/reference/reading-application-configuration).
## Send real-time data to Formant's teleoperation interface
### Status indicators
Use `post_bitset` with stream name `"Status"`. For example:
```python
fclient.post_bitset("Status", {
"FLIR online": False,
"Motors responsive:" True,
"Walk mode": False,
"Camera mode": True,
})
```
If a teleoperation session is active on your device, the bitset will be streamed to the Formant teleoperation interface in real-time.
### Images and video
Use `post_image` to stream images. You can configure an image stream to be encoded to a video stream by the Formant agent.
For more information, see [Sending image or video data](https://docs.formant.io/reference/sending-image-datapoints).
## Handle real-time data sent from the teleoperation interface
### Buttons and joystick
Use the `register_teleop_callback` method. For example:
```python
def handle_teleop_controls(datapoint):
if datapoint.stream == "Buttons":
handle_button(datapoint.bitset)
elif datapoint.stream == "Joystick":
handle_joystick(datapoint.twist)
fclient.register_teleop_callback(handle_teleop_controls)
```
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 (`"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 the `unregister_teleop_callback` method.
For more information, see [Teleop](https://docs.formant.io/reference/teleop).
## Create events
Use the `create_event` method to create new events. You can configure the severity and whether the event generates a notification in the Formant web application.
For more information, see [Agent SDK: Events](https://docs.formant.io/reference/events) and [Getting Started: Events and notifications](https://docs.formant.io/docs/getting-started-events-and-notifications).
# See also
* [Agent SDK reference](https://docs.formant.io/reference/agent-sdk-reference)
* [Getting started with Formant](https://docs.formant.io/docs/getting-started-overview)
### If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [support@formant.io](mailto:support@formant.io).