Skip to content

Commit 80fbe9a

Browse files
authored
Merge branch 'main' into contrib/3686-event-driven-streaming
2 parents 159cd1a + c385c2d commit 80fbe9a

110 files changed

Lines changed: 15819 additions & 1306 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/issue-triage.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,11 +216,15 @@ jobs:
216216
AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
217217
ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
218218
ISSUE_NUMBER: ${{ needs.team_check.outputs.issue_number }}
219+
ISSUE_TYPE: ${{ needs.team_check.outputs.issue_type }}
220+
ISSUE_SNAPSHOT_PATH: ${{ runner.temp }}/issue-triage-snapshot.json
219221
run: |
220222
uv run python scripts/classify_issue_spam.py \
221223
--repo "$ISSUE_REPO" \
222224
--issue-number "$ISSUE_NUMBER" \
225+
--issue-type "$ISSUE_TYPE" \
223226
--repo-path "${TARGET_REPO_PATH}" \
227+
--issue-snapshot-output "$ISSUE_SNAPSHOT_PATH" \
224228
--apply-labels
225229
226230
- name: Stop after spam gate
@@ -244,6 +248,8 @@ jobs:
244248
ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
245249
ISSUE_NUMBER: ${{ needs.team_check.outputs.issue_number }}
246250
ISSUE_TYPE: ${{ needs.team_check.outputs.issue_type }}
251+
ISSUE_SNAPSHOT_PATH: ${{ runner.temp }}/issue-triage-snapshot.json
252+
ISSUE_SNAPSHOT_SHA256: ${{ steps.spam.outputs.issue_snapshot_sha256 }}
247253
# Model-provider settings for generated repro code. Never enter the
248254
# agent prompt; consumed by SDK constructors via os.environ. Azure
249255
# OpenAI and Foundry auth via AAD from the azure/login step above.
@@ -271,4 +277,6 @@ jobs:
271277
--repo "$ISSUE_REPO" \
272278
--issue-number "$ISSUE_NUMBER" \
273279
--issue-type "$ISSUE_TYPE" \
280+
--issue-snapshot "$ISSUE_SNAPSHOT_PATH" \
281+
--issue-snapshot-sha256 "$ISSUE_SNAPSHOT_SHA256" \
274282
--github-username "$GITHUB_ACTOR"

‎docs/decisions/0003-agent-opentelemetry-instrumentation.md‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,21 +124,43 @@ The implementation is validated through:
124124

125125
### Usage Example
126126

127+
The name passed to `TracerProviderBuilder.AddSource` must match the source name the agent emits under, otherwise the
128+
provider silently receives no agent spans. When no source name is supplied to `UseOpenTelemetry`, the agent emits under
129+
`OpenTelemetryAgent.DefaultSourceName`, so that is the value to register. That property is marked
130+
`[Experimental("MAAI001")]`; suppress that diagnostic in your csproj to use it.
131+
127132
```csharp
128133
// Create TracerProvider
129134
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
130-
.AddSource(AgentOpenTelemetryConsts.DefaultSourceName)
135+
.AddSource(OpenTelemetryAgent.DefaultSourceName)
131136
.AddConsoleExporter()
132137
.Build();
133138

134139
// Create and wrap agent with telemetry
135140
var baseAgent = new ChatClientAgent(chatClient, options);
136-
using var telemetryAgent = baseAgent.WithOpenTelemetry();
141+
using var telemetryAgent = baseAgent.AsBuilder()
142+
.UseOpenTelemetry()
143+
.Build();
137144

138145
// Use agent normally - telemetry is captured automatically
139146
var response = await telemetryAgent.RunAsync(messages);
140147
```
141148

149+
To emit under a custom source name, pass the same value to both calls:
150+
151+
```csharp
152+
const string SourceName = "MyCompany.MyAgent";
153+
154+
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
155+
.AddSource(SourceName)
156+
.AddConsoleExporter()
157+
.Build();
158+
159+
using var telemetryAgent = baseAgent.AsBuilder()
160+
.UseOpenTelemetry(sourceName: SourceName)
161+
.Build();
162+
```
163+
142164
### Relationship to Microsoft.Extensions.AI
143165

144166
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.

‎docs/decisions/0008-python-subpackages.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ The goal is to design a subpackage structure for the Python agent framework that
7878
- 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.
7979
- 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.
8080
- 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`.
8282
- 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.
8383

8484
## Decision Outcome

‎docs/decisions/0011-create-get-agent-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ var agent3 = new AssistantClient(...).CreateAIAgent(...); // Creates a remote ag
107107

108108
### Possible Python implementations
109109

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.
111111

112112
Possible options:
113113

‎docs/specs/004-python-function-calling-loop.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,10 @@ that manually replay messages own the equivalent rule: do not resend an approval
369369
already executing in a worker thread cannot be interrupted and may complete its side effects — its result is
370370
discarded either way and never reaches the transcript, the model, or history. Middleware must not catch
371371
`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.
372376
- Parallel calls retain model order in the returned transcript.
373377
- `call_id` remains the provider/service correlation id; a locally actionable `function_call` also carries a stable
374378
Agent Framework occurrence identity in `Content.id`.
@@ -377,6 +381,17 @@ that manually replay messages own the equivalent rule: do not resend an approval
377381
not invent one.
378382
- A completed function call/result pair is inert on later turns.
379383
- 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,
391+
normalized invocation. Built-in security middleware normalizes hidden-value expansions before policy inspection.
392+
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.
380395

381396
### Reasoning-bound calls
382397

@@ -414,6 +429,11 @@ that manually replay messages own the equivalent rule: do not resend an approval
414429
- If policy middleware detects that the exact resolved invocation changed after approval, the old response executes
415430
nothing and yields a caller-visible, session-persisted replacement request for the same occurrence; execution
416431
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.
417437
- If session-bound middleware no longer holds the reviewed authority because it expired or was evicted, the matched
418438
response executes nothing and produces a replacement approval request with the same occurrence identity and a fresh
419439
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
582602
|---|---|---|
583603
| Rejected execution | Rejection is a normal terminal result, not an exception to the caller. | `test_unapproved_tool_execution_raises_exception` |
584604
| 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` |
585606
| 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` |
586609
| Approved success | Successful approved execution returns one result. | `test_approved_function_call_successful_execution` |
587610
| 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` |
588611
| Unknown call handling | Configured false returns an error result; configured true raises. | `test_function_invocation_config_terminate_on_unknown_calls_false`, `test_function_invocation_config_terminate_on_unknown_calls_true`, streaming equivalents |
@@ -611,6 +634,7 @@ that manually replay messages own the equivalent rule: do not resend an approval
611634
| OpenAI end-to-end hosted approval | Hosted request parses, response sends, and continuation completes. | `test_end_to_end_mcp_approval_flow` |
612635
| 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` |
613636
| 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` |
614638
| 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` |
615639
| 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` |
616640
| 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

Comments
 (0)