You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 80fbe9a
Browse filesBrowse the repository at this point in the historyBrowse files
This implementation follows the exact patterns established by Microsoft.Extensions.AI's OpenTelemetry instrumentation, ensuring consistency across the AI ecosystem and leveraging proven patterns for telemetry integration.
Copy file name to clipboardExpand all lines: docs/decisions/0008-python-subpackages.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,7 +78,7 @@ The goal is to design a subpackage structure for the Python agent framework that
78
78
- Integrations that are mature and that have released (GA) dependencies and or features on the service side will be moved into the main package, the dependencies of those packages will stay installable under the same `extra` name, so that users do not have to change anything, and we then remove the subpackage itself.
79
79
- All subpackage imports in the code should be from a stable place, mostly vendor-based, so that when something moves from a subpackage to the main package, the import path does not change, so `from agent_framework.google import GoogleChatClient` will always work, even if it moves from the `agent-framework-google` package to the main `agent-framework` package.
80
80
- The imports in those vendor namespaces (these won't be actual python namespaces, just the folders with a __init__.py file and any code) will do lazy loading and raise a meaningful error if the subpackage or dependencies are not installed, so that users know which extra to install with ease.
81
-
- On a case by case basis we can decide to create additional `extras`, that combine multiple subpackages into one extra, so that users that work primarily with one platform can install everything they need with a single extra, for instance you can install with the `agent-framework[azure-purview]` extra that only implement a Azure Purview Middleware, or you can install with the `agent-framework[azure]` extra that includes all Azure related connectors, like `purview`, `content safety` and others (all examples, not actual packages (yet)), regardless of where the code sits, these should always be importable from `agent_framework.azure`.
81
+
- On a case by case basis we can decide to create additional `extras`, that combine multiple subpackages into one extra, so that users that work primarily with one platform can install everything they need with a single extra, for instance you can install with the `agent-framework[azure-purview]` extra that only implements an Azure Purview Middleware, or you can install with the `agent-framework[azure]` extra that includes all Azure related connectors, like `purview`, `content safety` and others (all examples, not actual packages (yet)), regardless of where the code sits, these should always be importable from `agent_framework.azure`.
82
82
- Subpackage naming should also follow this, so in principle a package name is `<vendor/folder>-<feature/brand>`, so `google-gemini`, `azure-purview`, `microsoft-copilotstudio`, etc. For smaller vendors, with less likely to have a multitude of connectors, we can skip the feature/brand part, so `mem0`, `redis`, etc.
Copy file name to clipboardExpand all lines: docs/decisions/0011-create-get-agent-api.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -107,7 +107,7 @@ var agent3 = new AssistantClient(...).CreateAIAgent(...); // Creates a remote ag
107
107
108
108
### Possible Python implementations
109
109
110
-
Methods like `create_agent` and `get_agent` should be implemented separately or defined on some stateless component that will allow to create multiple agents from the same instance/place.
110
+
Methods like `create_agent` and `get_agent` should be implemented separately or defined on some stateless component that will allow creating multiple agents from the same instance/place.
Copy file name to clipboardExpand all lines: docs/specs/004-python-function-calling-loop.md
+24Lines changed: 24 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -369,6 +369,10 @@ that manually replay messages own the equivalent rule: do not resend an approval
369
369
already executing in a worker thread cannot be interrupted and may complete its side effects — its result is
370
370
discarded either way and never reaches the transcript, the model, or history. Middleware must not catch
371
371
`MiddlewareFailure` — swallowing it converts a fail-closed abort back into a running, possibly unguarded loop.
372
+
-`Content.exception` is host-internal diagnostic state. Default `Content.to_dict()` and nested response serialization replace it with a fixed non-sensitive failure marker,
373
+
while the original field remains directly available to trusted local code. Remote protocol serializers use the
374
+
marker only for status and use the channel-visible `result` or `items` for output text. `include_detailed_errors=False` keeps the channel-visible
375
+
result generic; enabling it explicitly may place diagnostic text in the result for that configured channel.
372
376
- Parallel calls retain model order in the returned transcript.
373
377
-`call_id` remains the provider/service correlation id; a locally actionable `function_call` also carries a stable
374
378
Agent Framework occurrence identity in `Content.id`.
@@ -377,6 +381,17 @@ that manually replay messages own the equivalent rule: do not resend an approval
377
381
not invent one.
378
382
- A completed function call/result pair is inert on later turns.
379
383
- Informational-only and declaration-only calls are not executed as local tools.
384
+
- For automatic local execution, provider arguments are JSON-parsed before function middleware. Schema-compatible
385
+
arguments retain the existing normalized mapping contract. A provisional validation failure is not terminal:
386
+
middleware receives the raw mapping and may repair it before calling `call_next()`. The innermost handler validates
387
+
changed or previously invalid arguments immediately before the tool body and writes the normalized mapping back to
388
+
`FunctionInvocationContext.arguments`; unchanged provisionally normalized arguments are reused without running
389
+
validators twice. Middleware that short-circuits without `call_next()` skips final validation and tool execution.
390
+
- Argument-repair middleware must precede security or policy middleware so enforcement observes the effective,
Changing arguments after security middleware has processed them fails closed with `MiddlewareFailure`.
393
+
- Argument-validation failures after middleware retain the established `Argument parsing failed` result contract.
394
+
Exceptions raised by middleware or the tool body retain the separate `Function failed` contract.
380
395
381
396
### Reasoning-bound calls
382
397
@@ -414,6 +429,11 @@ that manually replay messages own the equivalent rule: do not resend an approval
414
429
- If policy middleware detects that the exact resolved invocation changed after approval, the old response executes
415
430
nothing and yields a caller-visible, session-persisted replacement request for the same occurrence; execution
416
431
requires a second approval and happens exactly once.
432
+
- If function middleware repairs an approval-bound call, the old response likewise executes nothing and yields a
433
+
caller-visible, session-persisted replacement request containing the repaired approval-visible arguments. The
434
+
replacement retains the call occurrence identity, rotates request-generation identity, and requires a second
435
+
approval before exactly-once execution. Security middleware transformations that preserve an approval-visible
436
+
placeholder do not disclose the resolved value or trigger a spurious replacement.
417
437
- If session-bound middleware no longer holds the reviewed authority because it expired or was evicted, the matched
418
438
response executes nothing and produces a replacement approval request with the same occurrence identity and a fresh
419
439
request generation. The replacement is caller-visible, becomes the authoritative pending session snapshot, and
@@ -582,7 +602,10 @@ that manually replay messages own the equivalent rule: do not resend an approval
582
602
|---|---|---|
583
603
| Rejected execution | Rejection is a normal terminal result, not an exception to the caller. |`test_unapproved_tool_execution_raises_exception`|
584
604
| Approved tool exception | Generic and detailed error modes preserve one result and one execution. |`test_approved_function_call_with_error_without_detailed_errors`, `test_approved_function_call_with_error_with_detailed_errors`|
605
+
| Tool exception diagnostics | Internal diagnostics remain available to trusted local code, serialization preserves only a fixed failure marker, and explicit detailed-error configuration affects only the channel-visible result. |`packages/core/tests/core/test_types.py::test_function_result_exception_is_internal_by_default`, `packages/core/tests/core/test_function_invocation_logic.py::test_function_invocation_config_include_detailed_errors_false`, `test_function_invocation_config_include_detailed_errors_true`, `test_streaming_function_invocation_config_include_detailed_errors_false`, `test_streaming_function_invocation_config_include_detailed_errors_true`|
585
606
| Approved validation error | Validation failure returns one result without invoking the function body. |`test_approved_function_call_with_validation_error`|
607
+
| Pre-validation middleware repair | Schema-compatible calls retain normalized middleware arguments without duplicate validation. Prepared-value reuse does not require validator outputs to be copyable, and unchanged NaNs remain stable. Identity-only opaque values may be reused for ordinary execution, but security authority rejects them before downstream middleware or the tool body because in-place mutation cannot be detected safely. When provisional validation fails, function middleware observes raw parsed arguments, may repair them before final validation, and the body receives normalized values; short-circuiting skips final validation and execution. Repair after security middleware fails closed using recursive type-aware, float-bit-exact comparison, including invalid and short-circuited mutations. Security inspects exact normalized values, and validation errors after hidden-value resolution do not disclose resolved values or mapping keys, including validator `TypeError` paths. | `test_function_middleware_keeps_normalized_arguments_for_valid_calls`, `test_prepared_arguments_support_noncopyable_validator_output`, `test_nan_prepared_and_approval_snapshots_are_stable`, `test_function_middleware_repairs_raw_arguments_before_validation`, `test_function_middleware_can_short_circuit_before_argument_validation`, `test_invalid_arguments_produced_by_middleware_keep_argument_error_contract`, `packages/core/tests/test_security.py::TestVariableArgumentPolicy::test_security_rejects_opaque_mutable_validator_output`, `test_argument_mutation_after_security_middleware_fails_closed`, `test_security_snapshot_accepts_unchanged_nan`, `test_argument_mutation_after_security_short_circuit_fails_closed`, `test_security_policy_observes_custom_validator_transform_once`, `test_hidden_argument_validation_error_does_not_disclose_resolved_value`, `test_hidden_mapping_key_is_not_disclosed_by_validation_error`, `test_hidden_value_is_not_disclosed_by_validator_type_error`, `test_hidden_argument_can_be_normalized_after_security_check` |
608
+
| Approved middleware repair | Approval binds to the normalized middleware-entry representation, so ordinary Pydantic coercion still completes in one approval round. A changed approval-bound call executes zero times under the old grant, returns a persisted occurrence-bound replacement request in both response modes, and executes once only after the replacement is approved. Recursive type-aware, float-bit-exact comparison treats booleans and numbers, and positive and negative zero, as distinct while keeping unchanged NaNs stable. Opaque mutable normalized values fail closed before approval authority is established. The same replacement rule applies when middleware short-circuits instead of calling the tool. Security expansion preserves approval-visible placeholders. | `test_approved_coercing_arguments_execute_without_replacement`, `test_approved_argument_repair_requires_replacement_approval`, `test_approved_argument_repair_short_circuit_requires_replacement_approval`, `test_approval_snapshot_distinguishes_exact_values`, `test_approval_rejects_opaque_mutable_validator_output`, `packages/core/tests/test_security.py::TestVariableArgumentPolicy::test_hidden_argument_resolution_does_not_require_reapproval` |
| Consecutive error cap | Error threshold stops repeated failures, submits collected results, and makes only the required final no-tool model call. |`test_function_invocation_config_max_consecutive_errors`, `test_streaming_function_invocation_config_max_consecutive_errors`, `test_approval_resume_error_limit_forces_final_no_tool_response`|
| Stored function call/result | Service-side storage drops server-issued calls but keeps new outputs. |`test_prepare_options_with_conversation_id_strips_server_issued_items`, `test_prepare_messages_for_openai_full_conversation_with_reasoning`|
613
636
| Stateless reasoning replay | Replay reconstructs reasoning, call, and result together; missing required reasoning fails before the request. |`test_tool_loop_store_false_replays_encrypted_reasoning_group`, `test_stateless_request_rejects_non_replayable_reasoning_bound_mcp_output`, `test_prepare_messages_for_openai_full_conversation_with_reasoning`|
637
+
| Remote tool error serialization | Foundry Responses, Responses hosting, and AG-UI preserve channel-visible results without host-internal diagnostics. A2A and MCP hosting omit unsupported intermediate function results entirely, including their diagnostics. |`packages/foundry_hosting/tests/test_responses.py::TestNonStreaming::test_function_result_omits_internal_exception`, `TestStreaming::test_function_result_omits_internal_exception`, `packages/hosting-responses/tests/hosting_responses/test_parsing.py::TestResponsesRunHelpers::test_responses_from_run_omits_internal_function_exception`, `test_responses_from_streaming_run_omits_internal_function_exception`, `packages/ag-ui/tests/ag_ui/test_run_common.py::TestEmitToolResult::test_tool_result_does_not_emit_internal_exception`, `packages/hosting-a2a/tests/hosting_a2a/test_conversion.py::test_a2a_from_run_omits_unsupported_content`, `packages/hosting-mcp/tests/hosting_mcp/test_conversion.py::test_mcp_from_run_omits_content_not_supported_in_tool_results`|
614
638
| Foundry encrypted reasoning opt-in | Foundry clients omit `reasoning.encrypted_content` by default and preserve an explicit caller opt-in. |`packages/foundry/tests/foundry/test_foundry_chat_client.py::test_get_response_does_not_request_encrypted_reasoning_by_default`, `test_get_response_preserves_explicit_encrypted_reasoning_opt_in`, `packages/foundry/tests/foundry/test_foundry_agent.py::test_foundry_agent_basic_call_does_not_request_unsupported_encrypted_reasoning`, `test_foundry_agent_preserves_caller_requested_encrypted_reasoning`, `packages/foundry_hosting/tests/test_responses_int.py::TestReasoningHostedMcpReplay::test_second_turn_replays_mcp_call_with_encrypted_reasoning`|
615
639
| Opaque reasoning signature replay | Provider-specific opaque reasoning metadata is captured and restored on reconstructed calls. |`packages/gemini/tests/test_gemini_client.py::test_function_call_part_captures_thought_signature_as_reasoning_content`, `test_reconstructed_function_call_replays_thought_signature_from_reasoning_content`|
616
640
| Chat Completions approval wrappers | Framework approval wrappers are not sent as chat messages. |`packages/openai/tests/openai/test_openai_chat_completion_client.py` approval serialization tests |
0 commit comments