pypi-agent-packaging

PyPI Agent Packaging

When to Use PyPI

PyPI is the right distribution channel when:

The key advantage of PyPI: uvx my-agent gives users a zero-install experience. No cloning, no virtual environment setup, no dependency management. It just works.

pyproject.toml Anatomy for AI Agents

pyproject.toml is the single source of truth for your Python package. Every field below is annotated with why it matters for agents specifically.

[project]
name = "my-agent"                          # PyPI package name (globally unique)
version = "0.1.0"                          # Semver — bump on every publish
description = "An AI agent that researches topics and writes summaries"
readme = "README.md"
license = { text = "MIT" }
requires-python = ">=3.11"                 # Pin minimum Python — agents use modern features
authors = [
    { name = "Your Name", email = "[email protected]" },
]
keywords = ["ai", "agent", "langchain", "cli"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Environment :: Console",
    "Intended Audience :: Developers",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
]

# Core dependencies — keep this list SMALL
# Users who run `pip install my-agent` get only these
dependencies = [
    "anthropic>=0.40.0",                   # API client (lightweight)
    "click>=8.0",                          # CLI framework
    "python-dotenv>=1.0",                  # .env file support
    "rich>=13.0",                          # Terminal formatting
    "httpx>=0.27",                         # Async HTTP client
]

[project.optional-dependencies]
# Heavy ML deps are opt-in, not forced on every user
gpu = [
    "torch>=2.0",
    "transformers>=4.40",
    "sentence-transformers>=3.0",
]
# LangChain ecosystem (large dependency tree)
langchain = [
    "langchain>=0.3.0",
    "langchain-anthropic>=0.3.0",
    "langchain-community>=0.3.0",
]
# Development tools
dev = [
    "pytest>=8.0",
    "pytest-asyncio>=0.24",
    "ruff>=0.8.0",
    "mypy>=1.13",
]

# THIS IS CRITICAL — without this, your agent has no CLI command
[project.scripts]
my-agent = "my_agent.cli:main"            # `my-agent` command → calls main() in cli.py

# For MCP servers, also add:
# my-agent-mcp = "my_agent.mcp_server:main"

[project.urls]
Homepage = "https://github.com/your-org/my-agent"
Repository = "https://github.com/your-org/my-agent"
Issues = "https://github.com/your-org/my-agent/issues"

# =========================================================================
# Build system — Hatchling is modern, fast, and requires minimal config
# =========================================================================
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/my_agent"]                # Tells hatch where to find your package

# =========================================================================
# Tool configurations
# =========================================================================
[tool.ruff]
target-version = "py311"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.mypy]
python_version = "3.11"
strict = true