agent/agent-framework
1
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Python: updated doc generation setup and some slight api enhancements (#267)

Browse Source 
* updated doc generation setup and some slight api enhancements

* small fix in index
This commit is contained in:
Eduard van Valkenburg
2025-07-31 17:04:22 +02:00
committed by GitHub
Unverified
parent 139f033b05
commit 42c7a59640
28 changed files with 216 additions and 251 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/packages/main/agent_framework/__init__.py
-1
View File
@@ -11,6 +11,5 @@ except importlib.metadata.PackageNotFoundError:
from ._agents import * # noqa: F403
from ._clients import * # noqa: F403
from ._logging import * # noqa: F403
from ._pydantic import * # noqa: F403
from ._tools import * # noqa: F403
from ._types import * # noqa: F403
python/packages/main/agent_framework/_clients.py
+6 -7
View File
@@ -225,22 +225,21 @@ def use_tool_calling(cls: type[TChatClientBase]) -> type[TChatClientBase]:
Remarks:
This only works on classes that derive from ChatClientBase
and the _inner_get_response
and _inner_get_streaming_response methods.
It also sets a __maximum_iterations_per_request attribute on the class.
and the `_inner_get_response`
and `_inner_get_streaming_response` methods.
It also sets a `__maximum_iterations_per_request` attribute on the class.
if you want to expose this to end_users, do a version of this:
```python
@use_tool_calling
class MyChatClient(ChatClientBase):
@property
def maximum_iterations_per_request(self):
return getattr(self, "__maximum_iterations_per_request", 10)
@maximum_iterations_per_request.setter
def maximum_iterations_per_request(self, value: int) -> None:
setattr(self, "__maximum_iterations_per_request", value)
```
"""
setattr(cls, "__maximum_iterations_per_request", 10)
python/packages/main/agent_framework/_pydantic.py
+5 -5
View File
@@ -29,11 +29,11 @@ class AFBaseSettings(BaseSettings):
In the case where a value is specified for the same Settings field in multiple ways,
the selected value is determined as follows (in descending order of priority):
- Arguments passed to the Settings class initializer.
- Environment variables, e.g. my_prefix_special_function as described above.
- Variables loaded from a dotenv (.env) file.
- Variables loaded from the secrets directory.
- The default field values for the Settings model.
- Arguments passed to the Settings class initializer.
- Environment variables, e.g. my_prefix_special_function as described above.
- Variables loaded from a dotenv (.env) file.
- Variables loaded from the secrets directory.
- The default field values for the Settings model.
"""
env_prefix: ClassVar[str] = ""
python/packages/main/agent_framework/_tools.py
+9 -7
View File
@@ -146,15 +146,17 @@ def ai_function(
) -> AIFunction[Any, ReturnT]:
"""Decorate a function to turn it into a AIFunction that can be passed to models and executed automatically.
Remarks:
In order to add descriptions to parameters, use:
This function will create a Pydantic model from the function's signature,
which will be used to validate the arguments passed to the function.
And will be used to generate the JSON schema for the function's parameters.
In order to add descriptions to parameters, in your function signature,
use the `Annotated` type from `typing` and the `Field` class from `pydantic`:
```python
from typing import Annotated
from pydantic import Field
from typing import Annotated
arg: Annotated[<type>, Field(description="<description>")]
```
from pydantic import Field
<field_name>: Annotated[<type>, Field(description="<description>")]
Args:
func: The function to wrap. If None, returns a decorator.
python/packages/main/agent_framework/_types.py
+4 -33
View File
@@ -312,9 +312,7 @@ class AIContent(AFBaseModel):
type: Literal["ai"] = "ai"
additional_properties: dict[str, Any] | None = None
"""Additional properties for the content."""
raw_representation: Any | None = Field(default=None, repr=False)
"""The raw representation of the content from an underlying implementation."""
class TextContent(AIContent):
@@ -367,7 +365,9 @@ class TextReasoningContent(AIContent):
raw_representation: Optional raw representation of the content.
""" # TODO(): Should we merge these two classes, and use a property to distinguish them?
"""
# TODO(eavanvalkenburg): Should we merge these two classes, and use a property to distinguish them?
text: str
type: Literal["text_reasoning"] = "text_reasoning" # type: ignore[assignment]
@@ -536,9 +536,7 @@ class UriContent(AIContent):
type: Literal["uri"] = "uri" # type: ignore[assignment]
uri: str
"""The URI of the content, e.g., 'https://example.com/image.png'."""
media_type: str
"""The media type of the content, e.g., 'image/png', 'application/json', etc."""
def __init__(
self,
@@ -604,11 +602,8 @@ class ErrorContent(AIContent):
type: Literal["error"] = "error" # type: ignore[assignment]
error_code: str | None = None
"""The error code associated with the error."""
details: str | None = None
"""Additional details about the error."""
message: str | None
"""The error message."""
def __init__(
self,
@@ -660,13 +655,9 @@ class FunctionCallContent(AIContent):
type: Literal["function_call"] = "function_call" # type: ignore[assignment]
call_id: str
"""The function call identifier."""
name: str
"""The name of the function requested."""
arguments: str | dict[str, Any | None] | None = None
"""The arguments requested to be provided to the function."""
exception: Exception | None = None
"""Any exception that occurred while mapping the original function call data to this representation."""
def __init__(
self,
@@ -753,11 +744,8 @@ class FunctionResultContent(AIContent):
type: Literal["function_result"] = "function_result" # type: ignore[assignment]
call_id: str
"""The identifier of the function call for which this is the result."""
result: Any | None = None
"""The result of the function call, or a generic error message if the function call failed."""
exception: Exception | None = None
"""An exception that occurred if the function call failed."""
def __init__(
self,
@@ -802,7 +790,6 @@ class UsageContent(AIContent):
type: Literal["usage"] = "usage" # type: ignore[assignment]
details: UsageDetails
"""The usage information."""
def __init__(
self,
@@ -812,14 +799,7 @@ class UsageContent(AIContent):
raw_representation: Any | None = None,
**kwargs: Any,
) -> None:
"""Initializes a UsageContent instance.
Args:
details: The usage information.
additional_properties: Optional additional properties associated with the content.
raw_representation: Optional raw representation of the content.
**kwargs: Any additional keyword arguments.
"""
"""Initializes a UsageContent instance."""
super().__init__(
details=details, # type: ignore[reportCallIssue]
raw_representation=raw_representation,
@@ -890,15 +870,6 @@ class ChatFinishReason(AFBaseModel):
Attributes:
value: The string representation of the finish reason.
Properties:
CONTENT_FILTER: The model filtered content, whether for safety, prohibited content, sensitive content,
or other such issues.
LENGTH: The model reached the maximum length allowed for the request and/or response (typically in
terms of tokens).
STOP: The model encountered a natural stop point or provided stop sequence.
TOOL_CALLS: The model requested the use of a tool that was defined in the request.
"""
value: str
python/packages/main/agent_framework/azure/__init__.py
+1
View File
@@ -7,6 +7,7 @@ PACKAGE_NAME = "agent_framework_azure"
PACKAGE_EXTRA = "azure"
_IMPORTS = [
"AzureChatClient",
"AzureOpenAISettings",
"get_entra_auth_token",
"__version__",
]
python/packages/main/agent_framework/azure/__init__.pyi
+2
View File
@@ -2,12 +2,14 @@
from agent_framework_azure import (
AzureChatClient,
AzureOpenAISettings,
__version__,
get_entra_auth_token,
)
__all__ = [
"AzureChatClient",
"AzureOpenAISettings",
"__version__",
"get_entra_auth_token",
]
python/packages/main/agent_framework/foundry/__init__.py
+1 -1
View File
@@ -5,7 +5,7 @@ from typing import Any
PACKAGE_NAME = "agent_framework_foundry"
PACKAGE_EXTRA = "foundry"
_IMPORTS = ["__version__", "FoundryChatClient"]
_IMPORTS = ["__version__", "FoundryChatClient", "FoundrySettings"]
def __getattr__(name: str) -> Any:
python/packages/main/agent_framework/foundry/__init__.pyi
+2 -2
View File
@@ -1,5 +1,5 @@
# Copyright (c) Microsoft. All rights reserved.
from agent_framework_foundry import FoundryChatClient, __version__
from agent_framework_foundry import FoundryChatClient, FoundrySettings, __version__
__all__ = ["FoundryChatClient", "__version__"]
__all__ = ["FoundryChatClient", "FoundrySettings", "__version__"]
python/packages/main/agent_framework/openai/_chat_client.py
+9 -8
View File
@@ -286,26 +286,27 @@ class OpenAIChatClient(OpenAIConfigBase, OpenAIChatClientBase):
org_id: str | None = None,
default_headers: Mapping[str, str] | None = None,
async_client: AsyncOpenAI | None = None,
instruction_role: str | None = None,
env_file_path: str | None = None,
env_file_encoding: str | None = None,
instruction_role: str | None = None,
) -> None:
"""Initialize an OpenAIChatCompletion service.
Args:
ai_model_id (str): OpenAI model name, see
ai_model_id: OpenAI model name, see
https://platform.openai.com/docs/models
api_key (str | None): The optional API key to use. If provided will override,
api_key: The optional API key to use. If provided will override,
the env vars or .env file value.
org_id (str | None): The optional org ID to use. If provided will override,
org_id: The optional org ID to use. If provided will override,
the env vars or .env file value.
default_headers: The default headers mapping of string keys to
string values for HTTP requests. (Optional)
async_client (Optional[AsyncOpenAI]): An existing client to use. (Optional)
env_file_path (str | None): Use the environment settings file as a fallback
async_client: An existing client to use. (Optional)
instruction_role: The role to use for 'instruction' messages, for example,
"system" or "developer". If not provided, the default is "system".
env_file_path: Use the environment settings file as a fallback
to environment variables. (Optional)
env_file_encoding (str | None): The encoding of the environment settings file. (Optional)
instruction_role (str | None): The role to use for 'instruction' messages, for example,
env_file_encoding: The encoding of the environment settings file. (Optional)
"""
try:
openai_settings = OpenAISettings(
python/packages/main/agent_framework/openai/_responses_client.py
+9 -8
View File
@@ -66,26 +66,27 @@ class OpenAIResponsesClient(OpenAIConfigBase, ChatClientBase, OpenAIHandler):
org_id: str | None = None,
default_headers: Mapping[str, str] | None = None,
async_client: AsyncOpenAI | None = None,
instruction_role: str | None = None,
env_file_path: str | None = None,
env_file_encoding: str | None = None,
instruction_role: str | None = None,
) -> None:
"""Initialize an OpenAIChatCompletion service.
Args:
ai_model_id (str): OpenAI model name, see
ai_model_id: OpenAI model name, see
https://platform.openai.com/docs/models
api_key (str | None): The optional API key to use. If provided will override,
api_key: The optional API key to use. If provided will override,
the env vars or .env file value.
org_id (str | None): The optional org ID to use. If provided will override,
org_id: The optional org ID to use. If provided will override,
the env vars or .env file value.
default_headers: The default headers mapping of string keys to
string values for HTTP requests. (Optional)
async_client (Optional[AsyncOpenAI]): An existing client to use. (Optional)
env_file_path (str | None): Use the environment settings file as a fallback
async_client: An existing client to use. (Optional)
instruction_role: The role to use for 'instruction' messages, for example,
"system" or "developer". If not provided, the default is "system".
env_file_path: Use the environment settings file as a fallback
to environment variables. (Optional)
env_file_encoding (str | None): The encoding of the environment settings file. (Optional)
instruction_role (str | None): The role to use for 'instruction' messages, for example,
env_file_encoding: The encoding of the environment settings file. (Optional)
"""
try:
openai_settings = OpenAISettings(
python/packages/main/agent_framework/openai/_shared.py
+27 -26
View File
@@ -54,43 +54,44 @@ OPTION_TYPE = Union[
__all__ = [
"OpenAIHandler",
"OpenAIModelTypes",
"OpenAISettings",
]
class OpenAISettings(AFBaseSettings):
"""OpenAI model settings.
"""OpenAI environment settings.
The settings are first loaded from environment variables with the prefix 'OPENAI_'.
If the environment variables are not found, the settings can be loaded from a .env file with the
encoding 'utf-8'. If the settings are not found in the .env file, the settings are ignored;
however, validation will fail alerting that the settings are missing.
Optional settings for prefix 'OPENAI_' are:
- api_key: SecretStr - OpenAI API key, see https://platform.openai.com/account/api-keys
(Env var OPENAI_API_KEY)
- org_id: str | None - This is usually optional unless your account belongs to multiple organizations.
(Env var OPENAI_ORG_ID)
- chat_model_id: str | None - The OpenAI chat model ID to use, for example, gpt-3.5-turbo or gpt-4.
(Env var OPENAI_CHAT_MODEL_ID)
- responses_model_id: str | None - The OpenAI responses model ID to use, for example, gpt-4o or o1.
(Env var OPENAI_RESPONSES_MODEL_ID)
- text_model_id: str | None - The OpenAI text model ID to use, for example, gpt-3.5-turbo-instruct.
(Env var OPENAI_TEXT_MODEL_ID)
- embedding_model_id: str | None - The OpenAI embedding model ID to use, for example, text-embedding-ada-002.
(Env var OPENAI_EMBEDDING_MODEL_ID)
- text_to_image_model_id: str | None - The OpenAI text to image model ID to use, for example, dall-e-3.
(Env var OPENAI_TEXT_TO_IMAGE_MODEL_ID)
- audio_to_text_model_id: str | None - The OpenAI audio to text model ID to use, for example, whisper-1.
(Env var OPENAI_AUDIO_TO_TEXT_MODEL_ID)
- text_to_audio_model_id: str | None - The OpenAI text to audio model ID to use, for example, jukebox-1.
(Env var OPENAI_TEXT_TO_AUDIO_MODEL_ID)
- realtime_model_id: str | None - The OpenAI realtime model ID to use,
for example, gpt-4o-realtime-preview-2024-12-17.
(Env var OPENAI_REALTIME_MODEL_ID)
- env_file_path: str | None - if provided, the .env settings are read from this file path location
Attributes:
api_key: OpenAI API key, see https://platform.openai.com/account/api-keys
(Env var OPENAI_API_KEY)
org_id: This is usually optional unless your account belongs to multiple organizations.
(Env var OPENAI_ORG_ID)
chat_model_id: The OpenAI chat model ID to use, for example, gpt-3.5-turbo or gpt-4.
(Env var OPENAI_CHAT_MODEL_ID)
responses_model_id: The OpenAI responses model ID to use, for example, gpt-4o or o1.
(Env var OPENAI_RESPONSES_MODEL_ID)
text_model_id: The OpenAI text model ID to use, for example, gpt-3.5-turbo-instruct.
(Env var OPENAI_TEXT_MODEL_ID)
embedding_model_id: The OpenAI embedding model ID to use, for example, text-embedding-ada-002.
(Env var OPENAI_EMBEDDING_MODEL_ID)
text_to_image_model_id: The OpenAI text to image model ID to use, for example, dall-e-3.
(Env var OPENAI_TEXT_TO_IMAGE_MODEL_ID)
audio_to_text_model_id: The OpenAI audio to text model ID to use, for example, whisper-1.
(Env var OPENAI_AUDIO_TO_TEXT_MODEL_ID)
text_to_audio_model_id: The OpenAI text to audio model ID to use, for example, jukebox-1.
(Env var OPENAI_TEXT_TO_AUDIO_MODEL_ID)
realtime_model_id: The OpenAI realtime model ID to use,
for example, gpt-4o-realtime-preview-2024-12-17.
(Env var OPENAI_REALTIME_MODEL_ID)
Parameters:
env_file_path: The path to the .env file to load settings from.
env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
"""
env_prefix: ClassVar[str] = "OPENAI_"