agent-framework 0.0.0__tar.gz → 1.0.0__tar.gz

agent_framework-1.0.0/.cspell.json

@@ -0,0 +1,85 @@
+{
+    "version": "0.2",
+    "languageSettings": [
+        {
+            "languageId": "py",
+            "allowCompoundWords": true,
+            "locale": "en-US"
+        }
+    ],
+    "language": "en-US",
+    "patterns": [
+        {
+            "name": "import",
+            "pattern": "import [a-zA-Z0-9_]+"
+        },
+        {
+            "name": "from import",
+            "pattern": "from [a-zA-Z0-9_]+ import [a-zA-Z0-9_]+"
+        }
+    ],
+    "ignorePaths": [
+        "samples/**",
+        "notebooks/**"
+    ],
+    "words": [
+        "aeiou",
+        "agui",
+        "aiplatform",
+        "azuredocindex",
+        "azuredocs",
+        "azurefunctions",
+        "boto",
+        "contentvector",
+        "contoso",
+        "datamodel",
+        "desync",
+        "dotenv",
+        "endregion",
+        "entra",
+        "faiss",
+        "finalizer",
+        "finalizers",
+        "genai",
+        "generativeai",
+        "hnsw",
+        "httpx",
+        "huggingface",
+        "Instrumentor",
+        "logit",
+        "logprobs",
+        "lowlevel",
+        "Magentic",
+        "mistralai",
+        "mongocluster",
+        "nd",
+        "ndarray",
+        "nopep",
+        "NOSQL",
+        "ollama",
+        "Onnx",
+        "onyourdatatest",
+        "OPENAI",
+        "opentelemetry",
+        "OTEL",
+        "otlp",
+        "powerfx",
+        "protos",
+        "pydantic",
+        "pytestmark",
+        "qdrant",
+        "retrywrites",
+        "serde",
+        "streamable",
+        "superstep",
+        "supersteps",
+        "templating",
+        "uninstrument",
+        "vectordb",
+        "vectorizable",
+        "vectorizer",
+        "vectorstoremodel",
+        "vertexai",
+        "Weaviate"
+    ]
+}

agent_framework-1.0.0/.env.example

@@ -0,0 +1,47 @@
+# Microsoft Foundry
+FOUNDRY_PROJECT_ENDPOINT=""
+# Model used for FoundryChatClient
+FOUNDRY_MODEL=""
+# Foundry Agents (prompt or hosted agents)
+FOUNDRY_AGENT_NAME=""
+FOUNDRY_AGENT_VERSION=""
+# Microsoft Foundry Models endpoint, used by embeddings
+FOUNDRY_MODELS_ENDPOINT=""
+FOUNDRY_MODELS_API_KEY=""
+FOUNDRY_EMBEDDING_MODEL=""
+FOUNDRY_IMAGE_EMBEDDING_MODEL=""
+# Bing connection for web search (optional, used by samples with web search)
+BING_CONNECTION_ID=""
+# Azure AI Search (optional, used by AzureAISearchContextProvider samples)
+AZURE_SEARCH_ENDPOINT=""
+AZURE_SEARCH_API_KEY=""
+AZURE_SEARCH_INDEX_NAME=""
+AZURE_SEARCH_SEMANTIC_CONFIG=""
+AZURE_SEARCH_KNOWLEDGE_BASE_NAME=""
+# Note: For agentic mode Knowledge Bases, also set AZURE_OPENAI_ENDPOINT below
+# (different from AZURE_AI_PROJECT_ENDPOINT - Knowledge Base needs OpenAI endpoint for model calls)
+# OpenAI
+OPENAI_API_KEY=""
+OPENAI_CHAT_COMPLETION_MODEL=""
+OPENAI_CHAT_MODEL=""
+# Azure OpenAI
+AZURE_OPENAI_ENDPOINT=""
+AZURE_OPENAI_CHAT_COMPLETION_MODEL=""
+AZURE_OPENAI_CHAT_MODEL=""
+# Mem0
+MEM0_API_KEY=""
+# Copilot Studio
+COPILOTSTUDIOAGENT__ENVIRONMENTID=""
+COPILOTSTUDIOAGENT__SCHEMANAME=""
+COPILOTSTUDIOAGENT__TENANTID=""
+COPILOTSTUDIOAGENT__AGENTAPPID=""
+# Anthropic
+ANTHROPIC_API_KEY=""
+ANTHROPIC_MODEL=""
+# Ollama
+OLLAMA_ENDPOINT=""
+OLLAMA_MODEL=""
+# Observability
+ENABLE_INSTRUMENTATION=true
+ENABLE_SENSITIVE_DATA=true
+OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317/"

agent_framework-1.0.0/.github/instructions/python.instructions.md

@@ -0,0 +1,6 @@
+---
+applyTo: 'python/**'
+---
+
+See [AGENTS.md](../../AGENTS.md) for project structure and package documentation.
+Detailed conventions are in the agent skills under `.github/skills/`.

agent_framework-1.0.0/.github/skills/python-code-quality/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: python-code-quality
+description: >
+  Code quality checks, linting, formatting, and type checking commands for the
+  Agent Framework Python codebase. Use this when running checks, fixing lint
+  errors, or troubleshooting CI failures.
+---
+
+# Python Code Quality
+
+## Quick Commands
+
+All commands run from the `python/` directory:
+
+```bash
+# Syntax formatting + checks (parallel across packages by default)
+uv run poe syntax
+uv run poe syntax -P core
+uv run poe syntax -F    # Format only
+uv run poe syntax -C    # Check only
+uv run poe syntax -S    # Samples only
+
+# Type checking
+uv run poe pyright       # Pyright fan-out across packages
+uv run poe pyright -P core
+uv run poe pyright -A
+uv run poe mypy          # MyPy fan-out across packages
+uv run poe mypy -P core
+uv run poe mypy -A
+uv run poe typing        # Both pyright and mypy
+uv run poe typing -P core
+uv run poe typing -A
+
+# All package-level checks in parallel (syntax + pyright)
+uv run poe check-packages
+
+# Full check (packages + samples + tests + markdown)
+uv run poe check
+uv run poe check -P core
+
+# Samples only
+uv run poe check -S
+uv run poe pyright -S
+
+# Markdown code blocks
+uv run poe markdown-code-lint
+```
+
+## Pre-commit Hooks (prek)
+
+Prek hooks run automatically on commit. They stay lightweight and only check
+changed files.
+
+```bash
+# Install hooks
+uv run poe prek-install
+
+# Run all hooks manually
+uv run prek run -a
+
+# Run on last commit
+uv run prek run --last-commit
+```
+
+They run changed-package syntax formatting/checking, markdown code lint only
+when markdown files change, and sample syntax lint/pyright only when files
+under `samples/` change.
+They intentionally do not run workspace `pyright` or `mypy` by default.
+
+## Ruff Configuration
+
+- Line length: 120
+- Target: Python 3.10+
+- Auto-fix enabled
+- Rules: ASYNC, B, CPY, D, E, ERA, F, FIX, I, INP, ISC, Q, RET, RSE, RUF, SIM, T20, TD, W, T100, S
+- Scripts directory is excluded from checks
+
+## Pyright Configuration
+
+- Strict mode enabled
+- Excludes: tests, .venv, packages/devui/frontend
+
+## Parallel Execution
+
+The task runner (`scripts/task_runner.py`) executes the cross-product of
+(package × task) in parallel using ThreadPoolExecutor. Single items run
+in-process with streaming output.
+
+## CI Workflow
+
+CI splits into 4 parallel jobs:
+1. **Pre-commit hooks** — lightweight hooks (SKIP=poe-check)
+2. **Package checks** — syntax/pyright via check-packages
+3. **Samples & markdown** — `check -S` plus `markdown-code-lint`
+4. **Mypy** — change-detected mypy checks

agent_framework-1.0.0/.github/skills/python-development/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: python-development
+description: >
+  Coding standards, conventions, and patterns for developing Python code in the
+  Agent Framework repository. Use this when writing or modifying Python source
+  files in the python/ directory.
+---
+
+# Python Development Standards
+
+## File Header
+
+Every `.py` file must start with:
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+```
+
+## Type Annotations
+
+- Always specify return types and parameter types
+- Use `Type | None` instead of `Optional[Type]`
+- Use `from __future__ import annotations` to enable postponed evaluation
+- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)`
+- Use `Mapping` instead of `MutableMapping` for read-only input parameters
+- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods
+    But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes
+
+## Function Parameters
+
+- Positional parameters: up to 3 fully expected parameters
+- Use keyword-only arguments (after `*`) for optional parameters
+- Provide string-based overrides to avoid requiring extra imports:
+
+```python
+def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:
+    if isinstance(tool_mode, str):
+        tool_mode = ChatToolMode(tool_mode)
+```
+
+- Avoid shadowing built-ins (use `next_handler` instead of `next`)
+- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters
+
+## Docstrings
+
+Use Google-style docstrings for all public APIs:
+
+```python
+def equal(arg1: str, arg2: str) -> bool:
+    """Compares two strings and returns True if they are the same.
+
+    Args:
+        arg1: The first string to compare.
+        arg2: The second string to compare.
+
+    Returns:
+        True if the strings are the same, False otherwise.
+
+    Raises:
+        ValueError: If one of the strings is empty.
+    """
+```
+
+- Always document Agent Framework specific exceptions
+- Explicitly use `Keyword Args` when applicable
+- Only document standard Python exceptions when the condition is non-obvious
+
+## Import Structure
+
+```python
+# Core
+from agent_framework import Agent, Message, tool
+
+# Components
+from agent_framework.observability import enable_instrumentation
+
+# Connectors (lazy-loaded)
+from agent_framework.openai import OpenAIChatClient
+from agent_framework.foundry import FoundryChatClient
+```
+
+## Public API and Exports
+
+In `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit
+`__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid
+`from module import *`.
+
+Do not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a
+public import surface (for example, `agent_framework.observability`) should define `__all__`.
+
+```python
+__all__ = ["Agent", "Message", "ChatResponse"]
+
+from ._agents import Agent
+from ._types import Message, ChatResponse
+```
+
+## Performance Guidelines
+
+- Cache expensive computations (e.g., JSON schema generation)
+- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths
+- Avoid redundant serialization — compute once, reuse
+
+## Style
+
+- Line length: 120 characters
+- Format only files you changed, not the entire codebase
+- Prefer attributes over inheritance when parameters are mostly the same
+- Async by default — assume everything is asynchronous
+
+## Naming Conventions for Connectors
+
+- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services
+- `_parse_<object>_from_<source>` for methods that process data from external services

agent_framework-1.0.0/.github/skills/python-feature-lifecycle/SKILL.md

@@ -0,0 +1,238 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+---
+name: python-feature-lifecycle
+description: >
+  Guidance for package and feature lifecycle in the Agent Framework Python
+  codebase, including stage meanings, feature-stage decorators, feature enums,
+  and how to move APIs from one stage to the next.
+---
+
+# Python Feature Lifecycle
+
+## Two lifecycle levels
+
+Agent Framework uses lifecycle at two different levels:
+
+1. **Package lifecycle** — the maturity of the package as a whole
+2. **Feature lifecycle** — the maturity of a specific API or feature inside that package
+
+These are related, but they are **not the same thing**.
+
+- The **package stage is the default** for everything in the package.
+- **Feature-stage decorators are only for exceptions** when a feature is behind the package's default stage.
+- Do **not** decorate every class or function just because the package is experimental or release candidate.
+
+### Important default
+
+If a package is still in **beta / experimental preview**, all public APIs in that package are experimental by default.
+
+- Do **not** add `@experimental(...)` everywhere in that package.
+- The package stage already communicates that default.
+
+Once a package moves forward, you can keep individual features behind:
+
+- If a package moves to **release candidate**, a feature may remain **experimental**
+- If a package moves to **released / GA**, a feature may remain **experimental** or **release candidate**
+
+That is the main use case for feature-stage decorators.
+
+## The four stages
+
+### 1. Experimental
+
+Use for features that are still unstable and may change or be removed without notice.
+
+Feature-level code pattern:
+
+```python
+from ._feature_stage import ExperimentalFeature, experimental
+
+
+@experimental(feature_id=ExperimentalFeature.MY_FEATURE)
+class MyFeature:
+    ...
+```
+
+Behavior:
+
+- Adds an experimental warning block to the docstring
+- Records feature metadata on the decorated object
+- Emits a runtime warning the first time the feature is used (once per feature by default)
+
+Enum setup:
+
+- Add an all-caps member to `ExperimentalFeature`
+- Reuse the same feature ID across all APIs that belong to the same conceptual feature
+
+### 2. Release candidate
+
+Use for features that are nearly stable but may still receive small refinements before GA.
+
+Feature-level code pattern:
+
+```python
+from ._feature_stage import ReleaseCandidateFeature, release_candidate
+
+
+@release_candidate(feature_id=ReleaseCandidateFeature.MY_FEATURE)
+class MyFeature:
+    ...
+```
+
+Behavior:
+
+- Adds a release-candidate note to the docstring
+- Records feature metadata on the decorated object
+- Does **not** emit the experimental warning
+
+Enum setup:
+
+- Add an all-caps member to `ReleaseCandidateFeature`
+
+### 3. Released
+
+Use for stable GA APIs.
+
+Code pattern:
+
+- **No feature-stage decorator**
+- **No entry** in `ExperimentalFeature`
+- **No entry** in `ReleaseCandidateFeature`
+
+If a feature is fully released, remove any stage-specific feature annotation.
+
+### 4. Deprecated
+
+Use for APIs that still exist but should not be used for new code.
+
+Code pattern:
+
+```python
+import sys
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import deprecated  # type: ignore # pragma: no cover
+
+
+@deprecated("MyOldFeature is deprecated. Use MyNewFeature instead.")
+class MyOldFeature:
+    ...
+```
+
+Behavior:
+
+- Uses the repository's version-conditional deprecation import pattern
+- Should describe what to use instead
+
+Deprecated APIs should not also carry feature-stage decorators.
+
+## Expected decorators by stage
+
+| Feature stage | Expected annotation |
+| --- | --- |
+| Experimental | `@experimental(feature_id=ExperimentalFeature.X)` |
+| Release candidate | `@release_candidate(feature_id=ReleaseCandidateFeature.X)` |
+| Released | No feature-stage decorator |
+| Deprecated | `@deprecated("...")` |
+
+## Feature enums
+
+The feature enums are the inventory of currently staged features:
+
+- `ExperimentalFeature`
+- `ReleaseCandidateFeature`
+
+Guidance:
+
+- Use one enum member per conceptual feature, not per class
+- Ideally, an ADR already defines the overall feature boundary and therefore the feature ID that staged APIs for that feature should reuse
+- Keep feature IDs all caps
+- Reuse the same member across related APIs for the same feature
+- Remove enum members when the feature no longer belongs to that stage
+- Treat these enums as **current-stage inventories**, not as a stable consumer introspection API
+
+Minimal consumer guidance:
+
+- Treat `__feature_stage__` and `__feature_id__` as optional staged metadata, not as stable contracts
+- Use `getattr(obj, "__feature_stage__", None)` and `getattr(obj, "__feature_id__", None)` rather than direct attribute access
+- Treat missing metadata as "no explicit feature-stage annotation"
+- For warning filters while a feature is staged, match the literal feature ID string
+- Do **not** rely on `ExperimentalFeature.X`, `ReleaseCandidateFeature.X`, or the continued presence of `__feature_id__` after a feature moves stages or is released
+
+For consumers, the enums are also re-exported from `agent_framework`.
+
+For internal implementation code inside `agent_framework`, continue to import the enums and decorators from `._feature_stage`.
+
+## Package stage vs feature stage
+
+Use the following rules:
+
+### Package is experimental / beta
+
+- All public APIs are experimental by default
+- Do **not** add feature-stage decorators just to restate that
+- Only introduce feature-level annotations later if the package advances first
+
+### Package is release candidate
+
+- All public APIs are RC by default
+- Do **not** decorate everything
+- Add `@experimental(...)` only for features that are intentionally still behind the package
+
+### Package is released / GA
+
+- All public APIs are released by default
+- Add `@experimental(...)` or `@release_candidate(...)` only for features still being held back
+
+## Moving a feature from one stage to the next
+
+### Experimental -> Release candidate
+
+1. Move the feature ID from `ExperimentalFeature` to `ReleaseCandidateFeature`
+2. Replace `@experimental(...)` with `@release_candidate(...)`
+3. Update any tests or docs that mention the old stage
+
+### Experimental -> Released
+
+1. Remove `@experimental(...)`
+2. Remove the feature from `ExperimentalFeature`
+3. Do not add a replacement feature-stage decorator
+
+### Release candidate -> Released
+
+1. Remove `@release_candidate(...)`
+2. Remove the feature from `ReleaseCandidateFeature`
+3. Leave the API undecorated
+
+### Any stage -> Deprecated
+
+1. Remove any feature-stage decorator
+2. Remove the feature from the stage enum
+3. Add `@deprecated("...")`
+4. Update docs/tests to reflect the replacement path
+
+## Promotion guidance
+
+Features do **not** have to pass through every stage.
+
+- It is usually a good idea to move features in order when that reflects reality
+- But it is completely acceptable to go **experimental -> released**
+- Do **not** force a feature through release candidate if there is no real RC period
+
+Likewise, when a package advances, do not automatically move every feature with it.
+
+- Promote features based on actual readiness
+- Keep lagging features explicitly marked only when they are behind the package default
+
+## Practical rules of thumb
+
+- **Package default first, feature exceptions second**
+- **Do not decorate everything in preview packages**
+- **Do not double-annotate members of an already-staged class**
+- **Use enums only for currently staged features**
+- **Do not treat stage enums as a compatibility contract**
+- **Treat `__feature_stage__` and `__feature_id__` as optional metadata; use `getattr`**
+- **Remove stage annotations once a feature is released or deprecated**