agentsystems-sdk

AgentSystems SDK & CLI

The AgentSystems SDK is a single-install Python package that provides several components:

• agentsystems — a polished command-line interface for bootstrapping and operating an AgentSystems deployment.
• A small helper library (future) so you can embed AgentSystems clients in your own code.

The CLI is designed to work both interactively (laptops) and non-interactively (CI, cloud VMs).

Quick install (via pipx)

python3 -m pip install --upgrade pipx      # one-time setup
pipx install agentsystems-sdk              # installs isolated venv and the `agentsystems` app

# verify
agentsystems --version

Install from source (contributors)

# in the repository root
pipx uninstall agentsystems-sdk  # if previously installed
pipx install --editable .        # live-reloads on file changes

Continuous Integration (GitHub Actions)

Every push and pull request runs ci.yml which now goes beyond linting:

• Installs dev dependencies & runs pre-commit hooks (ruff, black, shellcheck, hadolint).
• Builds the wheel (python -m build).
• Installs the built wheel into a fresh venv.
• Runs smoke tests (agentsystems --version, agentsystems info).

A failing build or test blocks the merge, ensuring every released version installs cleanly.

CLI commands

All commands are available through agentsystems (or the shorter alias agntsys).

Command	Description
agentsystems init [TARGET_DIR]	Interactive bootstrap: prompts for Langfuse organization & admin details, generates secure keys, creates .env automatically, then clones the deployment template and pulls the required Docker images into TARGET_DIR.
agentsystems up [PROJECT_DIR]	Start the platform plus Langfuse tracing stack (docker compose up). Waits for the gateway and all agent containers to become healthy by default (spinner). Pass --no-wait to skip readiness wait or --no-langfuse to disable tracing. Uses the .env generated by init (or pass --env-file PATH).
agentsystems down [PROJECT_DIR]	Stop containers. Volumes are preserved by default; add --delete-volumes (or --delete-all) to wipe data.
agentsystems logs [PROJECT_DIR]	Stream or view recent logs (docker compose logs).
agentsystems status [PROJECT_DIR]	List running containers and state (docker compose ps).
agentsystems restart [PROJECT_DIR]	Quick bounce (down → up). Waits for readiness by default. Pass --no-wait to skip. Requires .env.
agentsystems info	Show environment diagnostics (SDK, Python, Docker).
agentsystems version	Show the installed SDK version.
agentsystems artifacts-path THREAD_ID [REL_PATH]	Resolve a path inside the shared artifacts volume using thread-centric structure.

up options

--detach / --foreground   Run containers in background (default) or stream logs
--fresh                   docker compose down -v before starting
--env-file PATH           Pass a custom .env file to Compose
--wait / --no-wait        Wait for gateway readiness (default: --wait)
--docker-token TEXT       Docker Hub Org Access Token (env `DOCKER_OAT`)
--no-login                Skip Docker login even if token env is set
--no-langfuse             Skip the Langfuse tracing stack (core services only)

Run agentsystems up --help for the authoritative list.

Tracing & observability (Langfuse)

By default the CLI starts the Langfuse tracing stack alongside the core services and exposes its UI at http://localhost:3000. You can explore request traces and performance metrics there while developing.

If you prefer to run only the core platform (for example on a small CI runner) pass --no-langfuse to any stack command (up, down, restart, logs, status).

Example: start and watch logs

agentsystems up --foreground    # run inside the deployment dir

Example: fresh restart in CI

agentsystems up /opt/agent-platform-deployments --fresh --detach

init options

--gh-token TEXT       GitHub PAT for private template repo (env `GITHUB_TOKEN`)
--docker-token TEXT   Docker Org Access Token (env `DOCKER_OAT`)
--branch TEXT         Template branch to clone (default: `main`)

If a flag is omitted the CLI falls back to environment variables / .env. The command always prompts for Langfuse organization, admin user, and password (interactive mode) and generates secure keys automatically. GitHub/Docker tokens are only requested if the unauthenticated clone or pull fails.

Example: interactive laptop

agentsystems init
# prompts for directory and, only if needed, tokens

Example: scripted cloud VM / CI

export GITHUB_TOKEN=ghp_xxx          # or use --gh-token
export DOCKER_OAT=st_xxx             # or use --docker-token

agentsystems init /opt/agentsystems/engine \
  --gh-token "$GITHUB_TOKEN" \
  --docker-token "$DOCKER_OAT"

Multi-registry agent marketplace

Agent images and credentials are now configured via a single agentsystems-config.yml file found in the deployment repo. Use the new top-level registry_connections: key (replacing the legacy registries:) to define one or more logins—multiple Docker Hub accounts, Harbor, ECR, etc.

registry_connections:
  dockerhub_main:
    url: docker.io
    enabled: true
    auth:
      method: basic
      username_env: DOCKERHUB_USER
      password_env: DOCKERHUB_TOKEN

agents:
  - name: hello-world
    registry_connection: dockerhub_main
    repo: agentsystems/hello-world-agent
    tag: latest

When you run agentsystems up the CLI logs in to each enabled connection using the referenced env vars, pulls the images, starts the containers with your .env, and waits until Docker marks them healthy (see HEALTHCHECK below). The CLI uses an isolated Docker config directory per registry, so multiple connections targeting the same hostname (e.g. several Docker Hub organisations) work seamlessly.

Environment variables & .env

Docker Hub token must include the "Read public repositories" permission so pulls for postgres, redis, etc. succeed.

Note: LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, and LANGFUSE_SECRET_KEY are written without quotes so they are passed correctly into Docker containers. If you edit .env manually, ensure these three remain unquoted. | Variable | Purpose | |----------|---------| | GITHUB_TOKEN | GitHub Personal Access Token with repo:read scope | | DOCKER_OAT | Docker Hub Org Access Token for agentsystems org |

The .env file is generated automatically by agentsystems init. It contains both runtime vars and a temporary set of LANGFUSE_INIT_* variables used on the very first startup. On the first successful agentsystems up these init variables are commented out and moved to the bottom of the file so they don’t confuse future edits. You can still keep them for reference or delete them entirely.

Note: LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, and LANGFUSE_SECRET_KEY are written without quotes so they are passed correctly into Docker containers. If you edit .env manually, ensure these three remain unquoted.

You may also set or override tokens manually if you prefer:

GITHUB_TOKEN=ghp_xxx
DOCKER_OAT=st_xxx

Updating / upgrading

pipx upgrade agentsystems-sdk           # upgrade from PyPI
# or, from source repo:
pipx reinstall --editable .

Security notes

• The CLI never prints your secrets. GitHub PATs are masked and Docker login uses --password-stdin.
• Delete tokens / .env after the resources become public.

Support & feedback

Open an issue or discussion in the private GitHub repository. Contributions welcome—see CONTRIBUTING.md.