docs(ai-foundry): document vectorizer requirement for AzureAISearchTool#46384
docs(ai-foundry): document vectorizer requirement for AzureAISearchTool#46384VenkataAnilKumar wants to merge 7 commits intoAzure:mainfrom
Conversation
|
Thank you for your contribution @VenkataAnilKumar! We will review the pull request and get back to you soon. |
|
@VenkataAnilKumar please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
1 similar comment
|
@VenkataAnilKumar please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
There was a problem hiding this comment.
Pull request overview
Adds documentation clarifications across Azure AI Projects and Azure AI Agents samples/docs to call out that vector-based Azure AI Search query types require an index configured with a vectorizer.
Changes:
- Added a prerequisite note to the Azure AI Projects AI Search tool sample for vector query types.
- Extended
AISearchIndexResource.query_typedocumentation inazure-ai-projectsmodels to mention the vectorizer requirement. - Added the same prerequisite note to
azure-ai-agentssamples and README.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/ai/azure-ai-projects/samples/agents/tools/sample_agent_ai_search.py | Adds a sample-level prerequisite note about vectorizer requirements for vector query types. |
| sdk/ai/azure-ai-projects/azure/ai/projects/models/_models.py | Adds a vectorizer requirement note to the AISearchIndexResource.query_type docs. |
| sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_azure_ai_search.py | Adds a prerequisite note about vectorizer requirements for vector query types. |
| sdk/ai/azure-ai-agents/samples/agents_async/sample_agents_azure_ai_search_async.py | Adds the same prerequisite note for the async sample. |
| sdk/ai/azure-ai-agents/README.md | Adds a README note calling out vectorizer requirements for vector query types. |
| """Type of query in an AIIndexResource attached to this agent. Known values are: \"simple\", | ||
| \"semantic\", \"vector\", \"vector_simple_hybrid\", and \"vector_semantic_hybrid\".""" | ||
| \"semantic\", \"vector\", \"vector_simple_hybrid\", and \"vector_semantic_hybrid\". | ||
| For vector query types, ensure the target Azure AI Search index is configured with a vectorizer.""" |
There was a problem hiding this comment.
The query_type attribute docstring adds the vectorizer note, but the wording/terminology is now inconsistent with the surrounding docs/samples (some say “vectorizer configuration”, others “configured with a vectorizer”). It would be clearer to standardize the phrasing across this model doc and the public-facing README/samples. Also, the same AISearchIndexResource.query_type exists in azure-ai-agents models and currently has no corresponding note; consider adding the same clarification there to keep the two packages’ API docs aligned.
* Move load to it's own file * moving helper methods to utils * reorginizing tests * readding after merge * copilot review comments
…d out source from main, AND we're not padding the python executable so it's not installing to the proper venv. (Azure#46382)
…h with AAD credentials (Azure#46243)
…on, diagnostic logging, startup config logging, Foundry User-Agent (Azure#46364) * Spec compliance: error shapes, post-delete 404, storage logging Align error payloads with the container-spec behaviour contract: Error code compliance: - error.code uses 'invalid_request_error' for 400/404 (was 'invalid_request', 'not_found', 'invalid_mode') - error.code uses 'server_error' for 500 (was 'internal_error') - RequestValidationError default code updated to 'invalid_request_error' Post-delete behaviour (spec alignment with .NET PR #58252): - GET, input_items, and second DELETE on deleted responses now return 404 (was 400) - deleted_response() factory now delegates to not_found_response() Cancel/SSE message alignment: - Cancel incomplete: 'Cannot cancel a response in terminal state.' (was 'Cannot cancel an incomplete response.') - SSE replay non-bg: 'This response cannot be streamed because it was not created with background=true.' - SSE replay non-stream: '...stream=true.' Storage error propagation: - FoundryStorageError subclasses now explicitly caught in GET, cancel, and input_items handlers instead of being swallowed by broad except clauses - FoundryResourceNotFoundError -> 404, FoundryBadRequestError -> 400, FoundryApiError -> error_response (500) Storage call logging: - FoundryStorageLoggingPolicy: per-retry pipeline policy logging method, URI, status code, duration (ms), and correlation headers at the azure.ai.agentserver logger - Replaces built-in HttpLoggingPolicy to avoid double-logging Tests: - Added error.code assertions to all existing error tests across cancel, delete, get, create, and input_items endpoint tests - Updated post-delete tests from expecting 400 to 404 - Added new tests: SSE replay unknown ID, 404 message contains ID, 500 error body shape, SSE replay message variants - Added FoundryStorageLoggingPolicy unit tests (4 tests) - 791 tests passing Version bumped to 1.0.0b2. * Address PR review: add FoundryBadRequestError handlers, clean up imports, fix pyright/pylint, reclassify changelog * Set 1.0.0b2 release date to 2026-04-17 * feat: chat isolation enforcement & malformed ID validation Chat isolation key enforcement: - Store chat_isolation_key on ResponseExecution and _RuntimeState - Enforce key matching on GET, DELETE, Cancel, and InputItems endpoints - Mismatched/missing keys return indistinguishable 404 - Backward-compatible: no enforcement when created without a key Malformed ID validation: - All endpoints reject malformed response_id path params (wrong prefix, too short) with 400 before touching storage - previous_response_id in POST body also validated - Update existing tests using fake IDs to use well-formed IdGenerator IDs 14 chat isolation tests + 19 malformed ID tests (33 new, 824 total) * feat(agentserver-responses): eager eviction of terminal response records Port eager eviction from .NET PR #58252. After a response reaches a terminal state (completed, failed, cancelled, incomplete), the in-memory record is removed from RuntimeState so that subsequent GET, DELETE, Cancel, and SSE replay requests fall through to the durable storage provider. Key changes: - RuntimeState.try_evict(): removes terminal records while preserving chat isolation keys for provider-fallback enforcement - RuntimeState.mark_deleted(): supports DELETE provider fallback - Eviction wired into all 5 orchestrator terminal paths (bg non-stream, sync, bg+stream Path A, non-bg stream Path B, cancel) - Provider fallback paths added to handle_get, handle_delete, handle_cancel for evicted responses - B1 background check in cancel provider fallback (matches .NET) - Cancel idempotency: cancelled responses return 200 via provider - B2 stream/background checks in SSE replay provider fallback - background + stream mode flags stamped on all persisted responses - SSE events saved for replay after eviction (including fallback events) - store=false cancel returns 404 (matching .NET) - SSE datetime serialization fix in _build_sse_frame - 9 new eager eviction unit tests * fix(agentserver-responses): remove stream mode flag stamping on persisted responses The stream flag is not part of the ResponseObject contract and should not be persisted. After eager eviction, the server cannot distinguish bg+non-stream from bg+stream-with-expired-TTL, so the SSE replay fallback now uses a combined error message matching .NET's SseReplayResult: 'This response cannot be streamed because it was not created with stream=true or the stream TTL has expired.' Added TODO documenting the deliberate spec violation — the container spec prescribes distinct error messages but the provider doesn't carry enough context to distinguish the two cases. * feat(agentserver-responses): inbound request logging middleware and handler diagnostic logging - Add InboundRequestLoggingMiddleware (pure ASGI): logs method, path, status, duration, correlation headers (x-request-id, x-ms-client-request-id), and OTel trace ID. Status >= 400 → WARNING; exceptions → forced 500 WARNING. Query strings are excluded from logs. - Add INFO-level handler diagnostic logs to all 5 endpoints: create (params), get (entry + retrieval), delete (entry + success), cancel (entry + success), input_items (entry). - Add orchestrator handler invocation log with handler function name. - Wire middleware in ResponsesAgentServerHost via add_middleware(). - 13 new contract tests for middleware and handler logging. - Update CHANGELOG.md with logging features. Matches .NET PR #58274 (InboundRequestLoggingMiddleware + handler logging). * chore: remove .NET references from code comments and docstrings * fix: add type ignore for Starlette add_middleware typing * fix: update githubcopilot core dependency to >=2.0.0b1 The azure-ai-agentserver-core package was bumped to 2.0.0b1 but the githubcopilot package still had the old <1.0.0b18 upper bound, causing the Analyze dependencies CI gate to fail. * Revert "fix: update githubcopilot core dependency to >=2.0.0b1" This reverts commit 903e498. * Move InboundRequestLoggingMiddleware to core Moves the middleware from azure-ai-agentserver-responses to azure-ai-agentserver-core so all protocol hosts get consistent inbound request logging automatically. - Created _middleware.py in core with the middleware class - Wired into AgentServerHost.__init__ middleware list - Exported from core __init__.py - Removed explicit add_middleware() call from ResponsesAgentServerHost - Updated CHANGELOG to reflect the move Addresses review feedback from @ankitbko. * Bump core to 2.0.0b2, invocations to 1.0.0b2 for middleware move - core 2.0.0b2: Added InboundRequestLoggingMiddleware, CHANGELOG updated - invocations 1.0.0b2: Core dep bumped to >=2.0.0b2, CHANGELOG updated - responses: Core dep bumped to >=2.0.0b2 * feat(responses): add x-agent-session-id header + B40 error shape (§8, B40) - Add x-agent-session-id response header on all protocol endpoints per container spec §8. POST /responses uses the per-request resolved session ID; GET/DELETE/CANCEL/INPUT_ITEMS use the env var. - Update B40 malformed ID error shape: code 'invalid_parameters', param 'responseId{<value>}' matching spec contract. - Add _session_headers() helper for consistent header propagation across all handler code paths including error responses. - Add invalid_parameters_response() validation helper for B40. - Update previous_response_id validation to use 'invalid_parameters'. - Fix header inconsistency: all JSONResponse calls now include headers. - TDD: tests written first, verified red, then implementation, green. Tests: 851 responses + 76 core + 105 invocations passing. * Address PR review: fix CHANGELOG B40 wire shape, use public API in test * Log isolation key presence (not values) in endpoint handler diagnostics * Log isolation header presence in Foundry storage logging policy Add has_user_isolation_key/has_chat_isolation_key booleans to both success and failure log lines. Values are never logged. Includes 3 new unit tests covering presence, absence, and failure paths. * Fix pyright errors in agentserver source code - _tracing.py: Suppress OTel type stub gaps (start_as_current_span context manager, LoggerProvider API vs SDK mismatch, duck-typed BaggageLogRecordProcessor) with targeted type: ignore comments. - _base.py: Suppress Starlette Middleware factory protocol mismatch for pure-ASGI middleware classes (arg-type). All 13 production-source pyright errors resolved (0 remaining). Test-only errors from generated model unions are pre-existing. * Add startup configuration logging across all agentserver packages - Core: AgentServerHost lifespan emits 3 INFO log lines at startup: 1. Platform environment (is_hosted, agent_name, agent_version, port, session_id, sse_keepalive_interval) 2. Connectivity (project_endpoint masked, otlp_endpoint masked, appinsights_configured boolean — connection string never logged) 3. Host options (shutdown_timeout, registered protocols) - Core: _mask_uri() helper strips URI to scheme://host, returns '(not set)' for empty values, '(redacted)' for unparseable input - Responses: Logs storage_provider type, default_model, default_fetch_history_count, shutdown_grace_period at construction - Invocations: Logs openapi_spec_configured at construction - 13 new unit tests (8 for _mask_uri, 5 for startup log assertions) - Updated all 3 CHANGELOGs * Fix ruff lint issues across agentserver packages - Fix I001 import sorting in _base.py, _config.py, _tracing.py, _endpoint_handler.py, _sse.py (auto-fixed via ruff --fix) - Fix E501 line-too-long in _orchestrator.py (2 occurrences, wrapped long getattr expressions) * Address PR review comments: URL masking, SSE session headers, test hardening - _mask_uri docstring: Include '(redacted)' return case in :return: docs - FoundryStorageLoggingPolicy: Mask everything before /storage in URLs (host, scheme, /api/projects/{name} prefix all redacted); query params stripped. Only /storage/... resource path is logged for debugging. - SSE session headers: _parse_starting_after now accepts headers param; _build_live_stream_response and _try_replay_persisted_stream merge session headers into SSE headers so x-agent-session-id is present on all streaming responses and cursor-parse error responses. - test_valid_format_nonexistent_previous_response_id: Strengthened to explicitly assert code != 'invalid_parameters' and 'Malformed' not in message when status is 400, instead of weak OR-based assertion. - 6 new _mask_storage_url unit tests covering project path redaction, query stripping, /storage path preservation, edge cases. * Preserve api-version query param in Foundry storage URL masking _mask_storage_url now keeps the api-version query parameter in the masked output for debugging while still stripping all other params. Updated docstring example and tests accordingly. * Foundry storage User-Agent matches x-platform-server via lazy callback; cspell fixes * Fix post-eviction chat isolation: let Foundry storage enforce instead of local 404 * Remove redundant _chat_isolation_keys dict — use record directly The _chat_isolation_keys dict duplicated what ResponseExecution.chat_isolation_key already carries. For in-flight responses the record is available; for post-eviction responses Foundry storage enforces isolation server-side. - Remove _chat_isolation_keys dict and all add/delete/evict bookkeeping - Make check_chat_isolation a @staticmethod(stored_key, request_key) - Endpoint callers pass record.chat_isolation_key directly - Remove redundant INPUT_ITEMS KeyError fallback check (already checked above) - Update eviction test to verify static helper + record lifecycle * Address PR review: fix docstring and logging policy generics - FoundryStorageProvider: update get_server_version=None docstring to say 'uses Azure Core default User-Agent policy' (matches actual behavior) - FoundryStorageLoggingPolicy: remove misleading AsyncHTTPPolicy generic type args; use bare AsyncHTTPPolicy with type: ignore[type-arg] * Address PR review round 4: sdk_moniker, exc_info, test name - Restore sdk_moniker='ai-agentserver-responses/{VERSION}' in default UserAgentPolicy path (was dropped when adding _ServerVersionUserAgentPolicy) - Add exc_info=True to logging policy transport-failure warning - Rename test_malformed_previous_response_id_returns_400_with_details to _returns_400; assert error.type/code/param (no details array in wire shape) - Update module docstring to match actual contract * Fix pylint: extract helpers to reduce statement/branch counts Core: - _base.py: break long Middleware() line (127 > 120 chars) Responses (_endpoint_handler.py): - Extract _handle_get_fallback(): provider fallback for evicted/missing records - Extract _handle_get_stream(): stream=true path for in-flight records - Extract _handle_cancel_fallback(): provider fallback for cancel - Extract _check_cancel_terminal_status(): shared terminal-status logic used by both in-flight and provider-fallback cancel paths - handle_get: 61 -> ~30 statements - handle_cancel: 55 statements / 22 branches -> ~30 / ~12 * Suppress remaining pylint warnings in agentserver-responses - Add pylint disable for too-many-positional-arguments on constructors and get_input_items protocol methods (6 sites) - Add pylint disable for import-error/no-name-in-module on cross-package azure.ai.agentserver.core imports (4 sites) * fix: remove too-many-positional-arguments disable comments unsupported by pylint 3.2.7 CI uses pylint==3.2.7 which does not have the too-many-positional-arguments check (added in 3.3+). The inline pylint disable comments were triggering unknown-option-value warnings (W0012), causing exit code 4.
6f57893 to
15cf271
Compare
Fixes #45584
Adds documentation notes in Azure AI Search tool docs/samples clarifying that vector query types (vector, vector_simple_hybrid, vector_semantic_hybrid) require the target Azure AI Search index to be configured with a vectorizer.