agent-framework 1.4.0__tar.gz → 1.6.0__tar.gz

agent_framework-1.6.0/.env.example

@@ -0,0 +1,49 @@
+# 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=""
+# Google Gemini
+GEMINI_API_KEY=""
+GEMINI_MODEL=""
+# Ollama
+OLLAMA_ENDPOINT=""
+OLLAMA_MODEL=""
+# Observability (instrumentation is enabled by default; set "ENABLE_INSTRUMENTATION" to "false" to opt out)
+ENABLE_SENSITIVE_DATA=true
+OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317/"

agent_framework-1.6.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_sensitive_telemetry
+
+# 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.6.0/AGENTS.md

@@ -0,0 +1,96 @@
+# 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
+- `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
+
+## 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
+- 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)