|
| 1 | +# A2A .NET SDK Copilot Instructions |
| 2 | + |
| 3 | +This file contains coding guidelines and requirements for maintaining the A2A .NET SDK. These instructions help ensure consistency and correctness when implementing features, especially discriminator-based serialization. |
| 4 | + |
| 5 | +## Discriminator Converter Implementation Requirements |
| 6 | + |
| 7 | +### Overview |
| 8 | +The A2A SDK uses a custom JSON discriminator pattern for polymorphic serialization of types like `A2AEvent`, `Part`, and `FileContent`. This approach allows for specific error handling with `A2AException` and error codes instead of the default `NotSupportedException` from System.Text.Json. |
| 9 | + |
| 10 | +### String Constant Patterns |
| 11 | + |
| 12 | +When implementing discriminator-based serialization: |
| 13 | + |
| 14 | +1. **Use internal static classes for kind constants** instead of enums |
| 15 | + - Create static classes like `A2AEventKind`, `PartKind`, `FileContentKind` |
| 16 | + - Use `const string` fields with lowercase kebab-case values |
| 17 | + - Include XML documentation linking to related types |
| 18 | + |
| 19 | + ```csharp |
| 20 | + public static class PartKind |
| 21 | + { |
| 22 | + /// <summary> |
| 23 | + /// A text part containing plain textual content. |
| 24 | + /// </summary> |
| 25 | + /// <seealso cref="TextPart"/> |
| 26 | + public const string Text = "text"; |
| 27 | + } |
| 28 | + ``` |
| 29 | + |
| 30 | +2. **Use BaseKindDiscriminatorConverter** |
| 31 | + - Inherit from `BaseKindDiscriminatorConverter<TBase>` |
| 32 | + - Implement `KindToTypeMapping` as `IReadOnlyDictionary<string, Type>` |
| 33 | + - Implement `DisplayName` property for error messages |
| 34 | + |
| 35 | + ```csharp |
| 36 | + internal class PartConverterViaKindDiscriminator<T> : BaseKindDiscriminatorConverter<T> where T : Part |
| 37 | + { |
| 38 | + protected override IReadOnlyDictionary<string, Type> KindToTypeMapping { get; } = new Dictionary<string, Type> |
| 39 | + { |
| 40 | + [PartKind.Text] = typeof(TextPart), |
| 41 | + [PartKind.File] = typeof(FilePart), |
| 42 | + [PartKind.Data] = typeof(DataPart) |
| 43 | + }; |
| 44 | + |
| 45 | + protected override string DisplayName { get; } = "part"; |
| 46 | + } |
| 47 | + ``` |
| 48 | + |
| 49 | +3. **Primary constructor usage for derived types** |
| 50 | + - Use primary constructors in derived classes |
| 51 | + - Pass the appropriate string constant to the base constructor |
| 52 | + |
| 53 | + ```csharp |
| 54 | + public sealed class TextPart() : Part(PartKind.Text) |
| 55 | + { |
| 56 | + // Implementation |
| 57 | + } |
| 58 | + ``` |
| 59 | + |
| 60 | +### Error Handling Requirements |
| 61 | + |
| 62 | +1. **Use specific error messages** |
| 63 | + - Missing discriminator: "Missing required 'kind' discriminator for {TypeName}" |
| 64 | + - Invalid discriminator type: "Invalid 'kind' discriminator for {TypeName}: '{value}'" |
| 65 | + - Unknown kind value: "Unknown {displayName} kind: '{kindValue}'" |
| 66 | + - Deserialization failure: "Failed to deserialize '{kindValue}' {displayName}" |
| 67 | + |
| 68 | +2. **Use appropriate A2AErrorCode** |
| 69 | + - All discriminator-related errors should use `A2AErrorCode.InvalidRequest` |
| 70 | + |
| 71 | +### Maintenance Guidelines |
| 72 | + |
| 73 | +#### When Adding New Discriminated Types |
| 74 | + |
| 75 | +1. **Create the kind constants class** |
| 76 | + - Use static class with const string fields |
| 77 | + - Follow kebab-case naming convention |
| 78 | + - Add comprehensive XML documentation |
| 79 | + |
| 80 | +2. **Create the base class** |
| 81 | + - Use primary constructor accepting string kind parameter |
| 82 | + - Add JsonConverter attribute pointing to your converter |
| 83 | + - Include JsonDerivedType attributes for all derived types |
| 84 | + - Add discriminator property with proper JsonPropertyName and JsonPropertyOrder |
| 85 | + |
| 86 | +3. **Create the converter** |
| 87 | + - Inherit from `BaseKindDiscriminatorConverter<TBase>` |
| 88 | + - Implement required abstract members |
| 89 | + - Use dictionary mapping for kind-to-type relationships |
| 90 | + |
| 91 | +4. **Create derived classes** |
| 92 | + - Use primary constructors |
| 93 | + - Pass appropriate kind constant to base constructor |
| 94 | + |
| 95 | +#### When Adding New Derived Types |
| 96 | + |
| 97 | +1. **Add new kind constant** to the appropriate kind constants class |
| 98 | +2. **Add mapping entry** in the converter's KindToTypeMapping |
| 99 | +3. **Add JsonDerivedType attribute** to the base class |
| 100 | +4. **Implement the derived class** with primary constructor |
| 101 | +5. **Add comprehensive tests** for serialization/deserialization |
| 102 | + |
| 103 | +### JSON Serialization Guidelines |
| 104 | + |
| 105 | +1. **Property naming**: Use camelCase for JSON property names |
| 106 | +2. **Property ordering**: Discriminator property should have `JsonPropertyOrder(int.MinValue)` |
| 107 | +3. **Required properties**: Mark discriminators with `JsonRequired` |
| 108 | +4. **Converter placement**: Use `JsonConverter` attribute on base classes, not derived classes |
| 109 | + |
| 110 | +### Testing Requirements |
| 111 | + |
| 112 | +When implementing discriminator converters, ensure: |
| 113 | + |
| 114 | +1. **Successful serialization** of all derived types |
| 115 | +2. **Successful deserialization** with valid kind values |
| 116 | +3. **Proper error handling** for missing/invalid/unknown kind values |
| 117 | +4. **Round-trip compatibility** (serialize then deserialize equals original) |
| 118 | +5. **Backward compatibility** with existing JSON payloads |
| 119 | + |
| 120 | +## Performance Considerations |
| 121 | + |
| 122 | +1. **Use readonly dictionaries** for kind-to-type mappings |
| 123 | +2. **Avoid repeated allocations** in converter hot paths |
| 124 | +3. **Cache type info** when possible |
| 125 | +4. **Use culture-invariant operations** for string handling |
| 126 | + |
| 127 | +## Implemention guidelines |
| 128 | + |
| 129 | +1. Follow **principle of least privilege/visibility** for new types |
| 130 | + |
| 131 | +## Example Implementation |
| 132 | + |
| 133 | +See the existing implementations of `A2AEvent`, `Part`, and `FileContent` hierarchies as reference patterns for implementing new discriminated types. |
0 commit comments