chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,114 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in the Python codebase.
+
+**Key Documentation:**
+- [DEV_SETUP.md](DEV_SETUP.md) - Development environment setup and available poe tasks
+- [CODING_STANDARD.md](CODING_STANDARD.md) - Coding standards, docstring format, and performance guidelines
+- [samples/SAMPLE_GUIDELINES.md](samples/SAMPLE_GUIDELINES.md) - Sample structure and guidelines
+
+**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
+- `pull-requests` — writing PR descriptions (template) and handling/resolving PR review comments
+- `agent-framework-py-release` — Python release PR workflow, CHANGELOG-driven package bumps, lifecycle version rules, and dependency-floor validation
+
+## 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](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
+- The root `agent_framework` public API is lazy-loaded from `packages/core/agent_framework/__init__.py` and
+  described for type checkers in `packages/core/agent_framework/__init__.pyi`; keep both plus `__all__` in sync.
+- Core uses lazy loading via `__getattr__` in provider folders (e.g., `agent_framework/azure/`)
+
+## Package Documentation
+
+### Core
+- [core](packages/core/AGENTS.md) - Core abstractions, types, and built-in OpenAI/Azure OpenAI support
+
+### LLM Providers
+- [anthropic](packages/anthropic/AGENTS.md) - Anthropic Claude API
+- [bedrock](packages/bedrock/AGENTS.md) - AWS Bedrock
+- [claude](packages/claude/AGENTS.md) - Claude Agent SDK
+- [foundry_local](packages/foundry_local/AGENTS.md) - Azure AI Foundry Local
+- [ollama](packages/ollama/AGENTS.md) - Local Ollama inference
+
+### Azure Integrations
+- [foundry](packages/foundry/README.md) - Microsoft Foundry chat, agent, memory, and embedding integrations
+- [azure-contentunderstanding](packages/azure-contentunderstanding/AGENTS.md) - Azure Content Understanding context provider
+- [azure-ai-search](packages/azure-ai-search/AGENTS.md) - Azure AI Search RAG
+- [azure-cosmos](packages/azure-cosmos/AGENTS.md) - Azure Cosmos DB-backed history provider
+- [azurefunctions](packages/azurefunctions/AGENTS.md) - Azure Functions hosting
+
+### Protocols & UI
+- [a2a](packages/a2a/AGENTS.md) - Agent-to-Agent protocol
+- [ag-ui](packages/ag-ui/AGENTS.md) - AG-UI protocol
+- [chatkit](packages/chatkit/AGENTS.md) - OpenAI ChatKit integration
+- [devui](packages/devui/AGENTS.md) - Developer UI for testing
+
+### Storage & Memory
+- [mem0](packages/mem0/AGENTS.md) - Mem0 memory integration
+- [redis](packages/redis/AGENTS.md) - Redis storage
+
+### Infrastructure
+- [copilotstudio](packages/copilotstudio/AGENTS.md) - Microsoft Copilot Studio
+- [declarative](packages/declarative/AGENTS.md) - YAML/JSON agent definitions
+- [durabletask](packages/durabletask/AGENTS.md) - Durable execution
+- [github_copilot](packages/github_copilot/AGENTS.md) - GitHub Copilot extensions
+- [purview](packages/purview/AGENTS.md) - Data governance
+
+### Experimental
+- [lab](packages/lab/AGENTS.md) - Experimental features
+- [monty](packages/monty/AGENTS.md) - Monty-backed CodeAct integrations (alpha)