Local development¶

Use Python 3.12 and uv. Development targets Windows x64; the serving container targets Linux x64. Commands below run from the repository root.

Install and check¶

uv sync --locked --all-extras
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest -q

The tests replace the Azure OpenAI HTTP transport, not the Pydantic AI agent or instrumentation. They assert one model request, rejected unauthenticated requests, model failures, and matching agent/trace IDs on framework-generated spans.

These local contracts do not prove Azure model access or Foundry ingestion. For offline Bicep compilation, follow the additional infrastructure validation instructions.

Repository map¶

Location	Responsibility
`src/foundry_aks_agent/`	FastAPI endpoint, Pydantic agent, telemetry, CLI, registration
`deploy/`	Restricted pod, ClusterIP service, service account, configuration
`infra/`	Staged Bicep and operator helpers
`tests/`	Runtime, deployment, and infrastructure contracts
`docs/`	Markdown guides and editable SVG diagrams
`docs_theme/`	Small, script-free documentation theme

Runtime dependencies¶

The project manifest and committed uv.lock are the dependency sources of truth. The runtime pins Pydantic AI 2.31.1 and explicitly uses version 5 instrumentation. Research about newer releases is not an upgrade requirement. See Pydantic instrumentation.

The admin extra contains the Foundry registration SDK. It stays outside the serving image; the CLI calls the existing runtime rather than running an agent on the operator's machine. For cloud execution, continue with configuration and deployment.

Work on these docs¶

The site uses MkDocs with a local theme, no browser JavaScript, and no remote fonts. Its pinned requirements.txt is separate from the runtime lockfile and registration dependencies. --no-project keeps these commands out of the runtime environment.

uv run --no-project --with-requirements docs/requirements.txt mkdocs serve --dev-addr 127.0.0.1:8001

Open the URL printed by MkDocs. To check the static output, including internal Markdown links and anchors:

uv run --no-project --with-requirements docs/requirements.txt mkdocs build --strict

The generated site/ directory is ignored. Edit the Markdown source, not the generated HTML. Navigation lives in mkdocs.yml. Keep diagrams as self-contained SVG with accessible titles/descriptions, exact labels, and separately labeled request/telemetry paths. Use solid arrows by default; dotted or dashed lines must encode a distinction explained in the diagram. The design follows nice-deck's precise-diagram guidance.

GitHub Pages publishing¶

The docs workflow builds pull requests without deployment permissions and publishes only from main. The repository's Pages settings use GitHub Actions as the build and deployment source. See GitHub's custom workflow documentation.

The public address is ericchansen.github.io/foundry-aks-agent. Publishing the documentation never deploys or exposes the agent runtime.