René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"feat: improve schema usability type instantiation","articleBody":"### Problem statement\n\nI'm just diving into using this SDK to add a compatibility layer to an agent service for ACP clients, and encountered a few initial difficulties with regards to the schema that felt could be improved.\n\nFirst is that when instantiating classes that have a required field and only one possible value, that field shouldn't need to be provided, it should default. For example, when I construct `AgentMessageChunk`, the `session_update` field only has one possible value, `\"agent_message_chunk\"`. It's a required field, and it cannot be anything else. So why do I have to provide it? I understand that it's used as the discriminator when deserializing, but when `AgentMessageChunk` is constructed explicitly, it shouldn't be needed. This is a common pattern, not exclusive to `AgentMessageChunk`.\n\nHowever if these fields are given a default such as:\n```\nclass AgentMessageChunk(ContentChunk):\n    session_update: Annotated[Literal[\"agent_message_chunk\"], Field(alias=\"sessionUpdate\")] = \"agent_message_chunk\"\n```\nThis then leads to another issue, in that when the SDK serializes the message, it's omitted because of `exclude_defaults=True` in https://github.com/agentclientprotocol/python-sdk/blob/a09e090cf3db70491abacb126d016187552796e1/src/acp/utils.py#L33\n\nNow after going through the examples, I noticed that you provide helpers such as `update_agent_message` for addressing this. But IMHO these should not be necessary. When I look at a function or class, and I see that it accepts some type, I shouldn't have to go hunting through the source code to see if there's a helper that is supposed to be used for construction of that type. And while I would argue that the type shouldn't need a helper at all, and that types should be simple to instantiate directly, if there is going to be a helper, I think it would be better for discoverability to put the helper as a static/class method on the class itself. Then if you want to expose all the helpers in some top level package for ease of import, you would declare local variables which reference the static method.\n\n### Proposed solution\n\n* Change all types that have a required parameter with only a single possible value to default to that value.\n* Change `params.model_dump` to use `exclude_defaults=False`.\n    * A little more work, but if you still want to use `exclude_defaults`, then implement a custom serializer that does exclude defaults, but only when the field is optional.\n* Remove the helpers.\n\n\n### Alternatives considered\n\nMake the helpers easier to discover by putting them as static methods on the class they construct.\n\n### Additional context\n\n_No response_\n\n### Can you help build it?\n\n- [ ] I can contribute code or docs for this request.","author":{"url":"https://github.com/phemmer","@type":"Person","name":"phemmer"},"datePublished":"2025-12-14T19:37:38.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/47/python-sdk/issues/47"}