{"id":18238223,"url":"https://github.com/humanlayer/kubechain","last_synced_at":"2025-04-04T06:32:44.877Z","repository":{"id":258471384,"uuid":"873985503","full_name":"humanlayer/kubechain","owner":"humanlayer","description":"A distributed agent scheduler optimized for simplicity, clarity, and control. It is designed for outer-loop agents that run without supervision, and make asynchronous tool calls like requesting human feedback on key operations.","archived":false,"fork":false,"pushed_at":"2025-04-01T23:16:03.000Z","size":3646,"stargazers_count":20,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T23:20:24.848Z","etag":null,"topics":["agents","framework","human-in-the-loop","kubernetes","llms","orchestration","outer-loops"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/humanlayer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-17T04:04:29.000Z","updated_at":"2025-04-01T23:16:06.000Z","dependencies_parsed_at":"2025-03-24T16:48:59.085Z","dependency_job_id":null,"html_url":"https://github.com/humanlayer/kubechain","commit_stats":null,"previous_names":["humanlayer/smallchain","humanlayer/kubechain"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanlayer%2Fkubechain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanlayer%2Fkubechain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanlayer%2Fkubechain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/humanlayer%2Fkubechain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/humanlayer","download_url":"https://codeload.github.com/humanlayer/kubechain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247134992,"owners_count":20889412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","framework","human-in-the-loop","kubernetes","llms","orchestration","outer-loops"],"created_at":"2024-11-05T03:04:26.893Z","updated_at":"2025-04-04T06:32:39.868Z","avatar_url":"https://github.com/humanlayer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003eSmallchain\u003c/h1\u003e\n\n\u003c/div\u003e\n\nSmallchain is a cloud-native orchestrator for Autonomous AI Agents. It supports long-lived outer-loop agents that can process asynchronous execution of both LLM inference and long-running tool calls. \n\n\n:warning: **Note** - SmallChain is highly experimental and has several known issues and race conditions. Use at your own risk.\n \n\u003cdiv align=\"center\"\u003e\n\n\u003ch3\u003e\n\n[Deep Dive](./smallchain.md) | [Discord](https://discord.gg/AK6bWGFY7d) | [Documentation](./docs) | [Examples](./examples)\n\n\u003c/h3\u003e\n\n[![GitHub Repo stars](https://img.shields.io/github/stars/humanlayer/smallchain)](https://github.com/humanlayer/smallchain)\n[![License: Apache-2](https://img.shields.io/badge/License-Apache-green.svg)](https://opensource.org/licenses/Apache-2)\n\n\u003c/div\u003e\n\n## Table of contents\n\n- [Getting Started](#getting-started)\n- [Why Smallchain?](#why-smallchain)\n- [Key Features](#key-features)\n- [Examples](#examples)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Getting Started\n\nTo get started, check out [Getting Started](./docs/getting-started.md), or jump straight into one of the [Examples](./examples/)\n\n## Design Principles\n\n- *Clarity* - it should be easy to understand what's happening, what the framework is doing with my prompts.\n- *Control* - it should be possible to do anything w/ SmallChain that you can do taking the reins yourself. SmallChain MUST NOT recreate the common \"i can't use this because I can't customize XYZ prompt scenario\" problem.\n- *Modularity* - SmallChain is composed of small control loops with a limited scope that each progress the state of the world.\n- *Durability* - SmallChain is a distributed system and should be resilient to faliures.\n- *Simplicity* - AI applications built on a chat completions API have the UNPRECEDENTEND benefit that the entire state of a workflow, the entire \"call stack\", can be expressed as the rolling context window accumulated through interactions and tool calls. Leverage this to cut corners\n\nStretch goals / future\n\n- *Extensible* - it should be easy to build and share agents, tools, and tasks\n- *Hackable* - it should be straightforward to unhook from the chat completions API and do whatever folks want WRT prompt / special tokens / context management \n\n## Example\n\n\u003cdetails\u003e\n\u003csummary\u003eComing Soon\u003c/summary\u003e\n\nCreate `smallchain.yaml`:\n\n```yaml\nllms:\n  - name: \"gpt-4o\n    provider: openai\n    model: gpt-4o\n    parameters:\n      temperature: 0.0\n\nagents:\n  - name: \"assistant\"\n    system_prompt: \"your goal is to assist the human with their tasks\"\n    llm: \"gpt-4o\"\n    tools:\n      - agent: \"calculator_operator\"\n  - name: calculator_operator\n    system_prompt: \"you are a skilled calculator operator\"\n    tools:\n      - add\n      # - subtract\n      # - multiply\n      # - divide\n\ntools:\n  - name: add\n    builtin: add\n\n  - name: subtract\n    description: \"subtract two numbers\"\n    parameters:\n      type: object\n      properties:\n        a:\n          type: number\n          description: \"The first number\"\n        b:\n          type: number\n          description: \"The second number\"\n    executor:\n      python: # or docker, local_nodejs, local_bash, etc.\n        image: \"python:3.12\"\n        command: |\n          python -c \"print(a - b)\"\n        requirements: []\n    \ntasks:\n  - name: \"do_some_math\"\n    user_message: \"add (3 + 4) and (5 + 3) and add the results\"\n    agent: assistant\n\nruns:\n  - name: \"my first run\"\n    task: do_some_math\n```\n\n\n\n```shell\nbrew install humanlayer/smallchain/smallchain\n```\n\n```shell\nsmallchain apply -f smallchain.yaml\n```\n\n```shell\nsmallchain get events --pretty\n```\n\n```text\n[2024-07-28 12:00:00] [INFO] Starting Smallchain\n[2024-07-28 12:00:05] [INFO] Executing task: determine the current weather in tokyo\n[2024-07-28 12:00:07] [INFO] Agent 'assistant' is executing the task\n[2024-07-28 12:00:10] [INFO] Agent 'assistant' is using tool: get_current_weather\n[2024-07-28 12:00:12] [INFO] Tool 'get_current_weather' executed successfully\n[2024-07-28 12:00:13] [INFO] Agent 'assistant' has completed the task\n[2024-07-28 12:00:14] [INFO] Task completed: determine the current weather in tokyo\n[2024-07-28 12:00:15] [INFO] Output: The current temperature in Tokyo is 75°F (24°C)\n[2024-07-28 12:00:16] [INFO] Run 'my first run' completed successfully\n```\n\nYou can query the state of the workflow as the agent runs\n\n```shell\nsmallchain get runs\n```\n\n```text\nRUN                 NAME                STATUS    TASK ID             DEPTH\nmy first run        assistant           Running    do_some_math       0\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSome draft-y mermaid docs\u003c/summary\u003e\n\n```mermaid\nflowchart TD;\n    MC[Manager Chain];\n    style MC fill:#FFB0B5\n    MC --\u003eMCSM(System Message - list of agents to delegate to)\n    style MCSM fill:#FFF\n    MCSM --\u003e MCUM(User Message: Create a Blog Post and promote it on linkedin, twitter, and slack)\n    style MCUM fill:#FFF\n    MCUM --\u003eMCLLM(LLM CALL)\n    MCLLM --\u003eMCTC(Async Tool Call: Delegate to Planner Chain)\n    style MCTC fill:#FFF\n    subgraph Planner\n      PCSM\n      PCUM\n      PCLLM\n      PCFA\n    end\n    MCTC --\u003e|launch| Planner;\n    MCTC --\u003eCP1[checkpoint]\n    style CP1 fill:#88ffbb \n    PCSM(System Message)\n    style PCSM fill:#FFF\n    PCSM --\u003e PCUM(User Message)\n    style PCUM fill:#FFF\n    PCUM --\u003e PCLLM(LLM CALL)\n    PCLLM --\u003e PCFA(Final Answer: Plan)\n    style PCFA fill:#FFF \n    MCTCR(Tool Call Response)\n    PCFA --\u003e|callback| MCTCR\n    style MCTCR fill:#FFF\n    R1[resume]\n    style R1 fill:#88ffbb \n    MCTCR --\u003eR1\n    MCTC --\u003e MCTCR\n    CP1 --\u003e R1\n    MCLLM o--o CP1\n    R1 --\u003e MCLLM2[LLM CALL]\n    MCLLM2 --\u003e MCTC2[Async Tool Call: Delegate to Researcher Agent]\n    style MCTC2 fill:#FFF\n    subgraph Researcher\n      RASM\n      RUM\n      RLLM\n      RLLM2\n      RLLM3\n      RTC1\n      RTC1X\n      RTCR1\n      RTC2\n      RTC2X\n      RTCR2\n      RFA\n    end\n    MCTC2 --\u003e|launch| Researcher;\n    CP2[checkpoint]\n    style CP2 fill:#88ffbb \n    MCTC2 --\u003e CP2\n    MCLLM2 o--o CP2\n    RASM[System Message]\n    style RASM fill:#FFF\n    RASM --\u003e RUM[User Message]\n    style RUM fill:#FFF\n    RUM --\u003e RLLM[LLM CALL]\n    RLLM --\u003e RTC1[Sync Tool Call: Search Serper]\n    style RTC1 fill:#FFF\n    RTC1 --\u003e RTCR1(Tool Call Response)\n    RTC1 --\u003e RTC1X(Serper API Call)\n    RTC1X --\u003e RTCR1\n    style RTCR1 fill:#FFF\n    RTCR1 --\u003e RLLM2[LLM CALL]\n    RLLM2 --\u003e RTC2[Sync Tool Call: Search Wikipedia]\n    style RTC2 fill:#FFF\n    RTC2 --\u003e RTCR2(Tool Call Response)\n    RTC2 --\u003e RTC2X(Wikipedia API Call)\n    RTC2X --\u003e RTCR2\n    style RTCR2 fill:#FFF\n    RTCR2 --\u003e RLLM3[LLM CALL]\n    RLLM3 --\u003e RFA[Final Answer: Research]\n    style RFA fill:#FFF\n    MCTCR2(Tool Call Response)\n    style MCTCR2 fill:#FFF\n    RFA --\u003e|callback| MCTCR2\n    R2[resume]\n    style R2 fill:#88ffbb \n    MCTCR2 --\u003e R2\n    MCTC2 --\u003e MCTCR2\n    CP2 --\u003e R2\n```\n\n```mermaid\nflowchart TD;\n    C --\u003e D(System Message);\n    C --\u003e E(User Message: Make a plan);\n    C --\u003e F(LLM CALL);\n\n    F --\u003e G[Final output: plan];\n    G --\u003e H(resume);\n    \n    H --\u003e I(LLM CALL);\n    I --\u003e|launch| J[Researcher Agent];\n    J --\u003e K(System Message);\n    J --\u003e L(User Message: Research topic for blog post);\n    J --\u003e M(LLM CALL);\n    \n    M --\u003e|launch| N[Tool: Search Serper];\n    N --\u003e O(Tool response);\n    O --\u003e P(LLM CALL);\n    \n    P --\u003e|launch| Q[Tool: Search Wikipedia];\n    Q --\u003e R(Tool response);\n    R --\u003e S(LLM CALL);\n    \n    S --\u003e T[Final output: summary of recent AI news];\n    T --\u003e U(resume);\n    \n    U --\u003e V(LLM CALL);\n    V --\u003e|launch| W[Writer Agent];\n    W --\u003e X(System Message);\n    W --\u003e Y(User Message: Write blog post using research);\n    W --\u003e Z(LLM CALL);\n    \n    Z --\u003e AA[Final output: great article on recent AI news];\n    AA --\u003e AB(resume);\n    \n    AB --\u003e AC(LLM CALL);\n    AC --\u003e|launch| AD[Publisher Agent];\n    AD --\u003e AE(System Message);\n    AD --\u003e AF(User Message: Review blog post and get feedback from humans);\n    AD --\u003e AG(LLM CALL);\n    \n    AG --\u003e|launch| AH[Tool: Contact Head of Marketing in Slack];\n    AG --\u003e|launch| AI[Tool: Contact Engineering SME in Slack];\n    AG --\u003e|launch| AJ[Tool: Email to CEO for review/feedback];\n    \n    AH --\u003e AK(Tool Response);\n    AI --\u003e AK;\n    AJ --\u003e AK;\n    \n    AK --\u003e|several minutes later| AL[Tool responses];\n    AL --\u003e AM[Checkpoint];\n    \n    AM --\u003e|several days later| AN[Tool Response];\n    AN --\u003e AO(resume);\n    \n    AO --\u003e AP(LLM CALL);\n    AP --\u003e|launch| AQ[Tool: Publish Post];\n    AQ --\u003e AR(Tool Response);\n    AR --\u003e AS(resume);\n    \n    AS --\u003e AT(LLM CALL);\n    AT --\u003e|launch| AU(Twitter Agent);\n    AT --\u003e|launch| AV(LinkedIn Agent);\n    \n    AU --\u003e AW(System Message: Write a Tweet Promoting the Post);\n    AV --\u003e AX(System Message: Write LinkedIn Post Promoting the Post);\n    \n    AW --\u003e AY(Tool response);\n    AX --\u003e AY;\n    \n    AY --\u003e AZ(Checkpoint);\n    AZ --\u003e BA(LLM CALL);\n    \n    BA --\u003e BB[Final output: post was published and promoted];\n    BB --\u003e BC(resume);\n    \n    BC --\u003e BD(LLM CALL);\n    BD --\u003e|launch| BE[Slack Internal Promo Agent];\n    \n    BE --\u003e BF(System Message: Send Slack message to announce the post);\n    BF --\u003e|...| BG;\n    \n    BG --\u003e BH(LLM CALL);\n    BH --\u003e BI[Final output: post was published and promoted];\n```\n\n\u003c/details\u003e\n\n\n## Why SmallChain?\n\nSmallChain is built to empower the next generation of AI agents - Autonomous Agents, but it's just a piece of the puzzle. To clarify \"next generation\", we can summarize briefly the history of LLM applications.\n\n- **Gen 1**: Chat - human-initiated question / response interface\n- **Gen 2**: Agentic Assistants - frameworks drive prompt routing, tool calling, chain of thought, and context window management to get much more reliability and functionality. Most workflows are initiated by humans in single-shot \"here's a task, go do it\" or rolling chat interfaces.\n- **Gen 3**: Autonomous Agents - no longer human initiated, agents will live in the \"outer loop\" driving toward their goals using various tools and functions. Human/Agent communication is Agent-initiated rather than human-initiated.\n\n![gen2 vs gen 3 agents](./docs/images/gen-2-gen-3-agents.png)\n\n\n### On Human Collaboration\n\nGen 3 autonomous agents will need ways to consult humans for input on various tasks. In order for these agents to perform actual useful work, they'll to do long-running things like communicate with humans and wait for a response. [HumanLayer](https://github.com/humanlayer/humanlayer) is a general-purpose framework for incorporating human feedback and approvals into agentic workflows.\n\n## Key Features\n\n- **Durable Agent Execution**: SmallChain implements something like async/await at the infrastructure layer, checkpointing a conversation chain whenever a tool call or agent delegation occurs, with the ability to resume from that checkpoint when the operation completes\n- **Dynamic Workflow Planning**: Allow agents to reprioritize and replan their workflows mid-execution\n- **Simple + Observable Control Loop Architecture**: SmallChain uses a simple, observable control loop architecture that allows for easy debugging and observability into agent execution.\n- **Human Approvals and Input**: Support for durable task execution across long-running function calls means a simple tool-based interface to allow an agent to ask a human for input or wait for an approval\n- **Self-Managing Agents**: Built in tools for agents to manage and budget their own spend and usage, like `check_current_spend_since()` and `sleep_until()`. Give agents an hourly or daily budget for work, and let them prioritize their own work or decide when to take a break. Or, configure hard limits on spend or time to prevent runaway agents.\n\n\n## Roadmap\n\n| Feature                                | Status              |\n|----------------------------------------|---------------------|\n| Local SQLite Runtime                   | 🚧 Alpha            |\n| Tool Calling Support                   | 🚧 Work in progress |\n| Configurable LLMs                      | 🚧 Work in progress |\n| External Callbacks for Tool Calls      | 🗓️ Planned          |\n| Kubernetes Runtime                     | 🗓️ Planned          |\n\n## Contributing\n\nSmallChain is open-source and we welcome contributions in the form of issues, documentation, pull requests, and more. See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.\n\n[![Star History Chart](https://api.star-history.com/svg?repos=humanlayer/smallchain\u0026type=Date)](https://star-history.com/#humanlayer/smallchain\u0026Date)\n\n\n## License\n\nSmallChain is licensed under the Apache 2 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanlayer%2Fkubechain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumanlayer%2Fkubechain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanlayer%2Fkubechain/lists"}