Skip to content

Python: [Bug]: DevUI item ids returned by the items list cannot be fetched by id #9862

Open

Description

Observed Behavior

The conversation items endpoints disagree about item identity. add_items mints item_<uuid> ids and get_item resolves only those, while list_items derives positional item_<index> ids from the stored messages. So GET /v1/conversations/{id}/items/item_0 responds 404 for an id the list endpoint just returned, and agent run messages, which never pass through add_items, cannot be fetched by id at all.

Expected Behavior

Per the OpenAI Conversations contract the route advertises, an id returned by the list endpoint must be retrievable through the item endpoint.

Steps to Reproduce

  1. Create a conversation.
  2. Call add_items with one user message; note the returned item_<uuid> id.
  3. Call list_items; the same message comes back as item_0.
  4. Call get_item with item_0, then with the uuid id.

Minimal Reproduction

import asyncio
from agent_framework_devui._conversations import InMemoryConversationStore

async def main() -> None:
    store = InMemoryConversationStore()
    conv = store.create_conversation(metadata={})
    added = await store.add_items(conv.id, items=[{"role": "user", "content": [{"type": "text", "text": "Hello"}]}])
    listed, _ = await store.list_items(conv.id)
    assert listed[0].id == "item_0"
    assert await store.get_item(conv.id, listed[0].id) is None   # listed id is unreadable
    assert await store.get_item(conv.id, added[0].id) is not None

asyncio.run(main())

Error Messages and Stack Traces

No exception in the store; the route translates the None into a 404 Item not found.

Package Versions

agent-framework-devui: 1.0.0b261022 (main @ 4d28d0a)

Python Version

Python 3.14.8

Operating System

macOS

Regression

Unknown

Additional Context

The list id scheme is positional per message (item_<index>, plus item_<index>_call_<call id> and item_<index>_result_<call id> for tool traffic), so retrieval can resolve those ids by rebuilding the addressed message's items with the exact same conversion the list uses. I have a fix that shares the per message conversion between list and get ready once the team agrees with the direction.

Acknowledgements

  • I searched existing issues and did not find a duplicate.
  • I personally verified this behavior and the reproduction details are authentic.
  • I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

Activity

  1. eavanvalkenburg commented on Oct 30, 2026

    @eavanvalkenburg
    Member

    please use the defined issue templates and wait for the team to review before opening a PR Manohar Paturi (@ManoharPaturi)

  2. changed the title [-]DevUI: item ids returned by the items list cannot be fetched by id[/-] [+]Python: [Bug]: DevUI item ids returned by the items list cannot be fetched by id[/+] on Oct 31, 2026
  3. eavanvalkenburg commented on Nov 9, 2026

    @eavanvalkenburg
    Member

    /plan Plan the confirmed DevUI conversation-item identity mismatch on current main. add_items indexes UUID IDs, list_items renders positional message/call/result IDs, and get_item only checks the UUID index or checkpoint IDs; agent-run messages also bypass the add_items index. Current-source inspection and an isolated exact get_item index-fixture probe confirm the retrieval gap, not a full HTTP reproduction. Establish the smallest correct shared conversion/retrieval design for listed message, function-call, and function-result IDs while preserving existing UUID lookup, content, cursor/order behavior, missing-item behavior, and lazy checkpoint retrieval. Account for multiple items per message, call IDs containing separators, and agent-run messages; do not silently change the advertised identity contract or mark this ready via a list-all fallback that misses pagination or mixed-item cases. Evaluate the original helper-extraction direction in already closed #9863 without reopening it or starting implementation; its production scope is materially above the minor-fix threshold. Specify focused store/HTTP round-trip and pagination controls, then scope the production change. Retain triage, do not add ready-for-implementation, and defer assignment until planning. This is planning, not implementation approval.

  4. github-actions commented on Nov 9, 2026

    @github-actions
    Contributor

    Summary

    In DevUI's in-memory conversation store, the list and get endpoints disagree about item IDs.

    • list_items builds IDs from message position: item_<n>, item_<n>_call_<call_id> and item_<n>_result_<call_id> (_conversations.py list_items).
    • add_items mints item_<uuid> IDs and records them in _item_index.
    • get_item (line 747) checks only that index, then checkpoint_* IDs. So an ID that the list endpoint just returned can give 404 from GET /v1/conversations/{id}/items/{item_id} (_server.py route).

    Confirmed by reading current source: the lookup gap, and that list_items rebuilds everything from conv_data["messages"] and never uses the cached items. Agent-run messages go into messages without passing through add_items, so they can never be found by ID.

    Not done: I did not run anything. This is not a full HTTP reproduction, and I have not inspected #9863's diff.

    Recommendation

    A code change is warranted, and it can be small. The list endpoint advertises these IDs, and the OpenAI Conversations contract says a listed ID should be retrievable. There is no workaround short of listing everything and filtering client-side. That is not a fix: it breaks pagination and has to be repeated per lookup.

    Keep both identity schemes. Do not silently change what IDs mean.

    • The UUID IDs returned by add_items stay valid.
    • The positional IDs from list_items become resolvable too.
    • One message therefore keeps two valid IDs. That is an existing quirk. Unifying them would change the contract and needs a separate decision, ideally an ADR.

    Caveat: positional IDs are stable only while messages are append-only. I found no delete path in the store. If one is added later, it would shift these IDs.

    On #9863's helper-extraction direction: the idea is sound. A shared per-message converter is the only way to guarantee list and get produce identical items. But it should be scoped narrowly. The converter body should move verbatim into one helper, with no behavior or formatting changes. Anything beyond that is out of proportion for this bug. A "convert all messages, then search" fallback is not acceptable: it would be O(n) per get, and it would be easy to get cursor behavior wrong.

    Proposed plan (nothing has been implemented)

    1. Extract a helper, for example _message_to_items(index, msg) -> list[ConversationItem]. Move the per-message loop body out of list_items unchanged. It produces the message item (only if the message has text, image or file parts), then the call items, then the result items. list_items calls it per message and keeps checkpoint appending, desc reversal and after cursor logic as they are.

    2. Resolve positional IDs in get_item.

      • Order of lookups: the UUID index first (existing behavior), then positional IDs, then checkpoint_ (unchanged, still lazy).
      • Parse only the leading item_(\d+) prefix with an anchored regex.
      • Do not split on _. Call IDs can contain _, _call_ or _result_.
      • Rebuild just that one message with the helper and return the item whose id equals the requested ID exactly.
    3. Cover the edge cases that follow from this design.

      • A message with text plus calls and results yields several items. Each must be fetchable.
      • A function-only message has no item_<n> message item, so item_<n> correctly stays 404, matching the list.
      • An out-of-range index, a non-numeric index or an unknown call suffix returns None, which the route turns into 404.
      • Duplicate call IDs within one message produce duplicate listed IDs. The first match wins. Note this as a pre-existing limitation.
      • Messages added directly to the conversation (as agent runs do) resolve positionally with no change to the run path.
    4. Tests, in tests/devui/test_conversations.py and the HTTP tests:

      • Round trip: for every ID from list_items (asc and desc), get_item returns an item equal to the listed one in content, type and role.
      • Mixed message with text, two calls and a result, including a call ID like a_call_b_result_c.
      • Pagination: walk pages with limit=1 and after, and fetch each ID returned. Include checkpoint items. The existing checkpoint pagination test is a good template.
      • Regression: UUID IDs still resolve; a missing ID gives 404; checkpoint_* still loads lazily and is not called for item_* IDs.
      • HTTP: create a conversation, post items, then run GET .../items followed by GET .../items/{id} for each. Also add an agent-run-style message through the store.
    5. Docs: a one-line note in the DevUI README items section that listed IDs are positional and the UUIDs from add_items are also accepted. No changelog edit, since release prep handles it.

    Done when: every ID returned by list, in any page or order, is retrievable with identical content, and all existing tests pass. The production change should be about one extracted function plus a small parser in get_item.

    This is a proposal only. Per the request, the issue keeps triage, has no ready-for-implementation, and assignment is deferred. A maintainer should confirm that both ID schemes stay accepted before anyone implements.

    Generated by Issue Planning for #9862 · copilot · auto · ~17 AIC · ⌖ ~1 AIC · ⊞ 4.8K · ◷

  5. ManoharPaturi commented on Nov 10, 2026

    @ManoharPaturi
    ContributorAuthor

    Eduard van Valkenburg (@eavanvalkenburg) should i start working on this ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageUsage: [Issues], Target: All issues that still need to be triaged

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions