CKnot is a cutting-edge agentic workflow orchestration framework built with Python, LangGraph, and FastAPI. Inspired by the intricate and interconnected nature of a Chinese Knot, the project coordinates multiple specialized agents under a central "Boss" orchestrator to handle complex system debugging and general assistance tasks.
- Hierarchical Multi-Agent System: A central "Boss Agent" (
cknot) delegates tasks to specialized agents like theDeep Search,Log ParserandCode Fixer. - Interactive Rich CLI: A professional terminal interface featuring Markdown rendering, live status spinners, and a hierarchical slash-command registry (
/llms,/agents,/status, etc.). - Persistent State Management: Full conversation persistence using Redis-backed LangGraph checkpointing, allowing workflows to survive restarts and handle human-in-the-loop interruptions.
- Dynamic LLM Service Registry: Register, enable, and switch between multiple LLM providers (OpenAI, local vLLM, etc.) at runtime without code changes.
- Production-Grade Logging: Sophisticated logging featuring sensitive data redaction (API keys/passwords) and dynamic routing of logs to user-specific files.
- Telemetry & Cost Tracking: Built-in tracking of token consumption and estimated costs per agent turn.
- Modern Tooling: Powered by
uvfor lightning-fast dependency management and containerized with Docker/Podman support.
- Docker or Podman
uv(recommended for local development)
-
Initialize the project:
./bootstrap.sh init
-
Configure environment: Update the
.envfile in the root with your LLM provider details and Redis configuration. -
Build and start the API server:
./bootstrap.sh build ./bootstrap.sh start
-
Tests inside container:
./bootstrap.sh tests
-
Enter the Interactive CLI: Agent plugin "plugins/agent/ArticleWriterAgent.py" registed automatically
./bootstrap.sh cli
The interactive CLI supports a hierarchical command system. Type /help inside the CLI turn to see all available options:
____ _ __ _ _ ___ _____
/ ___| |/ /| \ | |/ _ \_ _|
| | | ' / | \| | | | || |
| |___| . \ | |\ | |_| || |
\____|_|\_\|_| \_|\___/ |_|
version 0.0.1-alpha
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
cknot Interactive CLI (Session: cli_session_1780502068)
Type /exit or /quit to end the session.
> /llms
Registered LLM Services
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ ID ┃ Provider ┃ Type ┃ Model ┃ Status ┃ Valid ┃ Usage (In/Out) ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ default-embedding │ ollama │ embedding │ all-minilm │ ENABLED │ ✔ │ 0 / 0 │
│ local-vllm │ vllm │ chat │ Qwen/Qwen3-0.6B │ ENABLED │ ✔ │ 0 / 0 │
│ default-llm │ ollama │ chat │ my-qwen-3.6:latest │ ENABLED │ ✔ │ 0 / 0 │
└───────────────────┴──────────┴───────────┴────────────────────┴─────────┴───────┴────────────────┘
> /agents
Agent Registry
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Agent ID ┃ Expert At ┃ Avoid For ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ ArticleWriterAgent │ article paper or context summarization and │ code debugging, system log analysis, real-time │
│ │ writing, context summarize, article summarize, │ chat support │
│ │ context writing, article writing, long-form │ │
│ │ content, detailed outlines, editorial review, │ │
│ │ saving articles to local files │ │
│ cknot │ │ │
│ DeepSearchAgent │ deep internet research, web searching, latest │ local file access, private database analysis, │
│ │ news, public data │ code execution │
│ LogParserAgent │ log analysis, root cause identification, DevOps │ writing code, web search, user interaction │
│ │ debugging, container logs │ │
│ CodeFixerAgent │ code fixing, patching, software engineering, │ log parsing, web search, internet research │
│ │ refactoring │ │
└────────────────────┴──────────────────────────────────────────────────┴─────────────────────────────────────────────────┘
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
> /agents
list Lists all registered agents and their specialized capabilities.
info Shows detailed metadata for a specific agent. Usage: info <agent_id>
rm Unregisters an agent from the system. Usage: rm <agent_id>
llm Manage agent LLM assignments. Subcommands: set
- Data Privacy: The
RedactingFilterautomatically masks sensitive patterns likeapi_keyorpasswordin all system logs. - State Isolation: Conversations are isolated via
session_id, ensuring multi-tenant safety. - Health Checks: The system performs pre-flight checks on Redis and LLM providers to ensure service availability before starting workflows.
-
Access the UI: Start your API server (./bootstrap.sh start) and navigate to http://localhost:9999/docs in your browser.
-
Authorize: Click the Authorize button at the top right. Use the /token endpoint credentials to unlock protected endpoints (indicated by the lock icon).
-
Test Orchestration:
- Use the POST /chat endpoint to send a message like "Search for latest AI news".
- If the response returns requires_action: true and next_node: "deep_search", use the POST /approve/{session_id} endpoint to authorize the specialist to run.
-
Audit Infrastructure: Expand the llms, tools, and users sections to review current system configurations, check token usage, or manage user profiles.