How to Develop Agent Extensions¶

Agent extensions are Python projects that run as local processes under the Zelos agent. They are the right choice when you need to:

talk to devices or buses
stream telemetry into Zelos
expose runtime actions
package protocol or hardware integrations for reuse

Create a project¶

zelos extensions create my-agent-extension

Optional metadata and template controls:

zelos extensions create my-agent-extension \
  --author "Jane Doe" \
  --description "Decode and stream device telemetry" \
  --email "[email protected]" \
  --github "janedoe" \
  --python-version 3.12

The created project includes:

extension.toml
pyproject.toml
main.py
extension/
tests/
scripts/
Justfile
CI workflows and editor settings

Develop locally¶

cd my-agent-extension
just install
just dev
just check
just test

Install into Zelos¶

zelos extensions install-local .
zelos extensions start local.my-agent-extension --config '{"demo": true}'
zelos live signals
zelos actions list

Package and release¶

just package
just release 0.1.0
git push origin main v0.1.0

The generated extension.toml includes a [package] section that controls which files are included in the archive:

[package]
paths = ["main.py", "my_extension"]

Use zelos extensions package --list . to preview the files before packaging.

Templates and reference¶

Official templates: https://github.com/zeloscloud/zelos-extension-templates/tree/main/agent/python
Shared extension concepts and deeper reference: Develop Extensions
Host configuration details: Host Configuration

For detailed guidance on manifests, runtime behavior, lifecycle, configuration schemas, archive validation, and troubleshooting, use the shared extension reference in Develop Extensions. That page remains the deeper technical reference, while this page is the agent-specific workflow.