AgentControl Universal Agent SDK

AgentControl is an enterprise-grade toolkit that standardises how autonomous engineers and human teams operate on any codebase. The SDK provisions a consistent command surface, deterministic governance assets, and ready-to-use agent runtimes, so delivery begins immediately without bespoke project bootstrapping.

1. Value Proposition

• Single operational entrypoint. The agentcall CLI aligns humans and agents on the same verified pipelines (init, verify, ship, status, and more).
• Integrated governance. Roadmaps, task boards, and architecture manifests remain in sync through automated status and progress commands.
• Agent-first runtime. Codex/Claude CLIs, Memory Heart, and supporting scripts install without manual steps, keeping cognitive load low for automated contributors.
• Compliance by default. Lockfiles, SBOM generation, audit artefacts, and release gates are embedded into the workflow.

2. Solution Architecture

3. Quick Start (fresh machine)

1. Prerequisites. Bash ≥ 5.0, Python ≥ 3.10, Node.js ≥ 18, Cargo ≥ 1.75. Pin versions in CI for reproducibility.
2. Install the SDK globally.

   ./scripts/install_agentcontrol.sh
   pipx install agentcontrol  # alternatively: python3 -m pip install agentcontrol
   

   Templates are placed under ~/.agentcontrol/templates/<channel>/<version> and agentcall is published to PATH.
3. Bootstrap a project capsule.

   agentcall init --template python ~/workspace/project
   

   All SDK artefacts live inside project/agentcontrol/; the host repository remains untouched. (Set AGENTCONTROL_AUTO_INIT=1 if you prefer agentcall status to bootstrap automatically.)
4. Authenticate agents.

   cd ~/workspace/project
   agentcall agents auth
   agentcall agents status
   

   Credentials are stored beneath ~/.agentcontrol/state/.
5. Qualify the environment.

   agentcall verify
   

   The pipeline runs formatting, tests, security checks, SBOM, architecture sync, Memory Heart, and emits reports/verify.json.

3.1 Automatic Updates

• agentcall checks PyPI for newer public releases on first invocation (default interval: 6h) and upgrades itself automatically before executing the command.
• Disable on air-gapped hosts via AGENTCONTROL_DISABLE_AUTO_UPDATE=1 or AGENTCONTROL_AUTO_UPDATE=0.
• Choose the updater (pip default, pipx alternative) with AGENTCONTROL_AUTO_UPDATE_MODE.
• Provide an offline fallback by pointing AGENTCONTROL_AUTO_UPDATE_CACHE to a directory with cached wheels (e.g. agentcontrol-<version>-py3-none-any.whl); when PyPI is unreachable the newest cached version greater than the current install is applied and logged as a fallback_* telemetry event.
• For local development or testing you can bypass the dev-environment guard via AGENTCONTROL_ALLOW_AUTO_UPDATE_IN_DEV=1 and simulate network failures with AGENTCONTROL_FORCE_AUTO_UPDATE_FAILURE=1.
• All update attempts are logged as telemetry events (auto-update) with mode, versions, and exit status; after a successful upgrade CLI exits so you can re-run the original command.

4. Command Portfolio

5. Capsule Templates

Custom templates live under src/agentcontrol/templates/<version>/<name>; update template.json accordingly.

6. Release Procedure

1. Update version metadata (src/agentcontrol/__init__.py, pyproject.toml) and changelog.
2. Build artefacts with ./scripts/release.sh (wheel, sdist, SHA256, manifest).
3. Optional publication via python -m twine upload dist/*.
4. Offline install: distribute the .whl and agentcontrol.sha256, then run pipx install --force <wheel>.

7. Observability

• Telemetry is local, stored in ~/.agentcontrol/logs/telemetry.jsonl. Disable with AGENTCONTROL_TELEMETRY=0.
• Memory Heart resides in agentcontrol/state/heart/; query using agentcall heart query or serve via agentcall heart serve.
• Key artefacts: reports/verify.json, reports/status.json, reports/review.json, reports/doctor.json.

8. Service Model

• Product owner: AgentControl Core team (see AGENTS.md).
• Operational coverage: 24/7, with programme-level SLA for agent responses.
• Escalation: raise tasks via agentcall agents workflow --task=<ID> or contact the listed owner directly.

9. FAQ

Q: How do I disable automatic bootstrap? A: Export AGENTCONTROL_NO_AUTO_INIT=1 before running agentcall.

Q: How do I add a custom pipeline? A: Extend agentcontrol/agentcall.yaml and config/commands.sh. The command will appear in agentcall commands.

Q: Where is state stored? A: Project-level artefacts live in agentcontrol/state/; global state (registry, credentials) lives under ~/.agentcontrol/state/.

© AgentControl — Universal Agent SDK.