Repository navigation
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…pes it without the framework Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…he latest user message Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…istory misses a failed turn Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related: #655 (the AutoGen memory, which this framework succeeds)
Related: #696 (the Google ADK memory service, the same per-user session rule)
Changelog category (leave one):
Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):
The Python SDK ships
LoomContextProvider, a Microsoft Agent Framework context provider: before each run it adds the user's Loom memories to the instructions, and after the run Loom extracts the turn's facts (pip install 'clickhouse-loom[agent-framework]').Why
Agent Framework agents reach Loom today only through raw SDK calls or MCP. The framework's extension point for memory is the context provider an
Agenttakes incontext_providers=[...](agent_framework.ContextProvider):before_runadds context before the model call andafter_runsees the response. This PR implements that provider over the SDK. The data stays in the user's Loom deployment: no store, vector database or cache is added. AutoGen's repository points new work to Agent Framework, so the docs say a new project uses this provider and the AutoGen memory stays for AutoGen projects.Design (interfaces read from agent-framework-core 1.26.0):
before_runrunsmemory.searchwith the run's latest user message (as the AutoGen and LlamaIndex adapters search), pinned like the other adapters (namespace_scope="this",bodies="full",explain=False); withhonour_abstainit dropsbelow_thresholdrows before thetop_kcut and adds nothing on abstain. The matches go in as one block of instructions (SessionContext.extend_instructions), which the framework appends to the agent's own instructions. A run with no user text (an image only) reads nothing.after_runsends the user text of the run's new turn (the input after its last assistant message, so a caller that passes the whole conversation each run sends each turn once) and the assistant text of the response tomemory.set_from_messages, in calls of at most 400 messages (the op's cap). Tool calls and tool results are not sent.defer=Trueby default queues the extraction.maf-<first 20 hex of sha256 of the JSON [user, session id]>: Loom files a turn's verbatim chunks by session alone, and a caller may choose its own session ids, so two users' sessions named alike would otherwise share chunk rows (The Python SDK ships a Google ADK memory service #696 found this for ADK).user_idis the end user the memories belong to. Unset, the provider reads and writes the namespace's shared memories; an empty or-user is refused, since in Loom it names no user. Each user's writes are judged against that user's memories only once A write that names its user is judged against that user's rows only #701 lands; this PR does not depend on it to be correct for a single user.ContextProvideris not aHistoryProvider, so the framework still adds its in-memory history provider beside it, for a run given a session whose client does not store the conversation itself.after_run_once_per_turn = True: inside anAgentLoopMiddlewareloop the turn is sent once, when the loop ends; the loop's aggregated response carries its own continue prompts as user messages, so only the response's assistant messages are sent. A streamed loop, or one withreturn_final_only=True, hands the end-of-turn hook only its last iteration's response, so Loom gets the user's input and the last reply (a test pins it).before_runis per iteration, so after the first iteration the memories match the loop's prompt, not the user's request; the docs say both. Loom holds the memories across sessions; the turn-by-turn history stays the framework's. A LoomHistoryProviderwould need a per-session raw transcript store in Loom, which is a separate question and not in this PR.SyncAgentis refused with aTypeError(the framework awaits its providers);top_koutside 1–500 is refused.Agent: an error inbefore_runorafter_runfails the run; the provider does not catch. A failure after the run comes once the model answered: a history provider that runs after Loom's (the agent's in-memory one) does not record the turn, a tool's effect stays and a streamed reply has been shown; the failure modes say so.clickhouse-loom[agent-framework]pinsagent-framework-core>=1.26,<2(semver past 1.0) and joinsSDK_ADAPTER_EXTRAS;agent_frameworkjoins the root mypy overrides, since the SDK gate runs without the extra.Scope and risk
SDK-only: one module, an extra, docs. No server, wire or schema change, and
uv.lockis unchanged.Compatibility, rollout and rollback
Tests
sdk/python/tests/test_agent_framework.pythroughmake test-sdk-adapter-agent-framework(16 tests;mypy --stricton the module), driving the framework's realAgentwith a scripted chat client: it is aContextProvider; the memories reach the model's instructions with the pinned search fields; each run's turn is sent after it with the user, the derived session anddefer; the session is per user and unambiguous; only user and assistant text is sent (system, tool and blank messages and the function call are left out, the exact list checked); abstention and rows below the floor add nothing; thetop_kcut after the floor filter; a run without user text reads nothing; 401 messages go out as 400 + 2 (the 401 inputs and the reply); without a user the provider reads and writes the namespace; a two-iterationAgentLoopMiddlewareloop sends the user's turn and both replies once, without the loop's prompts, and the same loop streamed sends the last reply; a run given the whole conversation sends only its new turn and searches with the latest user message; the refusals; the import error names the extra; a realloom.Agentpostsmemory.searchandmemory.set_from_messageswith the expected bodies.SDK_ADAPTERS_RESOLUTION=lowest-directon Python 3.11 (agent-framework-core 1.26.0).tests/integration/test_sdk_agent_framework_memory.pyagainst a local server (fake LLM and embedder): a run's turn is extracted and the fact read back with the Loom agent, the user, the derived session and source classextracted; a later run in a new session gets it in its instructions, and another user's run does not. 1 passed with agent-framework-core installed; without it the module skips, as in CI's integration jobs.make format lint; the unit tests that name the integrations, the extras, the framework docs, doc links and public copy (978 passed).AI assistance in the code (leave one; writing this description with AI is fine):
AI-generated (an agent wrote most of the diff): Claude Code. Checked:
ContextProvider,SessionContext,HistoryProviderand the agent's history auto-injection against agent-framework-core 1.26.0 source, runs through the framework'sAgent, and the provider against a running Loom.I can explain every line of this diff and how it interacts with the rest of Loom.
Checklist
make format-check,make lint,make typecheckandmake test-unitpass (locally the named unit tests; the full suite in CI'spytest unitparts); the integration suite passes if server behaviour changed.docs/reference/configuration.mdand thedocs/reference/tables (python scripts/codegen/docs_reference.py), the reach manifest,schemas/schema.sql(make schema-dump) and the Codex plugin copies (python3 scripts/codegen/agent_plugin_sync.py).main; no merged migration is edited.hooks/,lib/,bin/,skills/,.mcp.json, the Codexplugin-defaults.json) bumps both plugin manifests' version, and no other open PR uses that version.npm --prefix frontend run build) and its tests pass, iffrontend/changed.docs/describe the system as it now is, and this description names any operator steps and wire changes.tests/unit/test_public_copy.py).git commit -s), as CONTRIBUTING.md asks.🤖 Generated with Claude Code