Getting Started

Getting Started

This package needs Python 3.12 or newer and nothing else: no model, no API key, and no network after installation. It was tested on Windows, and it has not been tested on Linux or macOS. A clean copy went through these steps on 2026-11-06 with Python 3.12.10, and the output shown came from that run.

Install

git clone https://github.com/dboles99/agent-gateway.git
cd agent-gateway
python -m venv .venv
.venv/bin/pip install -e ".[dev]"     # Windows: .venv\Scripts\pip install -e ".[dev]"

On Windows, replace .venv/bin/ with .venv\Scripts\ in every command below.

First run

The tour runs offline and writes only to a temporary folder.

.venv/bin/python examples/quickstart.py

admission: DOWNROUTE to worker: primary model not required for bounded implementation
budget: HARD
loop: deny repeat call: True
watchdog: CHECKPOINT_AND_STOP
fallback: fallback, resume at ['rerun tests']
DECISION ACCEPT [MEDIUM] by RG-004 of RELEASE-GATE
  MATCHED RG-004: change.tests_passed == true and change.review_confidence >= 0.9
    change.review_confidence = 0.95
    change.tests_passed = True
DECISION none: no rule matched in RELEASE-GATE
dispatch: passed [{'name': 'word_count', 'value': 4}]
dispatch: blocked capability_unbuilt
pool: completed, demo:latest, review required: True

How It Works reads this output line by line.

Run the tests

.venv/bin/python -m pytest -q

241 passed, 1 skipped

The skipped test needs a real local model. To run it, set AGENT_GATEWAY_LIVE_MODEL to the name of a model you have pulled in Ollama.

Use the command line

The installed command has three groups: governance, gateway, and pool. List what the example config declares:

.venv/bin/agent-gateway gateway capabilities --config examples/capabilities.yaml

unbuilt       text.summarise
ready         text.word_count
              handler: agent_gateway.demo:word_count
              required: word_count

2 declared, 1 built, 1 unbuilt, 0 unresolvable

Run admission on a context capsule:

.venv/bin/agent-gateway governance admit examples/context_capsule.yaml

{
  "status": "DOWNROUTE",
  "model": "worker",
  "reason": "primary model not required for bounded implementation"
}

Evaluate a rule pack:

.venv/bin/agent-gateway governance evaluate-rules examples/rules/release-gate.yaml --context examples/rules/context-pass.json

Dispatch a task packet. The result packet goes to stdout, and the exit code is 0 only on passed:

.venv/bin/agent-gateway gateway execute examples/task_packet.json --config examples/capabilities.yaml

Exit codes

Scripts can treat these commands as gates, and the codes are worth knowing because they separate different facts.

Command	Exit 0	Exit 1	Exit 2
gateway execute	The result is passed	The packet was read and refused	The packet could not be read at all
gateway capabilities	No defects, although capabilities may be unbuilt	A declared handler does not resolve	The config could not be read
governance admit	ALLOW, DOWNROUTE, or CACHE_HIT	REQUIRE_REPAIR or REJECT
governance evaluate-rules	The decision does not block	The decision blocks
governance check-loop	Below the repeat limit	Past the repeat limit

evaluate-rules also exits 0 when the context is empty and nothing matched, so read its output in that case. Limits and Next Steps lists this as the first thing to fix.

Connect it to an agent host

To warn an agent about repeated tool calls, point a PreToolUse hook at the adapter below. It reads the host's JSON payload on stdin, always allows the call, and adds a warning past the limit.

agent-gateway governance check-loop-hook loop_state.json

Configuration

Variable	Meaning	Default
AGENT_GATEWAY_RUN_DIR	Run directory for relative ledger and checkpoint paths	~/.agent_gateway/runs/current
AGENT_GATEWAY_CAPABILITIES	Capability config	./capabilities.yaml
AGENT_GATEWAY_POOL_REGISTRY	Pool model registry	./agent-pool.yaml
AGENT_GATEWAY_POOL_ROLES	Pool roles	./agent-roles.yaml
AGENT_GATEWAY_POOL_ENABLED	Overrides defaults.enabled	File value
AGENT_GATEWAY_POOL_MODE	Overrides defaults.mode	File value
AGENT_GATEWAY_POOL_TELEMETRY	Path for metadata-only telemetry	Off
AGENT_GATEWAY_ALLOW_CLOUD	Permit cloud-execution models	Off
AGENT_GATEWAY_OLLAMA_URL	Ollama base URL	http://127.0.0.1:11434
AGENT_GATEWAY_ENV_FILE	.env file for the command line to load	./.env

The command line loads the .env file. Importing the library does not, and it does not read configuration, touch the network, or write a file.

Next, How It Works explains why these checks exist, and Evidence shows how to confirm these claims in five minutes.