From ffba694f2d9717664ff64ea59565e0fca85489d9 Mon Sep 17 00:00:00 2001 From: tryambak2019 Date: Mon, 14 Sep 2026 16:07:57 -0400 Subject: [PATCH] docs(python): align integration READMEs with API v2 Signed-off-by: tryambak2019 --- python/packages/kagent-langgraph/README.md | 69 +++--------- python/packages/kagent-openai/README.md | 114 +++++++++----------- python/samples/langgraph/currency/README.md | 88 ++++----------- 3 files changed, 80 insertions(+), 191 deletions(-) diff --git a/python/packages/kagent-langgraph/README.md b/python/packages/kagent-langgraph/README.md index 98d26f448e..df8c37b468 100644 --- a/python/packages/kagent-langgraph/README.md +++ b/python/packages/kagent-langgraph/README.md @@ -4,71 +4,26 @@ This package provides LangGraph integration for KAgent with A2A (Agent-to-Agent) ## Features -- **A2A Server Integration**: Compatible with KAgent's Agent-to-Agent protocol -- **Event Streaming**: Real-time streaming of graph execution events -- **FastAPI Integration**: Ready-to-deploy web server for agent execution +- **A2A Server Integration**: Serves LangGraph workflows over A2A +- **Event Streaming**: Streams graph execution events +- **FastAPI Integration**: Builds a deployable FastAPI application -## Quick Start +## State and Task Storage -```python -from kagent.core import AsyncControllerClient, AsyncFileTokenProvider, KAgentConfig -from kagent.langgraph import KAgentApp -import os -import sqlite3 -from langgraph.checkpoint.sqlite import SqliteSaver -from langgraph.graph import StateGraph -from langchain_core.messages import BaseMessage -from typing import TypedDict, Annotated, Sequence +The LangGraph checkpointer owns graph conversation state. A SQLite checkpointer stores checkpoints in a local file; persistence across pod replacement requires placing that file on durable storage or selecting another durable LangGraph checkpointer. -class State(TypedDict): - messages: Annotated[Sequence[BaseMessage], "The conversation history"] - -config = KAgentConfig() -controller_client = AsyncControllerClient( - config.grpc_url, - agent_name=config.app_name, - token_provider=AsyncFileTokenProvider(), -) - -# Define and compile your graph -builder = StateGraph(State) -# Add nodes and edges... -checkpointer = SqliteSaver(sqlite3.connect( - os.getenv("KAGENT_CHECKPOINT_DB", "/tmp/langgraph-checkpoints.sqlite"), - check_same_thread=False, -)) -graph = builder.compile(checkpointer=checkpointer) - -# Create KAgent app -app = KAgentApp( - graph=graph, - agent_card={ - "name": "my-langgraph-agent", - "description": "A LangGraph agent with KAgent integration", - "version": "0.1.0", - "capabilities": {"streaming": True}, - "defaultInputModes": ["text"], - "defaultOutputModes": ["text"] - }, - config=config, - controller_client=controller_client, -) - -# Build FastAPI application -fastapi_app = app.build() -``` +`KAgentApp` uses an in-memory A2A task store inside the agent process. That task state does not survive a process restart. This package does not configure a gateway connection; a deployment may place a gateway in front of the application and have that gateway own durable task history. ## Architecture -The package mirrors the structure of `kagent-adk` but uses LangGraph instead of Google's ADK: - -- **LangGraphAgentExecutor**: Executes LangGraph workflows within A2A protocol -- **KAgentApp**: FastAPI application builder with A2A integration -- **Task Management**: Automatic A2A task persistence through one shared authenticated gRPC channel +- **LangGraphAgentExecutor**: Executes LangGraph workflows over A2A +- **KAgentApp**: Builds the FastAPI A2A application +- **LangGraph checkpointer**: Stores graph conversation state when configured +- **InMemoryTaskStore**: Tracks A2A tasks for the lifetime of the process ## Configuration -Set both endpoints when running locally. A2A and MCP use `KAGENT_GATEWAY_URL`, while control-plane calls use `KAGENT_API_URL`. +`KAgentConfig` currently requires both endpoint values and the agent identity. This wrapper uses the identity and tracing configuration, but does not use these URLs for outbound control-plane or gateway calls: ```bash export KAGENT_API_URL=http://localhost:8083 @@ -79,4 +34,4 @@ export KAGENT_NAMESPACE=default ## Deployment -Use the same deployment pattern as kagent-adk samples with Docker and Kubernetes. +This package has no documented end-to-end deployment path yet. Sample documentation identifies the validation available for each sample. diff --git a/python/packages/kagent-openai/README.md b/python/packages/kagent-openai/README.md index 43e9b942d0..28af250b49 100644 --- a/python/packages/kagent-openai/README.md +++ b/python/packages/kagent-openai/README.md @@ -1,38 +1,52 @@ # KAgent OpenAI Agents SDK Integration -OpenAI Agents SDK integration for KAgent with A2A (Agent-to-Agent) protocol support, session management, and optional skills integration. +OpenAI Agents SDK integration for KAgent with A2A (Agent-to-Agent) protocol support and optional skills integration. --- ## Quick Start +Set the required configuration first: + +```bash +export KAGENT_API_URL=http://localhost:8083 +export KAGENT_GATEWAY_URL=http://localhost:8083 +export KAGENT_NAME=my-openai-agent +export KAGENT_NAMESPACE=default +export OPENAI_API_KEY=your-api-key +``` + +Then build the A2A application: + ```python -from kagent.openai import KAgentApp from agents.agent import Agent +from kagent.core import KAgentConfig +from kagent.openai import KAgentApp -# Create your OpenAI agent agent = Agent( name="Assistant", instructions="You are a helpful assistant.", - tools=[my_tool], # Optional + tools=[], ) -# Create KAgent app +agent_card = { + "name": "my-openai-agent", + "description": "My OpenAI agent", + "version": "0.1.0", + "supportedInterfaces": [ + {"url": "http://localhost:8080", "protocolBinding": "JSONRPC"} + ], + "capabilities": {"streaming": True}, + "defaultInputModes": ["text/plain"], + "defaultOutputModes": ["text/plain"], +} + app = KAgentApp( agent=agent, - agent_card={ - "name": "my-openai-agent", - "description": "My OpenAI agent", - "version": "0.1.0", - "capabilities": {"streaming": True}, - "defaultInputModes": ["text"], - "defaultOutputModes": ["text"] - }, - kagent_url="http://localhost:8083", - app_name="my-agent" + agent_card=agent_card, + config=KAgentConfig(), ) -# Run fastapi_app = app.build() # uvicorn run_me:fastapi_app ``` @@ -61,77 +75,48 @@ See [skills README](../../kagent-skills/README.md) for skill format and structur --- -## Session Management +## Task and Conversation State -Sessions persist conversation history in KAgent backend: - -```python -from agents.agent import Agent -from agents.run import Runner -from kagent.openai._session_service import KAgentSession -import httpx - -client = httpx.AsyncClient(base_url="http://localhost:8083") -session = KAgentSession( - session_id="conversation_123", - client=client, - app_name="my-agent", -) +`KAgentApp` uses an in-memory A2A task store and does not configure an OpenAI Agents SDK session. Task state held by the agent process is lost when that process restarts. This package does not configure a gateway connection; a deployment may place a gateway in front of the application and have that gateway own durable task history. -agent = Agent(name="Assistant", instructions="Be helpful") -result = await Runner.run(agent, "Hello!", session=session) -``` +Applications that need durable framework-level conversation state must configure it explicitly rather than relying on a KAgent REST session service. --- ## Local Development -Test without KAgent backend using in-memory mode: +`build_local()` creates the same kind of in-memory A2A application without connecting to a KAgent backend. `KAgentConfig` still requires its configuration values: ```python app = KAgentApp( agent=agent, agent_card=agent_card, - kagent_url="http://localhost:8083", - app_name="test-agent" + config=KAgentConfig(), ) -fastapi_app = app.build_local() # In-memory, no persistence -``` - ---- - -## Deployment - -Standard Docker deployment: - -```dockerfile -FROM python:3.13-slim -WORKDIR /app -COPY requirements.txt . -RUN pip install -r requirements.txt -COPY agent.py . -CMD ["uvicorn", "agent:fastapi_app", "--host", "0.0.0.0", "--port", "8000"] +fastapi_app = app.build_local() ``` -Set `KAGENT_API_URL` and `KAGENT_GATEWAY_URL` to connect to kagent. - --- ## Architecture -| Component | Purpose | -| ----------------------- | -------------------------------------------- | -| **KAgentApp** | FastAPI application builder with A2A support | -| **KAgentSession** | Session persistence via KAgent REST API | -| **OpenAIAgentExecutor** | Executes agents with event streaming | +| Component | Purpose | +| --- | --- | +| **KAgentApp** | FastAPI application builder with A2A support | +| **OpenAIAgentExecutor** | Executes agents with event streaming | +| **InMemoryTaskStore** | Tracks A2A tasks for the lifetime of the process | --- ## Environment Variables -- `KAGENT_API_URL` - KAgent control-plane API URL -- `KAGENT_GATEWAY_URL` - KAgent A2A and MCP gateway URL +- `KAGENT_API_URL` - Required by `KAgentConfig`; not used for outbound control-plane calls by this wrapper +- `KAGENT_GATEWAY_URL` - Required by `KAgentConfig`; not used for outbound gateway calls by this wrapper +- `KAGENT_NAME` - Agent name +- `KAGENT_NAMESPACE` - Agent namespace +- `OPENAI_API_KEY` - OpenAI API key +- `OPENAI_API_BASE` - Optional OpenAI-compatible API base URL - `LOG_LEVEL` - Logging level (default: INFO) --- @@ -141,15 +126,14 @@ Set `KAGENT_API_URL` and `KAGENT_GATEWAY_URL` to connect to kagent. See `samples/openai/` for complete examples: - `basic_agent/` - Simple agent with custom tools -- More examples coming soon --- ## See Also -- [OpenAI Agents SDK Docs](https://github.com/openai/agents) +- [OpenAI Agents SDK Docs](https://github.com/openai/openai-agents-python) - [KAgent Skills](../../kagent-skills/README.md) -- [A2A Protocol](https://docs.kagent.ai/a2a) +- [A2A Protocol](https://a2a-protocol.org/) --- diff --git a/python/samples/langgraph/currency/README.md b/python/samples/langgraph/currency/README.md index 26a8670e2e..44e6a5d529 100644 --- a/python/samples/langgraph/currency/README.md +++ b/python/samples/langgraph/currency/README.md @@ -1,88 +1,37 @@ # Currency LangGraph Agent -This is a currency LangGraph agent that demonstrates KAgent integration with session persistence via REST API. +This sample serves a currency-conversion LangGraph agent over A2A. LangGraph conversation state is checkpointed to a local SQLite file. ## Features -- Currency conversion agent using OpenAI -- LangGraph state management with KAgent checkpointer -- A2A protocol compatibility -- Session persistence via KAgent REST API +- Currency conversion using OpenAI and the Frankfurter API +- LangGraph state checkpointing with `SqliteSaver` +- A2A protocol support - Streaming responses -## Quick Start +## Deployment -1. Build the agent image: - -Run the basic-langchain-sample target from the top-level Python directory. - -```bash -make basic-langchain-sample -``` - -2. Push to local registry (if using one): - -```bash -docker push localhost:5001/langgraph-currency:latest -``` - -3. Create a secret with the OpenAI API key: - -```bash -kubectl create secret generic kagent-openai -n kagent \ - --from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \ - --dry-run=client -o yaml | kubectl apply -f - -``` - -4. Run the image through a BYO `Harness` and matching `AgentTemplate`; see the - API v2 examples and E2E fixtures for the current resource shape. - -## Local Development - -1. Install dependencies: - -```bash -uv sync -``` - -2. Set environment variables: - -```bash -export OPENAI_API_KEY=your_api_key_here -export KAGENT_API_URL=http://localhost:8083 -export KAGENT_GATEWAY_URL=http://localhost:8083 -``` - -3. Run the agent server: - -```bash -uv run currency -``` - -4. Test the agent: - -```bash -uv run currency test -``` +The repository validates the packaged module import, ASGI application construction, and `GET /health` response. It does not validate the `main()` process lifecycle, port binding, container startup, OpenAI-backed execution, A2A requests, or checkpoint reuse after restart. This sample therefore has no documented end-to-end runtime command yet. ## Architecture This agent demonstrates: -- **StateGraph**: Simple conversation flow with one node -- **SqliteSaver**: Stores conversation state in a local SQLite file -- **A2A Integration**: Compatible with KAgent's agent-to-agent protocol -- **Streaming**: Real-time response streaming via A2A events +- **StateGraph**: A ReAct conversation graph with a currency tool +- **SqliteSaver**: Stores LangGraph conversation state in a local SQLite file +- **A2A Integration**: Serves the graph through KAgent's A2A application wrapper +- **Streaming**: Emits graph execution updates as A2A events -The agent stores conversation history in `KAGENT_CHECKPOINT_DB` (default: `/tmp/currency-checkpoints.sqlite`). Mount a persistent volume and point the variable there for persistence across pod replacement. +The agent stores LangGraph checkpoints in `KAGENT_CHECKPOINT_DB` (default: `/tmp/currency-checkpoints.sqlite`). Mount a persistent volume and point the variable there to retain checkpoints across pod replacement. A2A task tracking inside the agent process remains in memory. ## Configuration -The agent can be configured via environment variables: - - `OPENAI_API_KEY`: Required for OpenAI API access -- `KAGENT_API_URL`: Required. KAgent control-plane API URL; locally, `http://localhost:8083` -- `KAGENT_GATEWAY_URL`: Required. KAgent A2A and MCP gateway URL; locally, `http://localhost:8083` +- `KAGENT_API_URL`: Required by `KAgentConfig`; not used for outbound control-plane calls by this wrapper +- `KAGENT_GATEWAY_URL`: Required by `KAgentConfig`; not used for outbound gateway calls by this wrapper +- `KAGENT_NAME`: Required agent name +- `KAGENT_NAMESPACE`: Required agent namespace +- `KAGENT_CHECKPOINT_DB`: SQLite checkpoint path (default: `/tmp/currency-checkpoints.sqlite`) - `PORT`: Server port (default: 8080) - `HOST`: Server host (default: 0.0.0.0) @@ -107,5 +56,6 @@ High-level options for tracing this sample: - If you create custom tools, decorate them with the LangSmith SDK's `@traceable` decorator; this sample shows it for the exchange-rate tool. References: -- LangSmith SDK: `https://github.com/langchain-ai/langsmith-sdk` -- Trace with OpenTelemetry: `https://docs.langchain.com/langsmith/trace-with-opentelemetry` + +- LangSmith SDK: https://github.com/langchain-ai/langsmith-sdk +- Trace with OpenTelemetry: https://docs.langchain.com/langsmith/trace-with-opentelemetry