21. Package Distribution

Code that lives only on your machine doesn't exist. Distributing agents as packages enables reuse, version management, and collaboration.

Package Structure

# pyproject.toml for agent packages

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-text-processor"
version = "0.2.1"
description = "Text processing agent for document analysis"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "numpy>=1.24.0",
    "transformers>=4.30.0",
]

[project.optional-dependencies]
dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "black", "mypy"]

[project.entry-points]
"agentframework.agents" = "my_text_processor:TextProcessorAgent"

Agent Discovery via Entry Points

Let other packages discover your agent automatically:

# In your agent package's __init__.py
from importlib.metadata import entry_points

def get_available_agents() -> dict[str, type]:
    """Discover all registered agents."""
    try:
        eps = entry_points(group="agentframework.agents")
        return {ep.name: ep.load() for ep in eps}
    except TypeError:  # Python 3.9 compatibility
        eps = entry_points().get("agentframework.agents", [])
        return {ep.name: ep.load() for ep in eps}

Version Compatibility

Agents often depend on specific framework versions:

from packaging.requirements import Requirement

def check_compatibility(agent_version: str, framework_version: str) -> bool:
    """Check if an agent is compatible with the current framework."""
    requirements = [
        "agent-framework>=1.0.0,<2.0.0",  # From agent's pyproject.toml
    ]
    
    for req in requirements:
        requirement = Requirement(req)
        # Simple version check - real implementation uses packaging.version
        # This is illustrative only
        pass

Dependency Conflicts

Agents with conflicting dependencies can't run in the same process. Document this:

# In your agent's README

## Requirements

- Python 3.10 or later
- This agent requires `torch==2.0.0` specifically due to model checkpoint compatibility.
  
## Known Conflicts

- Cannot run alongside `image-generator` agent in the same process 
  (torch version mismatch). Run in separate processes or containers.

Local verification checkpoint

Run the smallest example from this chapter in a local workspace and record the package version, runtime, data path, and observed output. If the result depends on model size, vector count, CPU/GPU backend, or available memory, note that constraint beside the exercise so the lesson remains reproducible.