1 Commits

• .NET: Hosted-Files sample + AgentSessionFiles SDK companion + integration test (#5698)

  * .NET: Add Hosted-Files sample + alpha AgentSessionFiles SDK companion + integration test
  
  Closes #5691
  
  - Hosted-Files server sample (mirrors python 06_files): 3 local tools reading
    the per-session \C:\Users\rbarreto sandbox volume.
  - SessionFilesClient REPL companion: code-first equivalent of
    zd ai agent files upload using the alpha
    Azure.AI.Projects.AgentSessionFiles SDK (upload/ls/download/rm + session
    lifecycle with isolation key).
  - session-files scenario added to the Foundry.Hosting.IntegrationTests
    multi-scenario harness (PR #5598): SessionFilesHostedAgentFixture +
    SessionFilesHostedAgentTests.UploadAndAgentReadsFileAsync, end-to-end
    validating upload then agent-reads-file (agent_session_id pinned via
    CreateResponseOptions.Patch). Bundled testdata is linked from the sample
    so there is a single source of truth.
  
  * .NET: Hosted-Files: REPL companion now demonstrates file-as-knowledge end-to-end
  
  Adds an 'ask <prompt>' command to SessionFilesClient that pins
  agent_session_id (via CreateResponseOptions.Patch) so the agent invoked from
  the REPL reads files this REPL just uploaded. Surfaces the file content as
  agent knowledge in the same in-process loop instead of telling the user to
  shell out to azd ai agent invoke.
  
  * .NET: Reshape Hosted-Files sample - bake files into image, SessionFilesClient becomes thin chat REPL
  
  The previous SessionFilesClient leaned on the alpha AgentSessionFiles SDK
  to upload files at runtime, which made it diverge from the canonical
  Using-Samples shape (SimpleAgent / SimpleInvocationsAgent: tiny chat REPLs).
  
  This change:
  
  - Bakes the sample resources/ directory into the published output via a
    Content Include in HostedFiles.csproj. Inside the container the files live
    at /app/resources/. Two local function tools (ListFiles, ReadFile) surface
    them to the model.
  - Reshapes SessionFilesClient as a thin FoundryAgent chat REPL, identical
    shape to SimpleAgent. AGENT_ENDPOINT + AGENT_NAME, that is it.
  - Demo flow: user asks 'Give me the total revenue in the contoso file' and
    the agent answers with the figure read from its bundled file. Validated
    end-to-end locally against Hosted-Files on http://localhost:60419.
  - Bypasses SampleEnvironment alias on optional env vars to avoid stdin
    prompts when running unattended.
  
  The Foundry.Hosting.IntegrationTests session-files scenario continues to
  validate the alpha AgentSessionFiles SDK end-to-end (upload + agent reads
  from session HOME) and is unchanged.
  
  * .NET: Foundry.Hosting.IntegrationTests TestContainer - constrain session-files tools to $HOME
  
  Addresses the path-traversal review comment on the session-files scenario:
  ResolveSessionPath in TestContainer used to allow absolute paths and ..
  traversals, which (when chained with indirect prompt injection in an
  uploaded file) would let the model read or list arbitrary container files
  via the ReadFile / ListFiles tools.
  
  Mirrors the canonicalize + StartsWith(home) pattern from the framework's
  own FileSystemAgentFileStore.ResolveSafePath: rejects rooted paths, calls
  Path.GetFullPath, and verifies the result stays under $HOME, throwing
  ArgumentException otherwise.
  
  The Hosted-Files sample is already safe (uses Path.GetFileName which strips
  any directory component) so no change there. The integration test continues
  to upload and read 'contoso_q1_2026_report.txt', a single relative filename
  which passes the new validation unchanged.
  
  * .NET: SessionFilesHostedAgentTests - shrink to alpha SDK round-trip
  
  The previous test attempted to pin agent_session_id into the /responses
  payload via JsonPatch so the agent would read the file uploaded through
  AgentSessionFiles. The Foundry alpha service now consistently rejects the
  explicit-session-id pin with HTTP 400 conflict on /responses, regardless
  of whether the session was pre-created via AgentAdministrationClient or
  left to be auto-provisioned, so the agent leg of the test is no longer
  reachable from the SDK surface.
  
  Reshape the test to exercise what the alpha SDK actually guarantees:
  create session, upload, list (assert presence + size), download (assert
  deterministic token), delete (assert removed), cleanup. Everything stays
  inside Azure.AI.Projects.Agents.AgentSessionFiles.
  
  Verified live against tao-foundry-prj:
    UploadListDownloadAndDeleteAsync passed in 30s.
    Full Foundry.Hosting.IntegrationTests run: 25 total, 6 passed, 19
    skipped (existing placeholders), 0 failed.
  
  * .NET: SessionFilesHostedAgentTests - rewrite as upload-then-FoundryAgent.RunAsync e2e
  
  Per review feedback the integration test must validate the hosted agent
  itself: client uploads a file via the alpha AgentSessionFiles SDK, then
  FoundryAgent.RunAsync invokes the deployed agent and the agent's
  container-side ReadFile tool surfaces the uploaded file content into the
  response.
  
  Test flow:
    1. agent.RunAsync(warmup) - platform provisions a per-session container.
    2. AgentAdministrationClient.GetSessionsAsync(latest) - resolve the
       just-provisioned agent_session_id.
    3. AgentSessionFiles.UploadSessionFileAsync - upload contoso file to
       that session, asserts BytesWritten + GetSessionFiles listing.
    4. agent.RunAsync(real prompt, options=PreviousResponseId chain) -
       chained to warmup so the platform routes back to the same container.
    5. Assert response contains '1,482.6' (deterministic token from file).
    6. Best-effort cleanup.
  
  The test is annotated with [Fact(Skip=...)] right now: the Foundry alpha
  service consistently returns HTTP 400 conflict on /responses requests
  that link to a prior session via previous_response_id, conversation_id,
  or agent_session_id pinning - verified across multiple retries with
  multiple chaining strategies. Without that link we cannot route the
  second invocation to the same container the file was uploaded to. When
  the platform regression is resolved, removing the Skip will exercise
  the full flow.
  
  Full Foundry.Hosting.IntegrationTests run with this change: 25 total,
  5 passed, 20 skipped (existing placeholders + this one), 0 failed.
  
  * .NET: SessionFilesHostedAgentTests - end-to-end upload-then-FoundryAgent.RunAsync now passes
  
  The blocker was a routing problem combined with a platform race:
  
  1. Routing two /responses calls to the same per-session container.
     - agent_session_id pin in body -> 400 (platform treats it as create)
     - conversation_id created at project root -> 404 at agent endpoint
     - previous_response_id chain -> different session
     The working answer is to create the conversation on a per-agent
     ProjectOpenAIClient (AgentName option, URL becomes
     /agents/{name}/endpoint/protocols/openai/conversations) and pass that
     conversation_id on both calls. Both then resolve to the SAME
     x-agent-session-id (verified by capturing the response header).
  
  2. Race after AgentSessionFiles upload. The upload mutates session/
     conversation revision; a /responses call issued immediately after
     400-conflicts with 'modified concurrently. Please retry.' Bounded
     exponential retry handles it (5 attempts, 2*attempt seconds).
  
  Test flow:
    1. Create per-agent OpenAI client + ProjectConversationsClient + ProjectResponsesClient.
    2. CreateProjectConversationAsync on the per-agent client.
    3. Warm-up agent.RunAsync(prompt, ChatOptions { ConversationId = ... })
       - captures x-agent-session-id from the response header via a custom pipeline policy.
    4. AgentSessionFiles.UploadSessionFileAsync to that session id.
    5. ProjectResponsesClient.CreateResponseAsync (raw, retry-on-conflict)
       with the same conversation_id -> routes back to the same container.
    6. Assert response contains '1,482.6' (deterministic token from file).
    7. Cleanup: delete file, leave session for TTL.
  
  Verified live against tao-foundry-prj:
    UploadedFile_IsReadByHostedAgentAsync passed in 24.9s.
    Full Foundry.Hosting.IntegrationTests run: 25 total, 6 passed, 19
    skipped (existing placeholders), 0 failed.
  
  * .NET: address Copilot PR review findings
  
  - agent.manifest.yaml: description + tags now reflect bundled-files agent (image-baked /app/resources), not the obsolete session-sandbox tools the prior shape claimed.
  - SessionFilesHostedAgentTests: wrap test body in try/finally to call DeleteConversationAsync on the conversation we created (matches HappyPathHostedAgentTests pattern; prevents conversation leakage across runs).
  - ResponseHeaderCapturePolicy: drop unused LastRequestBody capture left over from diagnosis.
  
  Test still passes live (40s).
  
  * .NET: Hosted-Files: split into bundled vs session-file tool pairs
  
  The previous Hosted-Files agent only exposed bundled (image-baked) file
  knowledge. The platform also surfaces session-uploaded files at \C:\Users\rbarreto
  inside the per-session container per container-image-spec.md line 172
  (verified live by SessionFilesHostedAgentTests). The sample now teaches
  both patterns.
  
  Two distinct tool pairs, each scoped to its own root:
  
    Bundled (image-baked):    ListBundledFiles, ReadBundledFile
                              -> /app/resources/ (BUNDLED_FILES_DIR override)
  
    Session-uploaded (\C:\Users\rbarreto): ListSessionFiles, ReadSessionFile
                              -> \C:\Users\rbarreto (default /home/session per container spec)
  
  Security model -- distinct tools, distinct sandboxes:
    - Tool input is a fileName, not a path. Schema-level: model cannot
      request directories or traversals.
    - Path.GetFileName(input) strips any directory components.
    - Path.GetFullPath + StartsWith(root) check rejects anything outside
      the tool's root, mirroring FileSystemAgentFileStore.ResolveSafePath.
    - Read-only, non-recursive listing. No glob, no '..'.
    - Failures non-revealing: 'File <name> not found in <scope>.'
  
  The two roots are physically isolated (image-baked vs platform-mounted
  per-session volume). A bundled-root tool can never reach a session file
  and vice-versa, even if the implementation has a bug.
  
  README updated to document both flows, the security pattern, and cite
  the container-image-spec.md line 172 contract for \C:\Users\rbarreto. Live IT
  SessionFilesHostedAgentTests.UploadedFile_IsReadByHostedAgentAsync
  re-passed in 42s after the change (TestContainer is unchanged; the
  sample-agent split does not affect the IT).
  
  * .NET: Hosted-Files README - fix broken relative link to IT (4..5 dots)

  Roger Barreto · 2026-05-11 11:56:58 +00:00
  9faf52de4f