From 5894d44e160806ed30346092a96fc6241ca9af43 Mon Sep 17 00:00:00 2001 From: tryambak2019 Date: Tue, 15 Sep 2026 20:38:50 -0400 Subject: [PATCH 1/3] docs: add Python API v2 reconciliation ledger Signed-off-by: tryambak2019 --- .../plans/issue-2689-python-reconciliation.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/plans/issue-2689-python-reconciliation.md diff --git a/docs/plans/issue-2689-python-reconciliation.md b/docs/plans/issue-2689-python-reconciliation.md new file mode 100644 index 0000000000..84aeb55248 --- /dev/null +++ b/docs/plans/issue-2689-python-reconciliation.md @@ -0,0 +1,72 @@ +# Issue #2689 Python Reconciliation + +## Purpose + +This document is the closing ledger for the Python API v2 audit in #2689. It is +intentionally separate from the narrow documentation and startup PRs so that +the final conclusion is based on their merged state rather than a partial +branch. + +It does not declare #2689 complete. A retained item is supported only after its +execution path, documentation, and API v2 behavior satisfy the gates below. + +## Inventory + +| Kind | Item | Current reconciliation status | +| --- | --- | --- | +| Package | `agentsts-adk` | Requires API v2 audit and documented support decision. | +| Package | `agentsts-core` | Requires API v2 audit and documented support decision. | +| Package | `kagent-adk` | Requires API v2 audit; the `adk/basic` image command must be exercised against its packaged filesystem layout. | +| Package | `kagent-core` | Requires API v2 audit and documented support decision. | +| Package | `kagent-crewai` | README contains unverified Kagent-backed memory and Flow-persistence claims that must be corrected or the backing behavior restored. | +| Package | `kagent-langgraph` | Documentation correction is owned by #2821; runtime support still requires audit evidence. | +| Package | `kagent-openai` | Documentation correction is owned by #2821; runtime support still requires audit evidence. | +| Package | `kagent-proto` | Requires API v2 audit and documented support decision. | +| Package | `kagent-skills` | Requires API v2 audit and documented support decision. | +| Sample | `adk/basic` | Startup slice is owned by #2832; validate the built image's agent-loader path before retaining it. | +| Sample | `crewai/poem_flow` | Startup slice is owned by #2834; requires supported-path and documentation audit. | +| Sample | `crewai/research-crew` | Startup slice is owned by #2834; requires supported-path and documentation audit. | +| Sample | `langgraph/currency` | Documentation and startup slices are owned by #2821 and #2829; requires end-to-end A2A, deployment, and checkpoint-restart validation. | +| Sample | `langgraph/hitl-tools` | Startup slice is owned by #2831; requires supported-path and documentation audit. | +| Sample | `langgraph/kebab` | Startup slice is owned by #2831; requires supported-path and documentation audit. | +| Sample | `openai/basic_agent` | Startup slice is owned by #2830; requires supported-path and documentation audit. | + +## Reconciliation Gates + +1. Rebase this work after the preceding #2689 slices merge. Do not duplicate + files owned by those PRs unless their merged state still needs correction. +2. For every retained sample, record one API v2 execution path and validate the + guarantees its README and deployment material claim. A mocked Uvicorn call + and a health response alone do not prove container startup, A2A execution, + deployment, or durable restart behavior. +3. Correct or remove every package/sample statement that promises deleted + Kagent-owned session persistence, removed REST services, or unsupported + legacy Agent APIs. Keep framework-local session terminology only where the + source and public API demonstrate that it remains valid. +4. Run and retain the final classified search result: + + ```bash + rg -n -i 'KAgentSession|_session_service|session service|controller.*8083|agent.*sessions' python --glob '*.py' --glob '*.md' --glob '*.json' --glob '*.yaml' --glob '*.yml' + ``` + + Each remaining match must be either removed or listed as explicitly + framework-local or historical material with source evidence. +5. Add a focused automated guard for the forbidden legacy surface, with + documented exclusions for the classified valid matches. Run that guard and + the affected Python tests in CI. + +## Known Blockers Before Closure + +- #2821's Currency README explicitly states that it has no documented + end-to-end runtime command yet. +- The #2832 image copies the `basic` agent directory to `/app/basic`, while + `kagent-adk run basic --working-dir /app/basic` resolves the agent beneath + `/app/basic/basic`. +- `kagent-crewai` currently documents Kagent-backed session memory and Flow + state persistence without evidence of a current backing API. + +## Completion Record + +The reconciliation PR may close #2689 only after every inventory row has a +recorded disposition, all retained samples satisfy the execution/documentation +gates, and the final classified search plus CI guard pass on the merged base. \ No newline at end of file From a81c6ccc9b80b02b62fa47ac467ac9d4f075769a Mon Sep 17 00:00:00 2001 From: tryambak2019 Date: Tue, 15 Sep 2026 20:43:48 -0400 Subject: [PATCH 2/3] docs(crewai): remove unsupported persistence claims Signed-off-by: tryambak2019 --- python/packages/kagent-crewai/README.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/python/packages/kagent-crewai/README.md b/python/packages/kagent-crewai/README.md index 0f34c61f5d..be9445f2a8 100644 --- a/python/packages/kagent-crewai/README.md +++ b/python/packages/kagent-crewai/README.md @@ -1,14 +1,12 @@ # KAgent CrewAI Integration -This package provides CrewAI integration for KAgent with A2A (Agent-to-Agent) server support and session-aware memory storage. +This package provides CrewAI integration for KAgent with A2A (Agent-to-Agent) server support. ## Features - **A2A Server Integration**: Compatible with KAgent's Agent-to-Agent protocol - **Event Streaming**: Real-time streaming of crew execution events - **FastAPI Integration**: Ready-to-deploy web server for agent execution -- **Session-aware Memory**: Store and retrieve agent memories scoped by session ID -- **Flow State Persistence**: Save and restore CrewAI Flow states to KAgent backend ## Quick Start @@ -49,19 +47,15 @@ research_task: This is equivalent of `crew.kickoff(inputs={"input": "your input text"})` when triggering agents manually. -### Session-aware Memory +### Memory and Flow State #### CrewAI Crews -Session scoped memory is implemented using the `LongTermMemory` interface in CrewAI. If you wish to share memories between agents, you must interact with them in the same session to share long term memory so they can search and access the previous conversation history (because agent ID is volatile, we must use session ID). You can enable this by setting `memory=True` when creating your CrewAI crew. Note that this memory is also scoped by user ID so different users will not see each other's memories. - -Our KAgent backend is designed to handle long term memory saving and retrieval with the identical logic as `LTMSQLiteStorage` which is used by default for `LongTermMemory` in CrewAI, with the addition of session and user scoping. It will search the LTM items based on the task description and return the most relevant items (sorted and limited). - -> Note that when you set `memory=True`, you are responsible to ensure that short term and entity memory are configured properly (e.g. with `OPENAI_API_KEY` or set your own providers). The KAgent CrewAI integration only handles long term memory. +`KAgentApp` does not configure or persist CrewAI memory. Configure CrewAI memory and its backing storage explicitly when your application needs it. #### CrewAI Flows -In flow mode, we implement memory similar to checkpointing in LangGraph so that the flow state is persisted to the KAgent backend after each method finishes execution. We consider each session to be a single flow execution, so you can reuse state within the same session by enabling `@persist()` for flow or methods. We do not manage `LongTermMemory` for crews inside a flow since flow is designed to be very customizable. You are responsible for implementing your own memory management for all the crew you use in the flow. +`KAgentApp` creates a Flow instance for each A2A request. It does not persist Flow state or restore it for later requests. Configure persistence in your Flow application when needed. ### Tracing @@ -74,9 +68,9 @@ The package mirrors the structure of `kagent-adk` and `kagent-langgraph` but use - **CrewAIAgentExecutor**: Executes CrewAI workflows within A2A protocol - **KAgentApp**: FastAPI application builder with A2A integration - **Event Converters**: Translates CrewAI events into A2A events for streaming. -- **Task history**: The public A2A gateway persists client-visible task and event history. +- **Task store**: Tracks A2A tasks in memory for the lifetime of the application process. -For local development, configure the HTTP endpoint used by protocol traffic: +`KAgentConfig` requires its configuration values, but this wrapper does not use `KAGENT_API_URL` or `KAGENT_GATEWAY_URL` for outbound connections. For local development, configure the required values: ```bash export KAGENT_API_URL=http://localhost:8083 @@ -87,4 +81,4 @@ export KAGENT_NAMESPACE=default ## Deployment -The uses the same deployment approach as other KAgent A2A applications (ADK / LangGraph). You can refer to `samples/crewai/` for examples. +Use the `samples/crewai/` applications as deployment examples. This package does not provide a Kagent-backed memory or Flow-persistence service. From 702d3cfb28639645c0c949738720b4d49c4cdc37 Mon Sep 17 00:00:00 2001 From: tryambak2019 Date: Tue, 15 Sep 2026 20:55:37 -0400 Subject: [PATCH 3/3] docs: update Python reconciliation blockers Signed-off-by: tryambak2019 --- docs/plans/issue-2689-python-reconciliation.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/plans/issue-2689-python-reconciliation.md b/docs/plans/issue-2689-python-reconciliation.md index 84aeb55248..d8da8001f2 100644 --- a/docs/plans/issue-2689-python-reconciliation.md +++ b/docs/plans/issue-2689-python-reconciliation.md @@ -16,14 +16,14 @@ execution path, documentation, and API v2 behavior satisfy the gates below. | --- | --- | --- | | Package | `agentsts-adk` | Requires API v2 audit and documented support decision. | | Package | `agentsts-core` | Requires API v2 audit and documented support decision. | -| Package | `kagent-adk` | Requires API v2 audit; the `adk/basic` image command must be exercised against its packaged filesystem layout. | +| Package | `kagent-adk` | The `adk/basic` command now uses the sample root as its agent directory; requires API v2 audit and image-level execution validation. | | Package | `kagent-core` | Requires API v2 audit and documented support decision. | -| Package | `kagent-crewai` | README contains unverified Kagent-backed memory and Flow-persistence claims that must be corrected or the backing behavior restored. | +| Package | `kagent-crewai` | Unsupported Kagent-backed memory and Flow-persistence claims are corrected in this PR; requires API v2 audit and integrated residual-search classification. | | Package | `kagent-langgraph` | Documentation correction is owned by #2821; runtime support still requires audit evidence. | | Package | `kagent-openai` | Documentation correction is owned by #2821; runtime support still requires audit evidence. | | Package | `kagent-proto` | Requires API v2 audit and documented support decision. | | Package | `kagent-skills` | Requires API v2 audit and documented support decision. | -| Sample | `adk/basic` | Startup slice is owned by #2832; validate the built image's agent-loader path before retaining it. | +| Sample | `adk/basic` | #2832 corrects the container agent root; validate built-image startup and the supported execution path before retaining it. | | Sample | `crewai/poem_flow` | Startup slice is owned by #2834; requires supported-path and documentation audit. | | Sample | `crewai/research-crew` | Startup slice is owned by #2834; requires supported-path and documentation audit. | | Sample | `langgraph/currency` | Documentation and startup slices are owned by #2821 and #2829; requires end-to-end A2A, deployment, and checkpoint-restart validation. | @@ -59,11 +59,8 @@ execution path, documentation, and API v2 behavior satisfy the gates below. - #2821's Currency README explicitly states that it has no documented end-to-end runtime command yet. -- The #2832 image copies the `basic` agent directory to `/app/basic`, while - `kagent-adk run basic --working-dir /app/basic` resolves the agent beneath - `/app/basic/basic`. -- `kagent-crewai` currently documents Kagent-backed session memory and Flow - state persistence without evidence of a current backing API. +- The final classified repository search and CI guard have not yet been added + or run against the integrated post-merge state. ## Completion Record