python-installation.md

Python installation and workflows

agentic-api is the Python distribution for the Rust-backed Agentic API gateway. vLLM is a supported inference backend, not part of the Agentic API product name. Use the base wheel when you want a proxy-only install, and add the [local] extra when you want the launcher to manage a local vLLM process.

The Rust-native agentic CLI remains supported for run codex, run claude, serve, and validate.

Install from PyPI

Version 0.7.0 is published on PyPI. Use Python 3.10 or newer. The Python CLI reference lists commands, options, and defaults generated from the parser.

Install the base package

The base wheel bundles the Rust executables and does not install vLLM:

python -m pip install agentic-api==0.7.0
agentic-api serve --vllm-base-url http://existing-vllm:8000

Use this mode when an upstream inference server is already running. Every Python launcher command also works with python -m agentic_api in place of agentic-api.

Install the local extra

On supported Linux GPU hosts, the local extra adds the tested vLLM dependency:

python -m pip install "agentic-api[local]==0.7.0"
agentic-api serve --model Qwen/Qwen3-30B-A3B-FP8

The launcher accepts arbitrary --model values. Choose a model and serving configuration suitable for your hardware. Managed vLLM supports extra arguments after --:

agentic-api serve --model Qwen/Qwen3-30B-A3B-FP8 -- \
  --dtype bfloat16 \
  --max-model-len=32768

The launcher manages --host, --port, and --api-key; do not pass those vLLM options after --. Use --vllm-port and the API-key environment-variable options on the launcher instead.

Run with uvx

With uv installed, run the packaged Rust CLI in an isolated environment without a global installation. Install Codex or Claude Code separately and connect to an existing inference server:

uvx --from agentic-api==0.7.0 agentic --version
uvx --from agentic-api==0.7.0 agentic run codex --upstream http://existing-vllm:8000
uvx --from agentic-api==0.7.0 agentic run claude --upstream http://existing-vllm:8000
uvx --from agentic-api==0.7.0 agentic serve --upstream http://existing-vllm:8000

Install a workflow artifact

To test a wheel before publication, download the artifact for your platform from the release workflow:

python -m pip install /absolute/path/to/agentic_api-PLATFORM.whl

Check the install

doctor reports whether the packaged Rust executable is present, whether the tested local vLLM wheel is installed, and whether the current mode is healthy.

With no mode selected, doctor reports both local and remote health but uses remote health for its exit status, so the base proxy-only install is considered healthy when its packaged gateway is available.

agentic-api doctor
agentic-api doctor --mode remote
agentic-api doctor --mode local
agentic-api doctor --mode remote --json

Use --mode remote when you only need the packaged Rust gateway checks. Use --mode local when you want to verify the tested vLLM runtime and executable are available.

Rust-native CLI usage

The Python package does not replace the Rust CLI. It complements it.

agentic run codex --model MODEL_ID
agentic run claude --model SERVED_MODEL_ALIAS

Known-good model profiles

The matrix below is documentation data, not an allowlist. agentic-api serve still accepts arbitrary --model values. The served alias column is only needed when Claude Code requires a slash-free model name, and the alias values here are examples that should be revalidated on the target Linux GPU before promotion.

Model identifier	Required hardware class	Served alias for Claude Code	Tested launch arguments
Qwen/Qwen3-30B-A3B-FP8	Linux GPU host that can serve a 30B FP8 model	qwen3-30b-a3b-fp8	vllm serve Qwen/Qwen3-30B-A3B-FP8 --reasoning-parser deepseek_r1 --port 5050 and vllm serve Qwen/Qwen3-30B-A3B-FP8 --tool-call-parser hermes --enable-auto-tool-choice --port 5050

Other documented model IDs already exercised in this repository include Qwen/Qwen3.5-35B-A3B-FP8 and Qwen/Qwen3.8-27B-FP8. Treat them as examples pending hardware revalidation rather than as a CLI allowlist.

Publishing wheels (maintainers)

The Release Python GitHub Actions workflow builds and validates Linux x86_64, macOS x86_64, and macOS arm64 wheels. Relevant pull requests, merge-queue entries, and pushes to main run this same release matrix automatically, including installed-wheel tests and the Linux OpenSSL linkage check. These CI runs only build and validate artifacts. It reads [workspace.package].version from Cargo.toml at the selected workflow commit. There is no separate version input or default to maintain. Leave publish unchecked to validate a branch before merging. To publish, select main and check publish; PyPI upload waits for every platform build, installed-wheel test, and wheel check to succeed. Publishing from other branches is blocked. Merging code does not publish a package.

Publish runs check PyPI before building and fail if the declared version already exists. Only a not-found response allows the build to proceed; network errors and other HTTP failures stop the run. Build-only runs skip this check.

The publishing job downloads the validated artifacts from the same workflow run, requires the complete three-wheel set, and uploads them without rebuilding. It uses the pypi GitHub environment and PyPI Trusted Publishing for vllm-project/agentic-api, workflow release-python.yml, environment pypi; no PyPI API token secret is required. The build jobs do not receive the publishing job's OpenID Connect permission.

After merge, a maintainer can dispatch publication with:

gh workflow run release-python.yml --ref main -F publish=true

Review the resolved workspace version and run before announcing availability. Existing files are not silently skipped: if an upload partially succeeds, inspect the PyPI release before deciding how to recover. The workflow does not configure or publish to TestPyPI.