diff --git a/AGENTS.md b/AGENTS.md index df629243..53bf9ed9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,14 +16,20 @@ environments; agent-env depends on it. Python 3.11 or newer. The repo convention is a `.venv` at the root, which the Makefile and CI use. +```bash +uv sync --extra dev && . .venv/bin/activate +``` + +Without uv: + ```bash python3.11 -m venv .venv && . .venv/bin/activate -pip install -e ./packages/agentenv-protocol -e '.[dev]' # or: uv sync --extra dev +pip install -e ./packages/agentenv-protocol -e '.[dev]' ``` -Install the in-repo protocol package together with the dev extra: agent-env depends on it and the -workspace copy is the one to develop against (`uv sync` does this through the uv workspace in -`pyproject.toml`). `make install` is the same in one step. No cloud credentials are needed; the +Both install the in-repo protocol package together with the dev extra: agent-env depends on it and +the workspace copy is the one to develop against (`uv sync` does this through the uv workspace in +`pyproject.toml`). `make install` is the pip route in one step. No cloud credentials are needed; the default stores are local. ## Commands @@ -36,7 +42,7 @@ default stores are local. | `make installer-test` | `tst/installer`: `plugin add` / `remove` through the real pip, uv and pipx, offline against wheels built from the checkout, and the container user journey (`python:3.12-slim`, `--network none`) with the PEP 668 refusal; needs uv, pipx and Docker | | `make clean-install-test` | the `clean-install` CI gate: both distributions built as the release builds them, installed into a fresh venv from public PyPI with an allowlisted environment, and `agent-env run hello` run twice by name and checked through the local store; needs Python 3.11, uv and git | | `pytest tst/unit/env/store_test.py -v` | one file; add `--log-cli-level=DEBUG` for debug logs | -| `pip install build && python -m build` | wheel `agentenv_framework--py3-none-any.whl` (`src/agent_env` only) and sdist `agentenv_framework-.tar.gz` (`src`, `tst`, the protocol package) | +| `uv build` | wheel `agentenv_framework--py3-none-any.whl` (`src/agent_env` only) and sdist `agentenv_framework-.tar.gz` (`src`, `tst`, the protocol package) | | `agent-env`, `python -m agent_env.cli` | the CLI; `agent-env config show` prints which config file is in effect and where each section came from | ## Configuration @@ -188,7 +194,7 @@ Actions are pinned to commit SHAs. - Versions are cut by the maintainers' release automation. Never edit `version` in `pyproject.toml` or push a tag in a PR. - Names: the distribution is `agentenv-framework`, the import package `agent_env`, the console - script `agent-env`. Only the first is what `pip install` and `importlib.metadata.version()` take. + script `agent-env`. Only the first is what `uv add`, `pip install` and `importlib.metadata.version()` take. - Comments: default to none. The code says what; a docstring of one to three dense lines says why when that is not obvious. No comment that restates the code, no trailing assertion notes in tests. - Imports at module top, never inside functions. diff --git a/README.md b/README.md index ee0cfed8..04f348f5 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,27 @@ agent-env is a Python SDK and CLI for building, deploying and running agentic en ## Install -Both packages are on PyPI. You need Python 3.11 or newer and, to run environments locally, a running Docker daemon: +Both packages are on PyPI. You need Python 3.11 or newer and, to run environments locally, a running Docker daemon. With [uv](https://docs.astral.sh/uv/), install the `agent-env` command as a tool: + +```bash +uv tool install agentenv-framework +agent-env run hello +``` + +`agent-env run hello` runs the built-in hello task, which needs no Docker, model or configuration. To try it without installing anything, run it with uvx: + +```bash +uvx --from agentenv-framework agent-env run hello +``` + +Or install it with pip, into a virtualenv: ```bash pip install agentenv-framework ``` +To use the SDK in your own project, add it as a dependency with `uv add agentenv-framework`. The explorer, `agent-env up`, needs the `explorer` extra (`uv tool install 'agentenv-framework[explorer]'`, or the same extra with uvx or pip) and an `.agentenv/config.toml` in the current folder or above it; an empty one keeps every local default. + The distribution is named `agentenv-framework`, the import package is `agent_env` and the command is `agent-env`. It depends on `agentenv-framework-protocol`, whose import package is `agentenv_protocol`, and installs it too. To work on agent-env itself, install from a clone with [uv](https://docs.astral.sh/uv/): @@ -100,7 +115,7 @@ triage = "mycorp_demo.bundles" ### Plugin settings -A plugin that needs settings of its own reads them from `[plugins.]`, where `` is its distribution name: the name `pip install` takes and `agent-env plugin list` prints. That table belongs to the plugin. agent-env reads nothing in it and checks none of its keys. Every other top-level table belongs to agent-env, which warns about one it does not read in `agent-env config show`, so a plugin keeps nothing of its own anywhere else. +A plugin that needs settings of its own reads them from `[plugins.]`, where `` is its distribution name: the name `uv add` and `pip install` take and `agent-env plugin list` prints. That table belongs to the plugin. agent-env reads nothing in it and checks none of its keys. Every other top-level table belongs to agent-env, which warns about one it does not read in `agent-env config show`, so a plugin keeps nothing of its own anywhere else. ```toml [plugins.acme-agentenv-browser] diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 1e36fb1a..3710880a 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -1,7 +1,8 @@ # agentenv-framework-protocol Open data-plane protocol and server SDK for agent environments. Install it with -`pip install agentenv-framework-protocol`; the import package is `agentenv_protocol`. +`uv add agentenv-framework-protocol` or `pip install agentenv-framework-protocol`; the import +package is `agentenv_protocol`. An environment author writes a class with decorated methods and serves it: