Install

Requirements

Python >=3.11,<3.13. The repository pins 3.11 via .python-version, and the resolver rejects 3.10 and 3.13 outright.
uv for environment and dependency management.
Docker, only if you intend to run the integration or docker-backed semantics test tiers. Unit tests must pass with no docker.

From source

git clone https://github.com/ardada2468/beam-agents
cd beam-agents
uv sync --all-groups
uv run pre-commit install

Or equivalently, make bootstrap.

Verify the install:

uv run python -c "import beam_agents; print(sorted(beam_agents.__all__))"

Importing the package performs no I/O, spawns no threads, and imports no optional dependency.

To confirm the whole checkout is healthy, run the offline test tier. It needs no credentials and no docker, and it is the same tier CI requires on every change:

make test-unit

Optional extras

Nine extras exist, and each is genuinely optional — the core install works without any of them.

Extra	Provides	Pulls in
`langgraph`	The `beam_agents.adapters.langgraph` adapter and `LangGraphAgent`	`langgraph>=1.0,<2`, `langchain-core>=1.0,<2`
`pydantic-ai`	The `beam_agents.adapters.pydantic_ai` adapter and `PydanticAIAgent`	`pydantic-ai-slim>=2.21,<3`
`adk`	The `beam_agents.adapters.adk` adapter and `AdkAgent`	`google-adk>=2.6,<3`
`effector`	The reference effector service and its IO clients	`aiokafka`, `google-cloud-pubsub`, `redis`, `google-cloud-bigtable`
`otlp`	The `otlp://` trace sink	`opentelemetry-proto>=1.20`
`vllm`	The in-process engine behind `VllmSidecarProvider` (the endpoint provider needs no extra)	`vllm>=0.6`
`memory-stores`	The long-term `MemoryStore` backends: Bigtable, Redis, Firestore, SQL	`google-cloud-bigtable`, `redis`, `google-cloud-firestore`, `sqlalchemy[asyncio]`
`console`	The agent console's API server	`fastapi>=0.115`, `uvicorn[standard]>=0.30`, `sse-starlette>=2.1`
`console-ingest`	The console's Kafka and BigQuery ingestion	`aiokafka`, `google-cloud-bigquery`

From a source checkout:

uv sync --extra langgraph

The adapter entry points — LangGraphAgent, PydanticAIAgent, AdkAgent — are exported lazily. Without the matching extra, accessing one raises an ImportError naming the extra to install rather than a bare ModuleNotFoundError.

Depending on it from another project

There is no published version to depend on, so depend on a commit:

uv add "git+https://github.com/ardada2468/beam-agents@<commit-sha>"

Pin the sha, not a branch. main moves, and the declared version does not change with it — 1.0.0 is set once by a release PR, so between releases it says nothing about what is underneath. A branch dependency here is a dependency that can change meaning without changing its name.

The public surface is beam_agents.__all__, frozen name-by-name in public-surface.toml and checked by tests/test_public_surface.py. What that promise covers, and what may still change, is in docs/releasing.md.

Not yet implemented

This page is marked partial because the install story is genuinely incomplete, not because the documentation is:

No published package. There is no pip install beam-agents yet: the release workflow publishes on a v* tag and none has been pushed. Anything you build against this today is built against a git ref.
Private imports in practice. The names in beam_agents.__all__ are the public surface, but writing an agent currently also requires importing from modules the project documents as private — see the API reference for the exact list and why each is needed.

When released

Once a release is published, the install becomes the ordinary one, and this section replaces the source instructions above:

uv pip install 'beam-agents[langgraph]'

Until then, the site's own verifier fails the build if any page presents that command as something that works today.

What beam-agents is — the concepts.
Examples — runnable programs you can copy.