{"id":35495552,"url":"https://github.com/barun-saha/kodeagent","last_synced_at":"2026-04-26T17:02:11.395Z","repository":{"id":291401793,"uuid":"973598056","full_name":"barun-saha/kodeagent","owner":"barun-saha","description":"The minimal AI agent engine","archived":false,"fork":false,"pushed_at":"2026-04-26T10:11:23.000Z","size":4907,"stargazers_count":40,"open_issues_count":24,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-26T12:12:18.729Z","etag":null,"topics":["agent","agentic-ai","agentic-framework","ai","ai-agents","azure-openai","codeagent","e2b","gemini-api","lightweight","litellm","llm","ollama","planning","python","react-agent"],"latest_commit_sha":null,"homepage":"https://kodeagent.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barun-saha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-27T10:36:40.000Z","updated_at":"2026-04-26T10:11:27.000Z","dependencies_parsed_at":"2025-12-12T21:00:26.328Z","dependency_job_id":null,"html_url":"https://github.com/barun-saha/kodeagent","commit_stats":null,"previous_names":["barun-saha/kodeagent"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/barun-saha/kodeagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barun-saha%2Fkodeagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barun-saha%2Fkodeagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barun-saha%2Fkodeagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barun-saha%2Fkodeagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barun-saha","download_url":"https://codeload.github.com/barun-saha/kodeagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barun-saha%2Fkodeagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32305040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["agent","agentic-ai","agentic-framework","ai","ai-agents","azure-openai","codeagent","e2b","gemini-api","lightweight","litellm","llm","ollama","planning","python","react-agent"],"created_at":"2026-01-03T17:13:52.304Z","updated_at":"2026-04-26T17:02:11.389Z","avatar_url":"https://github.com/barun-saha.png","language":"Python","funding_links":[],"categories":["Frameworks","Applications","🌟 Core Frameworks"],"sub_categories":["Autonomous Agent Task Solver Projects"],"readme":"![KodeAgent](https://raw.githubusercontent.com/barun-saha/kodeagent/refs/heads/main/assets/icons/256/KodeAgent.png)\n\n# KodeAgent: The Minimal Agent Engine\n\n[![pypi](https://img.shields.io/pypi/v/kodeagent.svg)](https://pypi.org/project/kodeagent/)\n[![codecov](https://codecov.io/gh/barun-saha/kodeagent/branch/main/graph/badge.svg)](https://codecov.io/gh/barun-saha/kodeagent)\n[![Documentation Status](https://readthedocs.org/projects/kodeagent/badge/?version=latest)](https://kodeagent.readthedocs.io/en/latest/?badge=latest)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Known Vulnerabilities](https://snyk.io/test/github/barun-saha/kodeagent/badge.svg)](https://snyk.io/test/github/barun-saha/kodeagent)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/kodeagent)\n[![Ruff](https://img.shields.io/badge/linting-ruff-%23f64e60)](https://docs.astral.sh/ruff/)\n![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)\n\n\u003ca href=\"https://aiagentsdirectory.com/agent/kodeagent?utm_source=badge\u0026utm_medium=referral\u0026utm_campaign=free_listing\u0026utm_content=homepage\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n  \u003cimg src=\"https://aiagentsdirectory.com/featured-badge.svg?v=2024\" alt=\"Featured AI Agents on AI Agents Directory\" width=\"200\" height=\"50\" /\u003e\n\u003c/a\u003e\n\n\nKodeAgent is a frameworkless, minimalistic approach to building AI agents. KodeAgent is designed to be the robust reasoning core inside your larger system, not the entire platform.\n\n![KodeAgent Demo](https://raw.githubusercontent.com/barun-saha/kodeagent/refs/heads/main/assets/demo.gif)\n\n\n## ✅ Why KodeAgent?\n\nKodeAgent adheres to the **Unix Philosophy**: do one thing well and integrate seamlessly.\n\nUse KodeAgent because it offers:\n- **ReAct, CodeAct, and Function Calling:** KodeAgent supports ReAct, CodeAct, and native Function Calling paradigms out-of-the-box. This allows agents to reason, generate/execute code, or use a model's native tool-calling capabilities.\n- **Guidance and Auto-Correction:** Includes a \"Planner\" to plan the steps and an internal \"Observer\" to monitor progress, detect loops or stalled plans, and provide corrective feedback to stay on track.\n- **Optimized for SLMs:** The `FunctionCallingAgent` is specifically designed for Small Language Models (SLMs) and models with efficient function-calling support.\n- **Scalable:** With only a few dependencies, KodeAgent perfectly integrates into serverless environments, standalone applications, or existing platforms.\n- **LLM Agnostic:** Built on LiteLLM, KodeAgent easily swaps between models (e.g., Gemini, GPT, and Claude) and providers (e.g., Ollama) without changing your core logic.\n\n\n## ✋ Why Not?\n\nAlso, here are a few reasons why you shouldn't use KodeAgent:\n\n- KodeAgent is actively evolving, meaning some aspects may change.\n- You want to use some of the well-known frameworks.\n- You need a full-fledged platform with built-in long-term, persistent memory management.\n\n\n## 🚀 Quick Start\n\n\u003ca target=\"_blank\" href=\"https://colab.research.google.com/drive/1D9ly3qi9sPZn_sUFdfC1XCFehldCVPXM?usp=sharing\"\u003e\n  \u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/\u003e\n\u003c/a\u003e\n\n\nInstall [KodeAgent](https://pypi.org/project/kodeagent/) via pip:\n```bash\npip install -U kodeagent  # Upgrade existing installation\n```\n\nOr if you want to clone the KodeAgent GitHub repository locally and run from there, use:\n```bash\ngit clone https://github.com/barun-saha/kodeagent.git\n\npython -m venv venv\nsource venv/bin/activate\n# venv\\Scripts\\activate.bat  # Windows\n\npip install -r requirements.txt\n```\n\nNow, in your application code, create a ReAct agent and run a task like this (see `examples/_quickstart/kodeagent_quickstart.py`):\n\n```python\nfrom kodeagent import ReActAgent, print_response\nfrom kodeagent.tools import read_webpage, search_web\n\nagent = ReActAgent(\n    name='Web agent',\n    model_name='gemini/gemini-2.5-flash-lite',\n    tools=[search_web, read_webpage],\n    max_iterations=5,\n)\n\nfor task in [\n    'What are the festivals in Paris? How they differ from Kolkata?',\n]:\n    print(f'User: {task}')\n\n    async for response in agent.run(task):\n        print_response(response, only_final=True)\n```\nThat's it! Your agent should start solving the task and keep streaming the updates. After the loop is done, you can access the final result of the task using `agent.task.result`.\n\nYou can also create a CodeActAgent, which leverages the core CodeAct pattern to generate and execute Python code on the fly for complex tasks. For example:\n\n```python\nfrom kodeagent import CodeActAgent\nfrom kodeagent.tools import read_webpage, search_web, extract_as_markdown\n\nagent = CodeActAgent(\n    name='Web agent',\n    model_name='gemini/gemini-2.0-flash-lite',\n    tools=[search_web, read_webpage, extract_as_markdown],\n    run_env='host',\n    max_iterations=7,\n    allowed_imports=[\n        're', 'requests', 'ddgs', 'urllib', 'requests', 'bs4',\n        'pathlib', 'urllib.parse', 'markitdown'\n    ],\n    pip_packages='ddgs~=9.5.2;beautifulsoup4~=4.14.2;\"markitdown[all]\";',\n)\n```\n\n\n### Native Function Calling (Optimized for SLMs)\n\nFor models that natively support function calling (like Gemini, OpenAI, or specialized SLMs), you can use the `FunctionCallingAgent`. It includes built-in retry logic for transient SLM failures and robust error detection:\n\n```python\nfrom kodeagent import FunctionCallingAgent, print_response\nfrom kodeagent.tools import calculator\n\nagent = FunctionCallingAgent(\n    # Try with your SLMs here, e.g., 'ollama/granite4:7b-a1b-h' or 'ollama/qwen3:4b-instruct-2507-fp16'\n    model_name='gemini/gemini-2.0-flash-lite',\n    tools=[calculator],\n    litellm_params={'temperature': 0, 'timeout': 90},\n)\n\nasync for response in agent.run('What is 123 * 456?'):\n    print_response(response, only_final=True)\n```\n\nUse this [Colab notebook](https://colab.research.google.com/drive/1c7RMTCcSYrO7wZgB25bLX9QenDgVDmAP?usp=sharing) to run function-calling agent with several SLMs (uses T4 GPU).\n\n\n### Task-Specific Agents\n\nKodeAgent provides specialized agent classes for common tasks, such as `CSVAnalysisAgent` for automated data exploration:\n\n```python\nfrom kodeagent.agents import CSVAnalysisAgent\n\nagent = CSVAnalysisAgent(model_name='gemini/gemini-2.0-flash-lite')\n# Auto-loads CSV from URL/path and performs automated analysis\nasync for response in agent.run(\n    'Analyze the trends',\n    files=['https://raw.githubusercontent.com/mwaskom/seaborn-data/master/penguins.csv']\n):\n    pass\n```\n\nCheck out the [CSVAnalysisAgent documentation](https://kodeagent.readthedocs.io/en/latest/specialized_agents.html) for more details.\n\n### Memory(less)\n\nBy default, any agent in KodeAgent is **memoryless** across tasks—each task begins with no prior context, a clean slate. To enable context from the previous task (only), use **Recurrent Mode**:\n\n```python\n# Enable recurrent mode to leverage context from the previous run\nasync for response in agent.run('Double the previous result', recurrent_mode=True):\n    print_response(response)\n```\n\nThis will copy the previous task's description \u0026 result into the current task's context.\n\nFor more examples, including how to provide files as inputs, see the [examples.py](src/kodeagent/examples.py) module and [API documentation](https://kodeagent.readthedocs.io/en/latest/usage.html).\n\n\n### API Configuration\n\nKodeAgent uses [LiteLLM](https://github.com/BerriAI/litellm) for model access and [Langfuse](https://langfuse.com/) or [LangSmith](https://www.langchain.com/langsmith) for observability. Set your API keys as environment variables or in a `.env` file:\n\n| Service | Environment Variable |\n| :--- | :--- |\n| **Gemini** | `GOOGLE_API_KEY` |\n| **OpenAI** | `OPENAI_API_KEY` |\n| **Anthropic** | `ANTHROPIC_API_KEY` |\n| **E2B Sandbox** | `E2B_API_KEY` |\n| **Langfuse** | `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` |\n| **LangSmith** | `LANGCHAIN_API_KEY`, `LANGCHAIN_TRACING_V2` |\n\nDetailed configuration for various providers can be found in the [LiteLLM documentation](https://docs.litellm.ai/docs/set_keys).\n\n\n### Code Execution\n\n`CodeActAgent` executes LLM-generated code to leverage the tools. KodeAgent currently supports two different code run environments:\n- `host`: The Python code will be run on the system where you created this agent. In other words, where the application is running.\n- `e2b`:  The Python code will be run on an [E2B sandbox](https://e2b.dev/). You will need to set the `E2B_API_KEY` environment variable.\n\nWith `host` as the code running environment, no special steps are required, since it uses the current Python installation. However, with `e2b`, code (and tools) are copied to a different environment and are executed there. Therefore, some additional setup may be required.\n\nYou can also specify a `work_dir` to serve as a local workspace. For the `e2b` environment, any files generated by the agent in the sandbox will be automatically downloaded to this local `work_dir`. If specified, `work_dir` could be relative or absolute path, but it **must exist**; otherwise, a temporary directory will be created and used for each run.\n\n```python\nfrom kodeagent import CodeActAgent\n\nagent = CodeActAgent(\n    name='Data Agent',\n    model_name='gemini/gemini-2.0-flash-lite',\n    run_env='e2b',\n    work_dir='/home/user/agent_workspace',  # Local workspace directory to copy files to/from E2B\n    # ... other parameters\n)\n```\n\n\nFor example, the Python modules that are allowed to be used in code should be explicitly specified using `allowed_imports`. In addition, any additional Python package that may need to be installed should be specified as a comma-separated list via `pip_packages`.  \n\nKodeAgent is under active development. Capabilities are limited. Use with caution.\n\n\n## 🛠️ Tools\n\nA tool in KodeAgent is just a regular (synchronous) Python function. KodeAgent comes with the following built-in [tools](src/kodeagent/tools.py):\n- **`calculator`**: A simple calculator tool to perform basic arithmetic operations. It imports the `ast`, `operator`, and `re` Python libraries.\n- **`download_file`**: A tool to download a file from a given URL. It imports the `requests`, `re`, `tempfile`, `pathlib`, and `urllib.parse` Python libraries.\n- **`extract_as_markdown`**: A tool to read file contents and return as Markdown using MarkItDown. It imports the `re`, `pathlib`, `urllib.parse`, and `markitdown` Python libraries.\n- **`generate_image`**: A tool to generate an image based on a text prompt using the specified model. The (LiteLLM) model name to be used must be mentioned in the task, system prompt, or somehow. It imports the `os`, `base64`, and `litellm` Python libraries.\n- **`read_webpage`**: A tool to read a webpage using BeautifulSoup. It imports the `re`, `requests`, `urllib.parse`, and `bs4` Python libraries.\n- **`search_arxiv`**: A tool to search arXiv for research papers and return summaries and links. It imports the `arxiv` library.\n- **`search_web`**: A web search tool using DuckDuckGo to fetch top search results. It imports the `datetime`, `random`, and `time` Python libraries.\n- **`search_wikipedia`**: A tool to search Wikipedia and return summaries and links. It imports the `wikipedia` library.\n- **`transcribe_audio`**: A tool to transcribe audio files using OpenAI's Whisper via [Fireworks API](https://fireworks.ai/). Need to set the `FIREWORKS_API_KEY` environment variable. It imports the `os` and `requests` Python libraries.\n- **`transcribe_youtube`**: A tool to fetch YouTube video transcripts. It imports the `youtube_transcript_api` library.\n\nCheck out the docstrings of these tools in the [tools.py](src/kodeagent/tools.py) module for more details.\n\nNote: v0.12.1 has disabled installation of `arxiv` by default since that requires an older `requests` version. If you want to use `search_arxiv` tool, please install `arxiv` separately with `pip install arxiv`. Alternatively, pin to a prior version until this gets resolved.\n\nTo add your own custom tools, simply define a Python function and pass it to the agent via the `tools` parameter. For example:\n\n```python\ndef my_custom_tool(text: str) -\u003e str:\n    \"\"\"\n    A custom tool that does something with the input text and returns a result.\n    \n    Args:\n        text (str): The input text to process.\n        \n    Returns:\n        str: The processed result.\n    \"\"\"\n    return text\n\nagent = ReActAgent(\n    name='Custom Tool Agent',\n    model_name='gemini/gemini-2.5-flash-lite',\n    tools=[my_custom_tool],\n    max_iterations=5,\n)\n```\n\nModule imports and all variables should be inside the tool function. If you're using `CodeActAgent`, KodeAgent will execute the tool function in isolation.\nFor further details, refer to the [API documentation](https://kodeagent.readthedocs.io/en/latest/). Note: `async` tools are not supported.\n\n\n## 🔭 Observability\n\nIn addition to the logs, KodeAgent enables agent observability via third-party solutions, such as [Langfuse](https://langfuse.com/) and [LangSmith](https://www.langchain.com/langsmith).\n\nTo enable tracing, set the relevant environment variables (e.g., `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` for Langfuse, or `LANGCHAIN_API_KEY` and `LANGCHAIN_TRACING_V2='true'` for LangSmith). Note that `langsmith` is not installed by default with KodeAgent and must be installed separately with `pip install langsmith`. Then, in the code, specify `tracing_type` as `langfuse` or `langsmith` when creating the agent:\n\n```python\nfrom kodeagent import ReActAgent\n\nagent = ReActAgent(\n    name='Web agent',\n    model_name='gemini/gemini-2.5-flash-lite',\n    tools=[search_web, read_webpage],\n    tracing_type='langfuse',  # or 'langsmith'\n)\n```\n\nTracing is **disabled** by default (rather, a no-op tracer is used). You will need to explicitly enable it, as shown in the code snippet above. The screenshot below shows a sample trace of KodeAgent running a task on the Langfuse dashboard:\n\n\u003cimg width=\"80%\" height=\"80%\" alt=\"KodeAgent trace on Langfuse dashboard\" src=\"https://github.com/user-attachments/assets/52530ccd-57dd-4be0-afe9-70cdab279a2e\" /\u003e\n\n\n## ⊷ Sequence Diagram for CodeAct Agent (via CodeRabbit)\n```mermaid\nsequenceDiagram\n  autonumber\n  actor User\n  participant Agent\n  participant Planner\n  participant LLM as LLM/Prompts\n  participant Tools\n\n  User-\u003e\u003eAgent: run(task)\n  Agent-\u003e\u003ePlanner: create_plan(task)\n  Planner-\u003e\u003eLLM: request AgentPlan JSON (agent_plan.txt)\n  LLM--\u003e\u003ePlanner: AgentPlan JSON\n  Planner--\u003e\u003eAgent: planner.plan set\n\n  loop For each step\n    Agent-\u003e\u003ePlanner: get_formatted_plan()\n    Agent-\u003e\u003eLLM: codeact prompt + {plan, history}\n    LLM--\u003e\u003eAgent: Thought + Code\n    Agent-\u003e\u003eTools: execute tool call(s)\n    Tools--\u003e\u003eAgent: Observation\n    Agent-\u003e\u003ePlanner: update_plan(thought, observation, task_id)\n  end\n\n  Agent--\u003e\u003eUser: Final Answer / Failure (per codeact spec)\n```\n\n\n## 🧪 Run Tests\n\nTo run unit tests, use:\n```bash\npython -m pytest .\\tests\\unit -v --cov --cov-report=html\n```\n\nFor integration tests involving calls to APIs, use:\n```bash\npython -m pytest .\\tests\\integration -v --cov --cov-report=html\n```\n\nGemini and E2B API keys should be set in the `.env` file for integration tests to work.\n\nA [Kaggle notebook](https://www.kaggle.com/code/barunsaha/kodeagent-benchmark/) for benchmarking KodeAgent is also available.\n\n### Scalene Profiling\n\nThe following results were measured using [Scalene](https://github.com/plasma-umass/scalene) and `psutil` on development machine (Windows 10, Python 3.10). \"Peak Memory\" refers to the maximum Resident Set Size (RSS), i.e., the actual RAM used by the process.\n\n```shell\npython -m scalene run -c scalene.yaml -m src.kodeagent.examples\nscalene view\n```\n\n| Agent Type   | Avg. Runtime | Peak Memory (Scalene) | Peak Memory (psutil) | Notes                                        |\n|--------------|--------------|-----------------------|---------------------|----------------------------------------------|\n| ReActAgent   | ~58s         | 30MB                  | 294MB               | Faster, because tools are directly executed  |\n| CodeActAgent | ~155s        | 21MB                  | 253MB               | Slower, because of code review and execution |\n\n**Notes:**\n- _Scalene_ reports the maximum _sampled_ RSS during profiling, which is useful for comparing code sections but may miss short-lived or end-of-program memory spikes.\n- _psutil_ reports the actual RSS at program _end_, which is typically higher and reflects the real-world memory footprint.\n- Actual memory usage may vary depending on your system, Python version, and workload.\n\n\n\n## 🗺️ Roadmap \u0026 Contributions\n\nTo be updated.\n\n\n## 🙏 Acknowledgement\n\nKodeAgent heavily borrows code and ideas from different places, such as:\n- [LlamaIndex](https://docs.llamaindex.ai/en/stable/examples/agent/react_agent/)\n- [Smolagents](https://github.com/huggingface/smolagents/tree/main)\n- [LangGraph](https://github.com/langchain-ai/langgraph)\n- [Building ReAct Agents from Scratch: A Hands-On Guide using Gemini](https://medium.com/google-cloud/building-react-agents-from-scratch-a-hands-on-guide-using-gemini-ffe4621d90ae)\n- [LangGraph Tutorial: Build Your Own AI Coding Agent](https://medium.com/@mariumaslam499/build-your-own-ai-coding-agent-with-langgraph-040644343e73)\n- Aider, Antigravity, CodeRabbit, GitHub Copilot, Jules, ...\n\n\n## ⚠️ DISCLAIMER \u0026 LIABILITY\n\nAI agents can occasionally cause unintended or unpredictable side effects. We urge users to **use KodeAgent with caution**. Always review generated code and test agents rigorously in a constrained, non-production environment before deployment.\n\n**LIMITATION OF LIABILITY:**\nBy using this software, you agree that KodeAgent, its developers, contributors, supporters, and any other associated entities shall not be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarun-saha%2Fkodeagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarun-saha%2Fkodeagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarun-saha%2Fkodeagent/lists"}