Implement artifact streaming with append and sealing semantics

[darrelmiller]

Introduce artifact streaming capabilities, allowing for updates with append and sealing semantics. Enhance interfaces and implement necessary methods for managing streaming updates. Add CORS configuration to allow calling from localhost and a new StreamingArtifactAgent to test the streaming artifact capability. Include unit tests to validate the new functionality.

[gemini-code-assist]

Summary of Changes

Hello @darrelmiller, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the platform's artifact handling by introducing a robust streaming mechanism. Agents can now progressively build and update artifacts in chunks, with the ability to 'seal' them once complete, preventing any further changes. This feature improves the flexibility and responsiveness of artifact generation, supported by new API methods, updated storage logic, and a practical demonstration agent.

Highlights

• Artifact Streaming Implementation: Introduced new capabilities for streaming artifacts, allowing them to be updated incrementally with append semantics and then 'sealed' to prevent further modifications. This enables more dynamic and efficient artifact generation by agents.
• New Interfaces and Methods: Added ReturnArtifactStreamAsync to ITaskManager and TaskManager, and UpdateArtifactAsync to ITaskStore and its implementations (InMemoryTaskStore, DistributedCacheTaskStore) to support the new streaming and sealing logic.
• Sample Streaming Agent: Included a new StreamingArtifactAgent in the AgentServer sample application to demonstrate how to use the new artifact streaming functionality by generating a story in chunks.
• CORS Configuration: Configured Cross-Origin Resource Sharing (CORS) in the AgentServer sample to allow requests from any origin, facilitating local development and testing of the new streaming features.
• Comprehensive Unit Testing: Added extensive unit tests across InMemoryTaskStoreTests.cs and TaskManagerTests.cs to validate the behavior of artifact streaming, appending, replacing, merging metadata/extensions, and enforcing the sealing mechanism.

Changelog

• samples/AgentServer/Program.cs
  • Configured CORS to allow all origins, methods, and headers for development convenience.
  • Enabled CORS middleware in the application pipeline.
  • Registered a new StreamingArtifactAgent for demonstration purposes.
  • Updated the console output to include 'streaming' as a valid agent type option.
• samples/AgentServer/ResearcherAgent.cs
  • Modified the logic for extracting the last user message from task history.
  • Removed a redundant InputRequired status update after planning.
• samples/AgentServer/StreamingArtifactAgent.cs
  • Added a new agent that demonstrates artifact streaming by generating a story in multiple chunks.
  • Implemented the use of ReturnArtifactStreamAsync with Append and LastChunk flags.
• src/A2A.AspNetCore/Caching/DistributedCacheTaskStore.cs
  • Implemented the UpdateArtifactAsync method to support artifact streaming with append and sealing semantics.
  • Added logic to merge artifact parts, metadata, and extensions during append operations.
  • Introduced a mechanism to track and prevent updates to sealed artifacts in the distributed cache.
• src/A2A/A2AJsonUtilities.cs
  • Added HashSet<string> to the JSON serialization context to support caching of sealed artifact IDs.
• src/A2A/Server/ITaskManager.cs
  • Introduced the ReturnArtifactStreamAsync method to the interface for handling streamed artifact updates.
• src/A2A/Server/ITaskStore.cs
  • Introduced the UpdateArtifactAsync method to the interface for managing artifact updates with append and sealing logic.
• src/A2A/Server/InMemoryTaskStore.cs
  • Implemented the UpdateArtifactAsync method for in-memory storage, supporting artifact appending, replacement, and sealing.
  • Added internal data structures (_sealedArtifacts, _taskArtifactLocks) to manage sealed artifacts and ensure atomic updates.
• src/A2A/Server/TaskManager.cs
  • Implemented the ReturnArtifactStreamAsync method, which validates input and delegates artifact updates to the underlying ITaskStore.
  • Added OpenTelemetry activity tracing for artifact streaming operations.
• tests/A2A.UnitTests/Server/InMemoryTaskStoreTests.cs
  • Added unit tests for UpdateArtifactAsync covering scenarios like adding new artifacts, appending to existing ones, creating new artifacts on append, replacing existing artifacts, and merging metadata/extensions.
  • Included tests for error handling when a task is not found or an artifact ID is empty.
  • Added tests to verify correct cancellation behavior.
  • Implemented tests to ensure that sealed artifacts cannot be updated.
• tests/A2A.UnitTests/Server/TaskManagerTests.cs
  • Added unit tests for ReturnArtifactStreamAsync to verify artifact streaming with append and lastChunk flags.
  • Included tests for error handling when artifact ID is missing or task is not found.
  • Added tests to confirm that streaming generates correct events.
  • Implemented tests for replacing existing artifacts and supporting multiple simultaneous artifacts.
  • Added tests for cancellation behavior and proper merging of metadata and extensions.
  • Included tests to ensure that sealed artifacts cannot be updated via streaming.

Activity

• No specific human activity (comments, reviews) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces artifact streaming with append and sealing semantics, which is a significant new feature. The changes are well-structured, including new interfaces, implementations for both in-memory and distributed cache stores, a sample agent, and comprehensive unit tests. My review focuses on potential issues related to security, concurrency, and API design to ensure the new functionality is robust and safe to use. I've identified a critical race condition in the distributed cache implementation and a few other high-severity issues that should be addressed before merging.