{"id":42598255,"url":"https://github.com/agentsystems/agentsystems-sdk","last_synced_at":"2026-01-29T00:13:31.128Z","repository":{"id":313372942,"uuid":"1006022448","full_name":"agentsystems/agentsystems-sdk","owner":"agentsystems","description":"CLI tools for deploying and managing AI agents","archived":false,"fork":false,"pushed_at":"2025-11-02T23:11:32.000Z","size":459,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T20:37:48.056Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pypi.org/project/agentsystems-sdk/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentsystems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-21T10:10:34.000Z","updated_at":"2025-11-02T23:07:17.000Z","dependencies_parsed_at":"2025-09-05T17:38:17.564Z","dependency_job_id":"9b92cfea-1d17-4e47-8d22-af72e714f007","html_url":"https://github.com/agentsystems/agentsystems-sdk","commit_stats":null,"previous_names":["agentsystems/agentsystems-sdk"],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/agentsystems/agentsystems-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagentsystems-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagentsystems-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagentsystems-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagentsystems-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentsystems","download_url":"https://codeload.github.com/agentsystems/agentsystems-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentsystems%2Fagentsystems-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28857229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T22:56:21.783Z","status":"ssl_error","status_checked_at":"2026-01-28T22:56:00.861Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-29T00:13:30.183Z","updated_at":"2026-01-29T00:13:31.116Z","avatar_url":"https://github.com/agentsystems.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentSystems SDK \u0026 CLI\n\n[![GitHub stars](https://img.shields.io/github/stars/agentsystems/agentsystems?style=flat-square\u0026logo=github)](https://github.com/agentsystems/agentsystems/stargazers)\n[![CI](https://github.com/agentsystems/agentsystems-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/agentsystems/agentsystems-sdk/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/agentsystems/agentsystems-sdk/branch/main/graph/badge.svg?token=25Mahs4a96)](https://codecov.io/gh/agentsystems/agentsystems-sdk)\n\n\u003e [!NOTE]\n\u003e **Pre-Release Software** - AgentSystems is in active development. Join our [Discord](https://discord.com/invite/JsxDxQ5zfV) for updates and early access.\n\u003e ⭐ [**Star the main repository**](https://github.com/agentsystems/agentsystems) to show your support!\n\n\u003e This is the **CLI and deployment tool** for AgentSystems. See the [main repository](https://github.com/agentsystems/agentsystems) for platform overview and documentation.\n\nThe AgentSystems **SDK** is a single-install Python package that provides several components:\n\n* `agentsystems` — a polished command-line interface for bootstrapping and operating an AgentSystems deployment.\n* A small helper library so you can embed AgentSystems clients in your own code.\n\nThe CLI is designed to work **both interactively** (laptops) and **non-interactively** (CI, cloud VMs).\n\n\n## Quick install\n\n### Automatic installation (Recommended)\n\n```bash\n# Linux \u0026 macOS - installs Docker, pipx, and the SDK\ncurl -fsSL https://raw.githubusercontent.com/agentsystems/agentsystems/main/install.sh | sh\n```\n\n### Manual installation\n\n```bash\n# Install pipx if you don't have it\npython3 -m pip install --upgrade pipx\npipx ensurepath\n\n# Install the SDK\npipx install agentsystems-sdk\n\n# Verify installation\nagentsystems --version\n```\n\n\n\n### Install from source (contributors)\n\n```bash\n# in the repository root\npipx uninstall agentsystems-sdk  # if previously installed\npipx install --editable .        # live-reloads on file changes\n```\n\n---\n## Continuous Integration (GitHub Actions)\n\nEvery push and pull request runs `ci.yml` which now goes beyond linting:\n\n1. Installs dev dependencies \u0026 runs pre-commit hooks (ruff, black, shellcheck, hadolint).\n2. Builds the wheel (`python -m build`).\n3. Installs the built wheel into a fresh venv.\n4. Runs smoke tests (`agentsystems --version`, `agentsystems info`).\n\nA failing build or test blocks the merge, ensuring every released version installs cleanly.\n\n---\n\n## CLI commands\n\nAll commands are available through `agentsystems` (or the shorter alias `agntsys`).\n\n| Command | Description |\n|---------|-------------|\n| `agentsystems init [TARGET_DIR]` | Interactive bootstrap: prompts for Langfuse organization \u0026 admin details, generates keys, creates `.env` automatically, then copies the built-in deployment template and pulls the required Docker images into `TARGET_DIR`. No Docker authentication required - uses public images. |\n| `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`). |\n| `agentsystems down [PROJECT_DIR]` | Stop containers. Volumes are preserved by default; add `--delete-volumes` (or `--delete-all`) to wipe data. |\n| `agentsystems logs [PROJECT_DIR]` | Stream or view recent logs (`docker compose logs`). |\n| `agentsystems status [PROJECT_DIR]` | List running containers and state (`docker compose ps`). |\n| `agentsystems restart [PROJECT_DIR]` | Quick bounce (`down` → `up`). **Waits for readiness by default**. Pass `--no-wait` to skip. **Requires `.env`**. |\n| `agentsystems version` | Show the installed SDK version. |\n| `agentsystems versions` | Show version information for all AgentSystems components. |\n| `agentsystems clean` | Clean up deployment artifacts and containers. |\n| `agentsystems artifacts-path THREAD_ID [REL_PATH]` | Resolve a path inside the shared artifacts volume using thread-centric structure. |\n| `agentsystems run AGENT PAYLOAD` | Invoke an agent with JSON payload and optional file uploads, stream progress, and return results. |\n| `agentsystems update [PROJECT_DIR]` | Update core platform images (agent-control-plane, agentsystems-ui) to latest versions. Faster than re-running `up` when you only need to update platform components. |\n\n### Index Commands\n\n| Command | Description |\n|---------|-------------|\n| `agentsystems index login` | Login to AgentSystems Index - opens browser for authentication and stores API key locally. |\n| `agentsystems index logout` | Logout from AgentSystems Index - removes stored API key from local machine. |\n| `agentsystems index list` | List all your published agents on the index. |\n| `agentsystems index publish [PATH]` | Publish agent to the index. Use `--listed` for public agents. Agents are unlisted (private) by default. |\n| `agentsystems index delete DEVELOPER/AGENT` | Permanently remove an agent from the index. |\n| `agentsystems index allow-listed --enable\\|--disable` | Enable or disable listed (public) agents. When disabling, use `--preserve` to keep existing agents or `--cascade` to unlist all. |\n\n### `up` options\n\n```\n--detach / --foreground   Run containers in background (default) or stream logs\n--fresh                   docker compose down -v before starting\n--env-file PATH           Pass a custom .env file to Compose\n--wait / --no-wait        Wait for gateway readiness (default: --wait)\n--no-langfuse             Skip the Langfuse tracing stack (core services only)\n--agents MODE             Agent startup mode: none, create, or all (default: create)\n```\n\nRun `agentsystems up --help` for the authoritative list.\n\n---\n### Tracing \u0026 observability (Langfuse)\n\nBy default the CLI starts the [Langfuse](https://langfuse.com/) tracing stack alongside the core services and exposes its UI at \u003chttp://localhost:3000\u003e. You can explore request traces and performance metrics there while developing.\n\nIf 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`).\n\n\n### Example: start and watch logs\n\n```bash\nagentsystems up --foreground    # run inside the deployment dir\n```\n\n### Example: fresh restart in CI\n\n```bash\nagentsystems up /opt/agent-platform-deployments --fresh --detach\n```\n\n---\n\n## File Uploads \u0026 Artifacts\n\nThe AgentSystems platform supports file uploads to agents and provides tools for managing artifacts.\n\n### Uploading Files to Agents\n\nUse the `run` command to invoke agents with file uploads:\n\n```bash\n# Upload single file with JSON payload\nagentsystems run agent-name '{\"format\": \"csv\"}' --input-file data.csv\n\n# Upload multiple files\nagentsystems run agent-name '{\"sync\": true}' \\\n  --input-file input1.txt \\\n  --input-file input2.txt\n\n# Use file path for JSON payload\necho '{\"date\": \"July 4\"}' \u003e payload.json\nagentsystems run agent-name payload.json --input-file date.txt\n```\n\n### Artifacts Management\n\nThe platform uses a thread-centric artifacts structure where each request gets a unique directory:\n\n```\n/artifacts/\n├── {thread-id}/\n│   ├── in/          # Files uploaded by client\n│   └── out/         # Files created by agent\n```\n\n#### Using artifacts-path Command\n\nGet paths for reading/writing artifacts:\n\n```bash\n# Get path to thread's output directory\nagentsystems artifacts-path abc123-def456\n\n# Get path to specific output file\nagentsystems artifacts-path abc123-def456 result.json\n\n# Get path to input directory\nagentsystems artifacts-path abc123-def456 --input\n\n# Get path to specific input file\nagentsystems artifacts-path abc123-def456 data.csv --input\n```\n\n#### Manual Artifact Access\n\nYou can also access artifacts directly through any container with the volume mounted:\n\n```bash\n# List all active threads\ndocker exec local-gateway-1 ls -la /artifacts/\n\n# Read agent output files\ndocker exec local-gateway-1 cat /artifacts/{thread-id}/out/result.txt\n\n# Check uploaded input files\ndocker exec local-gateway-1 ls -la /artifacts/{thread-id}/in/\n```\n\n### Volume Mounting for Agents\n\nWhen deploying agents through `agentsystems-config.yml`, the CLI is configured to:\n\n1. **Mount artifacts volume**: All agents get `/artifacts` mounted with proper permissions\n2. **Create thread directories**: Gateway creates `/artifacts/{thread-id}/{in,out}/` as needed\n3. **Handle file uploads**: Gateway saves uploaded files to `/artifacts/{thread-id}/in/`\n4. **Manage permissions**: Attempts to configure agents (UID 1001) for artifact access\n\n### Agent Development\n\nWhen building agents that handle file uploads:\n\n```python\n# In your agent's invoke() function\nimport pathlib\nfrom fastapi import Request\n\ndef invoke(request: Request, req: InvokeRequest):\n    thread_id = request.headers.get(\"X-Thread-Id\", \"\")\n\n    # Read uploaded files\n    in_dir = pathlib.Path(\"/artifacts\") / thread_id / \"in\"\n    if (in_dir / \"data.txt\").exists():\n        content = (in_dir / \"data.txt\").read_text()\n\n    # Write output files\n    out_dir = pathlib.Path(\"/artifacts\") / thread_id / \"out\"\n    out_dir.mkdir(parents=True, exist_ok=True)\n    (out_dir / \"result.json\").write_text('{\"status\": \"complete\"}')\n```\n\nSee the [agent-template](https://github.com/agentsystems/agent-template) for a complete example.\n\n---\n\n### `init` details\n\nThe init command:\n1. Prompts for Langfuse organization and admin credentials (interactive mode)\n2. Generates keys automatically\n3. Creates `.env` file with all configuration\n4. Pulls required Docker images from public registries (no authentication needed)\n\nThe core platform images are publicly available on GitHub Container Registry:\n- `ghcr.io/agentsystems/agent-control-plane:latest`\n\n### Example: interactive laptop\n\n```bash\nagentsystems init\n# prompts for directory and Langfuse setup\n```\n\n### Example: scripted cloud VM / CI\n\n```bash\nagentsystems init /opt/agentsystems/engine\n# Non-interactive mode - uses defaults for Langfuse\n```\n\n---\n## Multi-registry agent ecosystem\n\nAgent 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.\n\n```yaml\nregistry_connections:\n  dockerhub_main:\n    url: docker.io\n    enabled: true\n    auth:\n      method: basic\n      username_env: DOCKERHUB_USER\n      password_env: DOCKERHUB_TOKEN\n\nagents:\n  - name: hello-world\n    registry_connection: dockerhub_main\n    repo: agentsystems/hello-world-agent\n    tag: latest\n```\n\nWhen 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.\n\n---\n## Environment variables \u0026 `.env`\n\n\u003e 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.\n\nThe `.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.\nYou can still keep them for reference or delete them entirely.\n\n\u003e 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.\n\n\n---\n## Updating / upgrading\n\n```bash\npipx upgrade agentsystems-sdk           # upgrade from PyPI\n# or, from source repo:\npipx reinstall --editable .\n```\n\n---\n## Security notes\n\n* The CLI is designed not to print secret values. GitHub PATs are masked and Docker login uses `--password-stdin`.\n* Delete tokens / `.env` after the resources become public.\n\n---\n## Support \u0026 feedback\n\nOpen an issue or discussion in the private GitHub repository.\nContributions welcome—see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nLicensed under the [Apache-2.0 license](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentsystems%2Fagentsystems-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentsystems%2Fagentsystems-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentsystems%2Fagentsystems-sdk/lists"}