Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (87 loc) · 5.45 KB

AGENTS.md

File metadata and controls

111 lines (87 loc) · 5.45 KB

AGENTS.md

Instructions for AI coding agents working in the Python codebase.

Key Documentation:

Agent Skills (.github/skills/) — detailed, task-specific instructions loaded on demand:

  • python-development — coding standards, type annotations, docstrings, logging, performance
  • python-testing — test structure, fixtures, async mode, running tests
  • python-code-quality — linting, formatting, type checking, prek hooks, CI workflow
  • python-feature-lifecycle — package vs feature lifecycle stages, decorators, enums, and promotion guidance
  • python-package-management — monorepo structure, lazy loading, versioning, new packages
  • python-samples — sample file structure, PEP 723, documentation guidelines

Maintaining Documentation

When making changes to a package, check if the following need updates:

  • The package's AGENTS.md file (adding/removing/renaming public APIs, architecture changes, import path changes)
  • The agent skills in .github/skills/ if conventions, commands, or workflows change

At the end of every run, re-read AGENTS.md and the relevant skill files and update any guidance that the conversation revealed to be out of date, incomplete, or misleading (renamed files, changed commands, new conventions the user confirmed, etc.). Before adding a new principle or rule, ask the user whether they want it captured as a durable principle — do not invent team norms from a single conversation without explicit confirmation.

Terminology

  • Avoid "GA" for Agent Framework code. Reserve GA for hosted services (e.g. "the Foundry service is GA"). For Agent Framework packages, features, and APIs use "released" or "stable" depending on context — these match the feature-lifecycle stages documented in the python-feature-lifecycle skill.

Pull Request Description Guidance

When preparing a PR description:

  • Follow the repository PR template at .github/pull_request_template.md and keep its structure/headings.
  • Describe the net change relative to main (this is implied; do not call it out explicitly as "vs main").
  • Do not add ad-hoc validation sections (for example, "Validation" or "Tests run"); CI/CD and the template checklist cover validation status.

Quick Reference

Run uv run poe from the python/ directory to see available commands. See DEV_SETUP.md for detailed usage.

Project Structure

python/
├── packages/
│   ├── core/                 # agent-framework-core (main package)
│   │   ├── agent_framework/  # Public API exports
│   │   └── tests/
│   ├── foundry/              # agent-framework-foundry
│   ├── anthropic/            # agent-framework-anthropic
│   ├── ollama/               # agent-framework-ollama
│   └── ...                   # Other provider packages
├── samples/                  # Sample code and examples
├── .github/skills/           # Agent skills for Copilot
└── tests/                    # Integration tests

Package Relationships

  • agent-framework-core contains core abstractions and OpenAI/Azure OpenAI built-in
  • Provider packages (foundry, anthropic, etc.) extend core with specific integrations
  • Core uses lazy loading via __getattr__ in provider folders (e.g., agent_framework/azure/)

Package Documentation

Core

  • core - Core abstractions, types, and built-in OpenAI/Azure OpenAI support

LLM Providers

Azure Integrations

Protocols & UI

  • a2a - Agent-to-Agent protocol
  • ag-ui - AG-UI protocol
  • chatkit - OpenAI ChatKit integration
  • devui - Developer UI for testing

Storage & Memory

  • mem0 - Mem0 memory integration
  • redis - Redis storage

Infrastructure

Experimental

  • lab - Experimental features
  • monty - Monty-backed CodeAct integrations (alpha)