This is an automated email from the ASF dual-hosted git repository.
Lee-W pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 3a23d4429e5 Clarify what common.ai message_history does and does not
cover (#74625)
3a23d4429e5 is described below
commit 3a23d4429e554a8fc124de335667e7dd29b28ba6
Author: Wei Lee <[email protected]>
AuthorDate: Wed Oct 14 17:28:04 2026 +0900
Clarify what common.ai message_history does and does not cover (#74625)
* Clarify what common.ai message_history does and does not cover
Readers looking for agent memory in common.ai land on this page, but it did
not say that message_history is only a transcript hand-off between runs, with
no built-in cross-session memory. Point them to the pydantic-ai message history
documentation for what the underlying library offers.
* Explain how to trim common.ai message_history and carry facts across
sessions
- Document that ProcessHistory works through capabilities= and that the
transcript pushed to XCom is then the trimmed one
- Add a tool-call-safe history processor example
- Say how to carry facts across sessions: store them and load them in an
upstream task
- Shorten the section that repeated the storage guidance above it
---
providers/common/ai/docs/message_history.rst | 62 +++++++++++++++++++++++++---
1 file changed, 57 insertions(+), 5 deletions(-)
diff --git a/providers/common/ai/docs/message_history.rst
b/providers/common/ai/docs/message_history.rst
index f75f8d6b2b9..af76b8b76de 100644
--- a/providers/common/ai/docs/message_history.rst
+++ b/providers/common/ai/docs/message_history.rst
@@ -47,14 +47,66 @@ straight back in on the next run. When pulling it via a
template, pass
``default='[]'`` (as above) so the first run -- which has no XCom yet --
starts a
fresh session instead of trying to parse the string ``"None"``.
-The transcript is **cumulative**: each turn appends to it, so it grows for the
-life of the session. For long sessions, configure an object-storage XCom
backend
-or trim older turns before the next run rather than feeding the whole history
-back unbounded.
-
.. note::
``message_history`` cannot be combined with ``enable_hitl_review`` -- the
operator raises at construction. The post-review (human-approved)
transcript
is not recoverable today, so emitting the pre-review transcript would
silently drop the reviewed turns.
+
+Message format, and limiting session size
+-----------------------------------------
+
+The transcript is stored as pydantic-ai's JSON message format. It is
+**cumulative**: each turn appends to it, so it grows for the life of the
+session. The operator does not trim it itself, but ``capabilities=`` is passed
+to the pydantic-ai ``Agent``, so the ``ProcessHistory``
+capability from pydantic-ai's documentation works on ``AgentOperator`` as is:
+
+.. code-block:: python
+
+ from pydantic_ai.capabilities import ProcessHistory
+ from pydantic_ai.messages import ModelMessage, ModelRequest, ToolReturnPart
+
+
+ def keep_recent(messages: list[ModelMessage]) -> list[ModelMessage]:
+ tail = messages[-10:]
+ # Start at a request without tool returns, so no tool return is left
+ # without its tool call.
+ for i, message in enumerate(tail):
+ if isinstance(message, ModelRequest) and not any(
+ isinstance(part, ToolReturnPart) for part in message.parts
+ ):
+ return tail[i:]
+ return messages
+
+
+ AgentOperator(
+ task_id="chat",
+ ...,
+ capabilities=[ProcessHistory(keep_recent)],
+ )
+
+pydantic-ai writes the processed list back into the run state, and
+``result.all_messages()`` returns that list. With a history processor set, the
+transcript pushed to XCom is therefore the **trimmed** one, and turns the
+processor drops are no longer part of the stored session. Alternatively, read
the
+``message_history`` XCom in a downstream task, trim it, store it in your own
+session store, and load it from there on the next run; or configure an
+object-storage XCom backend for long sessions.
+
+The operator has no built-in cross-session memory. To let an agent use facts
+from earlier sessions, store them yourself, load them in an upstream task (the
+same load, run, store pattern as above), and put them in the prompt or the
+instructions.
+
+Related pydantic-ai documentation
+---------------------------------
+
+The transcript is a pydantic-ai message list, so pydantic-ai's own
+documentation applies to it. The
+`message history page
<https://pydantic.dev/docs/ai/core-concepts/message-history/>`__
+covers accessing messages from a result, storing and loading them as JSON,
+persisting sessions, editing existing messages, and processing the history
+before it reaches the model (for example keeping only recent messages or
+summarizing old ones).
