feat(samples): add multitenant-agent-k8s auto-agent — BYO LangGraph ReAct agent with HITL

Author: v.chetvertukhin

python/pyproject.toml

@@ -1,5 +1,5 @@
 [tool.uv.workspace]
-members = ["packages/*", "samples/adk/*", "samples/langgraph/*", "samples/crewai/*", "samples/openai/*"]
+members = ["packages/*", "samples/adk/*", "samples/langgraph/*", "samples/crewai/*", "samples/openai/*", "samples/multitenant-agent-k8s/*"]
 
 [dependency-groups]
 dev = [

python/samples/multitenant-agent-k8s/auto-agent/README.md

@@ -0,0 +1,26 @@
+# Auto Agent — Phase 0.9
+
+Autonomous AI assistant with dynamic tool discovery via tool-registry.
+
+## Features
+
+- **ReAct loop** — Think → ListTools → CallTool → repeat
+- **Dynamic tools** — discovers available tools at runtime from tool-registry
+- **HITL** — pauses before destructive actions, asks user via Telegram
+- **Memory** — multi-turn via KAgentCheckpointer (PostgreSQL)
+- **Org-scoped** — only sees tools registered for its tenant+org
+
+## Env vars
+
+| Var | Default | Description |
+|-----|---------|-------------|
+| `TENANT_ID` | `unknown` | Tenant identifier |
+| `ORG_ID` | `unknown` | Organisation identifier |
+| `ORG_NAME` | derived | Human-readable org name |
+| `TOOL_REGISTRY_URL` | `http://tool-registry.platform.svc.cluster.local:8080` | Registry URL |
+| `REGISTRY_TOKEN` | — | Bearer token (from K8s Secret) |
+| `KAGENT_URL` | `http://kagent-controller.kagent.svc.cluster.local:8083` | For call_agent |
+| `OPENAI_API_KEY` | — | Required |
+| `OPENAI_MODEL` | `gpt-4o-mini` | Model name |
+| `OPENAI_BASE_URL` | — | Custom provider (e.g. BotHub) |
+| `DATABASE_URL` | — | PostgreSQL for KAgentCheckpointer |

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/__init__.py

@@ -0,0 +1 @@
+"""auto-agent package."""

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/agent-card.json

@@ -0,0 +1,21 @@
+{
+  "name": "auto-agent",
+  "description": "Autonomous AI assistant with dynamic tool discovery. Can list and call any registered tool, ask for human confirmation before destructive actions, and delegate to other agents.",
+  "url": "http://localhost:8080",
+  "version": "0.9.0",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": false,
+    "stateTransitionHistory": false
+  },
+  "defaultInputModes": ["text"],
+  "defaultOutputModes": ["text"],
+  "skills": [
+    {
+      "id": "autonomous-assistant",
+      "name": "Autonomous Assistant",
+      "description": "General-purpose autonomous assistant. Discovers and uses available tools dynamically. Asks for confirmation before destructive actions.",
+      "tags": ["autonomous", "dynamic-tools", "hitl"]
+    }
+  ]
+}

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/agent.py

@@ -0,0 +1,87 @@
+"""Auto Agent — Phase 0.9 BYO LangGraph autonomous agent.
+
+ReAct loop with dynamic tool discovery:
+  1. think        — scratch pad for planning
+  2. list_tools   — discover available tools from tool-registry
+  3. call_tool    — execute any tool by name (scope-checked via registry)
+  4. ask_human    — HITL: pause before destructive actions
+  5. call_agent   — A2A delegation to other agents
+
+Memory: KAgentCheckpointer → PostgreSQL (per context_id / thread_id).
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+import httpx
+from kagent.core import KAgentConfig
+from kagent.langgraph import KAgentCheckpointer
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+from auto_agent.tools import (
+    ask_human,
+    call_agent,
+    call_tool,
+    list_available_tools,
+    think,
+)
+
+log = logging.getLogger(__name__)
+
+# ── Tenant identity ───────────────────────────────────────────────────────────
+TENANT_ID = os.getenv("TENANT_ID", "unknown")
+ORG_ID = os.getenv("ORG_ID", "unknown")
+ORG_NAME = os.getenv("ORG_NAME", ORG_ID.replace("-", " ").title())
+
+# ── System prompt ─────────────────────────────────────────────────────────────
+SYSTEM_PROMPT = f"""You are an autonomous AI assistant for **{ORG_NAME}** \
+(tenant: {TENANT_ID}, org: {ORG_ID}).
+
+## Workflow — always follow this order:
+
+1. **think** — plan complex multi-step tasks before acting
+2. **list_available_tools** — discover what tools you can use
+3. **ask_human** — REQUIRED before ANY create / update / delete action
+4. **call_tool** — execute the tool with correct arguments
+5. On errors: retry once with corrected args, then ask_human if still failing
+
+## Rules:
+
+- NEVER guess tool names — always call list_available_tools first
+- NEVER perform destructive actions without ask_human confirmation
+- NEVER fabricate tool results — only report what tools actually return
+- Respond in the same language the user wrote in
+- Keep responses concise — no markdown headers in final answer
+
+## Memory:
+
+You remember previous messages in this conversation via thread_id.
+If the user refers to "earlier" or "before" — use that context.
+"""
+
+# ── LLM ───────────────────────────────────────────────────────────────────────
+_model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+_base_url = os.getenv("OPENAI_BASE_URL")
+
+_llm_kwargs: dict = {"model": _model, "temperature": 0}
+if _base_url:
+    _llm_kwargs["base_url"] = _base_url
+
+log.info("LLM: model=%s base_url=%s", _model, _base_url or "(default openai)")
+
+# ── KAgent memory ─────────────────────────────────────────────────────────────
+_kagent_config = KAgentConfig()
+kagent_checkpointer = KAgentCheckpointer(
+    client=httpx.AsyncClient(base_url=_kagent_config.url),
+    app_name=_kagent_config.app_name,
+)
+
+# ── Graph ─────────────────────────────────────────────────────────────────────
+graph = create_react_agent(
+    model=ChatOpenAI(**_llm_kwargs),
+    tools=[think, list_available_tools, call_tool, ask_human, call_agent],
+    checkpointer=kagent_checkpointer,
+    prompt=SYSTEM_PROMPT,
+)

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/cli.py

@@ -0,0 +1,41 @@
+"""CLI entry point for auto-agent."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+
+import uvicorn
+from auto_agent.agent import graph
+from kagent.core import KAgentConfig
+from kagent.langgraph import KAgentApp
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+log = logging.getLogger(__name__)
+
+AGENT_CARD_PATH = os.path.join(os.path.dirname(__file__), "agent-card.json")
+
+
+def main() -> None:
+    with open(AGENT_CARD_PATH) as f:
+        agent_card = json.load(f)
+
+    config = KAgentConfig()
+    app = KAgentApp(graph=graph, agent_card=agent_card, config=config, tracing=False)
+
+    port = int(os.getenv("PORT", "8080"))
+    host = os.getenv("HOST", "0.0.0.0")
+    log.info(
+        "Starting auto-agent on %s:%s  tenant=%s org=%s",
+        host, port,
+        os.getenv("TENANT_ID", "?"),
+        os.getenv("ORG_ID", "?"),
+    )
+    uvicorn.run(app.build(), host=host, port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/registry_client.py

@@ -0,0 +1,117 @@
+"""HTTP client for tool-registry service.
+
+GET  /tools?tenant_id=X&org_id=Y  → list[ToolInfo]   (with TTL cache)
+POST /call/{name}                  → dict              (with timeout)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+TOOL_REGISTRY_URL = os.getenv(
+    "TOOL_REGISTRY_URL",
+    "http://tool-registry.platform.svc.cluster.local:8080",
+)
+REGISTRY_TOKEN = os.getenv("REGISTRY_TOKEN", "")
+CALL_TIMEOUT = 30  # seconds
+_CACHE_TTL = 60  # seconds
+
+
+@dataclass
+class ToolInfo:
+    name: str
+    description: str
+    input_schema: dict
+    endpoint_url: str
+    tenant_id: str | None
+    org_id: str | None
+    scopes: list[str] = field(default_factory=list)
+    version: str = "v1"
+
+
+# ── in-process cache ─────────────────────────────────────────────────────────
+_cache: dict[str, tuple[list[ToolInfo], float]] = {}  # key → (data, timestamp)
+_cache_lock = asyncio.Lock()
+
+
+def _cache_key(tenant_id: str, org_id: str) -> str:
+    return f"{tenant_id}:{org_id}"
+
+
+async def get_tools(tenant_id: str, org_id: str) -> list[ToolInfo]:
+    """Return tools available for tenant+org. TTL-cached for 60 s."""
+    key = _cache_key(tenant_id, org_id)
+
+    async with _cache_lock:
+        cached = _cache.get(key)
+        if cached and time.monotonic() - cached[1] < _CACHE_TTL:
+            return cached[0]
+
+    headers = {"Authorization": f"Bearer {REGISTRY_TOKEN}"} if REGISTRY_TOKEN else {}
+    try:
+        async with httpx.AsyncClient(timeout=10, headers=headers) as client:
+            r = await client.get(
+                f"{TOOL_REGISTRY_URL}/tools",
+                params={"tenant_id": tenant_id, "org_id": org_id},
+            )
+            r.raise_for_status()
+            data = r.json()
+    except Exception as exc:
+        log.warning("registry_client.get_tools failed: %s", exc)
+        # Return stale cache on error rather than failing the agent
+        async with _cache_lock:
+            stale = _cache.get(key)
+            if stale:
+                log.warning("Returning stale tool list for %s", key)
+                return stale[0]
+        return []
+
+    tools = [ToolInfo(**item) for item in data]
+    async with _cache_lock:
+        _cache[key] = (tools, time.monotonic())
+
+    return tools
+
+
+async def call_tool(
+    tool_name: str,
+    arguments: dict,
+    tenant_id: str,
+    org_id: str,
+) -> dict:
+    """Proxy a tool call through tool-registry with scope check + timeout."""
+    headers = {"Authorization": f"Bearer {REGISTRY_TOKEN}"} if REGISTRY_TOKEN else {}
+    payload = {"arguments": arguments, "org_id": org_id}
+
+    try:
+        async with httpx.AsyncClient(
+            timeout=CALL_TIMEOUT, headers=headers
+        ) as client:
+            r = await client.post(
+                f"{TOOL_REGISTRY_URL}/call/{tool_name}",
+                json=payload,
+            )
+            if r.status_code == 403:
+                return {"error": f"Tool '{tool_name}' not available for org '{org_id}'"}
+            r.raise_for_status()
+            return r.json()
+    except httpx.TimeoutException:
+        return {"error": f"Tool '{tool_name}' timed out after {CALL_TIMEOUT}s"}
+    except Exception as exc:
+        log.error("registry_client.call_tool(%s) failed: %s", tool_name, exc)
+        return {"error": str(exc)}
+
+
+def invalidate_cache(tenant_id: str = "", org_id: str = "") -> None:
+    """Force cache refresh on next call. Pass empty strings to clear all."""
+    if tenant_id or org_id:
+        _cache.pop(_cache_key(tenant_id, org_id), None)
+    else:
+        _cache.clear()

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/tools/__init__.py

@@ -0,0 +1,13 @@
+from auto_agent.tools.think import think
+from auto_agent.tools.list_tools import list_available_tools
+from auto_agent.tools.call_tool import call_tool
+from auto_agent.tools.ask_human import ask_human
+from auto_agent.tools.call_agent import call_agent
+
+__all__ = [
+    "think",
+    "list_available_tools",
+    "call_tool",
+    "ask_human",
+    "call_agent",
+]

python/samples/multitenant-agent-k8s/auto-agent/auto_agent/tools/ask_human.py

@@ -0,0 +1,71 @@
+"""AskHumanTool — Human-in-the-Loop via LangGraph interrupt.
+
+Pauses the graph and waits for human input.
+Use before ANY create / update / delete action.
+
+Flow:
+1. Agent calls ask_human(question, options)
+2. interrupt() fires with kagent action_requests payload
+3. kagent executor emits input_required + adk_request_confirmation DataPart
+4. User approves/rejects via TG Bot or kagent UI
+5. Graph resumes with the answer
+
+Interrupt payload:
+  {"action_requests": [{"name": "ask_human", "args": {question, options}, "id": "<uuid>"}]}
+
+Resume value:
+  {"decision_type": "approve"|"reject", "ask_user_answers": [{"answer": ["<text>"]}]}
+"""
+from __future__ import annotations
+
+import uuid
+
+from langchain_core.tools import tool
+from langgraph.types import interrupt
+
+
+@tool
+def ask_human(question: str, options: list[str] | None = None) -> str:
+    """Ask the user a question and wait for their answer before continuing.
+
+    ALWAYS call this before any action that creates, updates, or deletes data.
+
+    Args:
+        question: what you are about to do and why
+        options:  suggested responses (e.g. ["Да", "Нет"]). None = free-form.
+
+    Returns:
+        The human's answer, or "rejected" if the user denied.
+    """
+    # kagent executor requires action_requests format to emit input_required.
+    payload = {
+        "action_requests": [
+            {
+                "name": "ask_human",
+                "args": {"question": question, "options": options or []},
+                "id": str(uuid.uuid4()),
+            }
+        ]
+    }
+
+    resume_value = interrupt(payload)
+
+    if isinstance(resume_value, dict):
+        decision = resume_value.get("decision_type", "approve")
+
+        if decision == "reject":
+            reasons = resume_value.get("rejection_reasons", {})
+            reason = reasons.get("*", "") if isinstance(reasons, dict) else ""
+            return f"rejected: {reason}" if reason else "rejected"
+
+        # approve — extract text from ask_user_answers[0]["answer"][0]
+        answers = resume_value.get("ask_user_answers", [])
+        if answers and isinstance(answers, list):
+            first = answers[0]
+            if isinstance(first, dict):
+                answer_list = first.get("answer", [])
+                if answer_list and isinstance(answer_list, list):
+                    return str(answer_list[0])
+
+    # resume_value is a plain string (e.g. in tests)
+    return str(resume_value)