Skip to content

The Python SDK ships a Microsoft Agent Framework context provider - #729

Open
zlareb1 wants to merge 4 commits into
mainfrom
feat/sdk-agent-framework
Open

zlareb1 wants to merge 4 commits into
mainfrom
feat/sdk-agent-framework

Conversation

@zlareb1

@zlareb1 zlareb1 commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

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):

  • New Feature

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 Agent takes in context_providers=[...] (agent_framework.ContextProvider): before_run adds context before the model call and after_run sees 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_run runs memory.search with 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); with honour_abstain it drops below_threshold rows before the top_k cut 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_run sends 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 to memory.set_from_messages, in calls of at most 400 messages (the op's cap). Tool calls and tool results are not sent. defer=True by default queues the extraction.
  • Session. Extraction runs under the Loom session 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. user_id is 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.
  • History. A ContextProvider is not a HistoryProvider, 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.
  • Loops. after_run_once_per_turn = True: inside an AgentLoopMiddleware loop 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 with return_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_run is 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 Loom HistoryProvider would need a per-session raw transcript store in Loom, which is a separate question and not in this PR.
  • A SyncAgent is refused with a TypeError (the framework awaits its providers); top_k outside 1–500 is refused.
  • Failure behaviour, probed with the framework's Agent: an error in before_run or after_run fails 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] pins agent-framework-core>=1.26,<2 (semver past 1.0) and joins SDK_ADAPTER_EXTRAS; agent_framework joins 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.lock is unchanged.

Compatibility, rollout and rollback

  • Wire: none.
  • Operator steps: none.
  • Rollback: reverting removes the module and the extra.

Tests

  • sdk/python/tests/test_agent_framework.py through make test-sdk-adapter-agent-framework (16 tests; mypy --strict on the module), driving the framework's real Agent with a scripted chat client: it is a ContextProvider; 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 and defer; 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; the top_k cut 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-iteration AgentLoopMiddleware loop 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 real loom.Agent posts memory.search and memory.set_from_messages with the expected bodies.
  • The same tests pass with SDK_ADAPTERS_RESOLUTION=lowest-direct on Python 3.11 (agent-framework-core 1.26.0).
  • tests/integration/test_sdk_agent_framework_memory.py against 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 class extracted; 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, HistoryProvider and the agent's history auto-injection against agent-framework-core 1.26.0 source, runs through the framework's Agent, 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 typecheck and make test-unit pass (locally the named unit tests; the full suite in CI's pytest unit parts); the integration suite passes if server behaviour changed.
  • Generated files are regenerated in this PR, not by hand: the SDK op tables, docs/reference/configuration.md and the docs/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).
  • A new migration is additive and numbered after the latest on main; no merged migration is edited.
  • A behaviour change to any file a plugin ships (hooks/, lib/, bin/, skills/, .mcp.json, the Codex plugin-defaults.json) bumps both plugin manifests' version, and no other open PR uses that version.
  • The frontend builds (npm --prefix frontend run build) and its tests pass, if frontend/ changed.
  • Docs under docs/ describe the system as it now is, and this description names any operator steps and wire changes.
  • Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (tests/unit/test_public_copy.py).
  • Commits are signed off (git commit -s), as CONTRIBUTING.md asks.

🤖 Generated with Claude Code

zlareb1 and others added 4 commits November 16, 2026 07:20
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

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant