{"id":28613934,"url":"https://github.com/Intelligent-Internet/ii-agent","last_synced_at":"2025-06-12T01:04:17.304Z","repository":{"id":294449569,"uuid":"962134278","full_name":"Intelligent-Internet/ii-agent","owner":"Intelligent-Internet","description":"II-Agent: a new open-source framework to build and deploy intelligent agents","archived":false,"fork":false,"pushed_at":"2025-06-11T05:22:17.000Z","size":1897,"stargazers_count":2405,"open_issues_count":20,"forks_count":351,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-06-11T06:29:16.095Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ii.inc/web/blog/post/ii-agent","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/Intelligent-Internet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGENOTES.md","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}},"created_at":"2025-04-07T17:45:48.000Z","updated_at":"2025-06-11T05:56:59.000Z","dependencies_parsed_at":"2025-06-03T19:55:28.142Z","dependency_job_id":"fc2d777e-a3d3-4850-88fe-e5d5c6968279","html_url":"https://github.com/Intelligent-Internet/ii-agent","commit_stats":null,"previous_names":["intelligent-internet/ii-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Intelligent-Internet/ii-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2Fii-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2Fii-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2Fii-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2Fii-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Intelligent-Internet","download_url":"https://codeload.github.com/Intelligent-Internet/ii-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intelligent-Internet%2Fii-agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259374698,"owners_count":22847854,"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":[],"created_at":"2025-06-12T01:02:01.402Z","updated_at":"2025-06-12T01:04:17.294Z","avatar_url":"https://github.com/Intelligent-Internet.png","language":"Python","funding_links":[],"categories":["Agent Integration \u0026 Deployment Tools","Python","智能体 Agents","4. Agentic AI \u0026 Multi-Agent Systems"],"sub_categories":["AI Agent Development"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/ii.png\" width=\"200\"/\u003e\n\n\n\n\n# II Agent\n\n[![GitHub stars](https://img.shields.io/github/stars/Intelligent-Internet/ii-agent?style=social)](https://github.com/Intelligent-Internet/ii-agent/stargazers)\n[![Discord Follow](https://dcbadge.limes.pink/api/server/yDWPsshPHB?style=flat)](https://discord.gg/yDWPsshPHB)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Blog](https://img.shields.io/badge/Blog-II--Agent-blue)](https://ii.inc/web/blog/post/ii-agent)\n[![GAIA Benchmark](https://img.shields.io/badge/GAIA-Benchmark-green)](https://ii-agent-gaia.ii.inc/)\n[\u003cimg src=\"https://devin.ai/assets/deepwiki-badge.png\" alt=\"Ask DeepWiki.com\" height=\"20\"/\u003e](https://deepwiki.com/Intelligent-Internet/ii-agent)\n\n\u003c/div\u003e\n\nII-Agent is an open-source intelligent assistant designed to streamline and enhance workflows across multiple domains. It represents a significant advancement in how we interact with technology—shifting from passive tools to intelligent systems capable of independently executing complex tasks.\n\n### Discord Join US\n\n📢 Join Our [Discord Channel](https://discord.gg/yDWPsshPHB)! Looking forward to seeing you there! 🎉\n\n\n## Introduction\nhttps://github.com/user-attachments/assets/d0eb7440-a6e2-4276-865c-a1055181bb33\n\n\n## Overview\n\nII Agent is built around providing an agentic interface to leading language models. It offers:\n\n- A CLI interface for direct command-line interaction\n- A WebSocket server that powers a modern React-based frontend\n- Integration with multiple LLM providers:\n  - Anthropic Claude models (direct API or via Google Cloud Vertex AI)\n  - Google Gemini models (direct API or via Google Cloud Vertex AI)\n\n## Core Capabilities\n\nII-Agent is a versatile open-source assistant built to elevate your productivity across domains:\n\n| Domain | What II‑Agent Can Do |\n|--------|----------------------|\n| Research \u0026 Fact‑Checking | Multistep web search, source triangulation, structured note‑taking, rapid summarization |\n| Content Generation | Blog \u0026 article drafts, lesson plans, creative prose, technical manuals, Website creations |\n| Data Analysis \u0026 Visualization | Cleaning, statistics, trend detection, charting, and automated report generation |\n| Software Development | Code synthesis, refactoring, debugging, test‑writing, and step‑by‑step tutorials across multiple languages |\n| Workflow Automation | Script generation, browser automation, file management, process optimization |\n| Problem Solving | Decomposition, alternative‑path exploration, stepwise guidance, troubleshooting |\n\n## Methods\n\nThe II-Agent system represents a sophisticated approach to building versatile AI agents. Our methodology centers on:\n\n1. **Core Agent Architecture and LLM Interaction**\n   - System prompting with dynamically tailored context\n   - Comprehensive interaction history management\n   - Intelligent context management to handle token limitations\n   - Systematic LLM invocation and capability selection\n   - Iterative refinement through execution cycles\n\n2. **Planning and Reflection**\n   - Structured reasoning for complex problem-solving\n   - Problem decomposition and sequential thinking\n   - Transparent decision-making process\n   - Hypothesis formation and testing\n\n3. **Execution Capabilities**\n   - File system operations with intelligent code editing\n   - Command line execution in a secure environment\n   - Advanced web interaction and browser automation\n   - Task finalization and reporting\n   - Specialized capabilities for various modalities (Experimental) (PDF, audio, image, video, slides)\n   - Deep research integration\n\n4. **Context Management**\n   - Token usage estimation and optimization\n   - Strategic truncation for lengthy interactions\n   - File-based archival for large outputs\n\n5. **Real-time Communication**\n   - WebSocket-based interface for interactive use\n   - Isolated agent instances per client\n   - Streaming operational events for responsive UX\n\n## GAIA Benchmark Evaluation\n\nII-Agent has been evaluated on the GAIA benchmark, which assesses LLM-based agents operating within realistic scenarios across multiple dimensions including multimodal processing, tool utilization, and web searching.\n\nWe identified several issues with the GAIA benchmark during our evaluation:\n\n- **Annotation Errors**: Several incorrect annotations in the dataset (e.g., misinterpreting date ranges, calculation errors)\n- **Outdated Information**: Some questions reference websites or content no longer accessible\n- **Language Ambiguity**: Unclear phrasing leading to different interpretations of questions\n\nDespite these challenges, II-Agent demonstrated strong performance on the benchmark, particularly in areas requiring complex reasoning, tool use, and multi-step planning.\n\n![GAIA Benchmark](assets/gaia.jpg)\nYou can view the full traces of some samples here: [GAIA Benchmark Traces](https://ii-agent-gaia.ii.inc/)\n\n## Requirements\n- Docker Compose\n- Python 3.10+\n- Node.js 18+ (for frontend)\n- At least one of the following:\n  - Anthropic API key, or\n  - Google Gemini API key, or  \n  - Google Cloud project with Vertex AI API enabled\n\n## Best Practices:\n- For best performance, we recommend using Claude 4.0 Sonnet or Claude Opus 4.0 models.\n- For fast and cheap, we recommend using GPT4.1 from OpenAI.\n- Gemini 2.5 Pro is a good balance between performance and cost.\n\n## Environment\n\nYou need to set up 2 `.env` files to run both frontend and backend\n**Shortcut:** Check file `.env.example` for example of `.env` file.\n\n### Frontend Environment Variables\n\nFor the frontend, create a `.env` file in the frontend directory, point to the port of your backend:\n\n```bash\nNEXT_PUBLIC_API_URL=http://localhost:8000\n```\n\n### Backend Environment Variables\n\nFor the backend, create a `.env` file in the root directory with the following variables. Here are the required variables needed to run this project:\n\n\n```bash\n# Required API Keys - Choose one based on your LLM provider:\n# Option 1: For Claude models via Anthropic\nANTHROPIC_API_KEY=your_anthropic_key\n\n# Option 2: For Gemini models via Google\nGEMINI_API_KEY=your_gemini_key\n\n# Option 3: For OpenAI models\nOPENAI_API_KEY=your_openai_key\n\n# Search Provider API Key\nTAVILY_API_KEY=your_tavily_key\n\nSTATIC_FILE_BASE_URL=http://localhost:8000/\n```\n\nWe also support other search and crawl provider such as FireCrawl and SerpAPI (Optional but yield better performance):\n```bash\nJINA_API_KEY=your_jina_key\nFIRECRAWL_API_KEY=your_firecrawl_key\nSERPAPI_API_KEY=your_serpapi_key \n```\n\nWe are supporting image generation and video generation tool by Vertex AI (Optional, good for more creative output), to use this, you need to set up the following variables:\n```bash\nMEDIA_GCS_OUTPUT_BUCKET=gs://your_bucket_here\nMEDIA_GCP_PROJECT_ID=your_vertex_project_id\nMEDIA_GCP_LOCATION=your_vertex_location\n```\n\nImage Search Tool  (Optional, good for more beautiful output)\n```\nSERPAPI_API_KEY=your_serpapi_key \n```\n\n\n## Installation\n\n### Docker Installation (Recommended)\n\n1. Clone the repository\n2. Set up the 2 environment files as mentioned in the above step\n3. If you are using Anthropic Client run\n```\nchmod +x start.sh stop.sh\n./start.sh \n```\nIf you are using Vertex, run with these variables\n```\nGOOGLE_APPLICATION_CREDENTIALS=absolute-path-to-credential \\\nPROJECT_ID=project-id \\\nREGION=region \\\n./start.sh\n```\n*Note: Due to a bug in the latest docker, if you receive and error, try running with `--force-recreate`. For example `./start.sh --force-recreate `*\n\nAfter running start.sh, you can check your application at: localhost:3000\n\nRun `./stop.sh` to tear down the service.\n\n### Manual Installation\n1. Clone the repository\n2. Set up Python environment:\n   ```bash\n   python -m venv .venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n   pip install -e .\n   ```\n\n3. Set up frontend (optional):\n   ```bash\n   cd frontend\n   npm install\n   ```\n\n### Command Line Interface\n\nIf you want to use anthropic client, set `ANTHROPIC_API_KEY` in `.env` file and run:\n```bash\npython cli.py \n```\n\nIf you want to use vertex, set `GOOGLE_APPLICATION_CREDENTIALS` and run:\n```bash\nGOOGLE_APPLICATION_CREDENTIALS=path-to-your-credential\npython cli.py --project-id YOUR_PROJECT_ID --region YOUR_REGION\n```\n\nOptions:\n- `--project-id`: Google Cloud project ID\n- `--region`: Google Cloud region (e.g., us-east5)\n- `--workspace`: Path to the workspace directory (default: ./workspace)\n- `--needs-permission`: Require permission before executing commands\n- `--minimize-stdout-logs`: Reduce the amount of logs printed to stdout\n\n### Web Interface\n\n1. Start the WebSocket server:\n\nWhen using Anthropic client:\n```bash\npython ws_server.py --port 8000\n```\n\nWhen using Vertex:\n```bash\nGOOGLE_APPLICATION_CREDENTIALS=path-to-your-credential \\\npython ws_server.py --port 8000 --project-id YOUR_PROJECT_ID --region YOUR_REGION\n```\n\n2. Start the frontend (in a separate terminal):\n\n```bash\ncd frontend\nnpm run dev\n```\n\n3. Open your browser to http://localhost:3000\n\n## Project Structure\n\n- `cli.py`: Command-line interface\n- `ws_server.py`: WebSocket server for the frontend\n- `src/ii_agent/`: Core agent implementation\n  - `agents/`: Agent implementations\n  - `llm/`: LLM client interfaces\n  - `tools/`: Tool implementations\n  - `utils/`: Utility functions\n\n## Conclusion\n\nThe II-Agent framework, architected around the reasoning capabilities of large language models like Claude 4.0 Sonnet or Gemini 2.5 Pro, presents a comprehensive and robust methodology for building versatile AI agents. Through its synergistic combination of a powerful LLM, a rich set of execution capabilities, an explicit mechanism for planning and reflection, and intelligent context management strategies, II-Agent is well-equipped to address a wide spectrum of complex, multi-step tasks. Its open-source nature and extensible design provide a strong foundation for continued research and development in the rapidly evolving field of agentic AI.\n\n## Acknowledgement\n\nWe would like to express our sincere gratitude to the following projects and individuals for their invaluable contributions that have helped shape this project:\n\n- **AugmentCode**: We have incorporated and adapted several key components from the [AugmentCode project](https://github.com/augmentcode/augment-swebench-agent). AugmentCode focuses on SWE-bench, a benchmark that tests AI systems on real-world software engineering tasks from GitHub issues in popular open-source projects. Their system provides tools for bash command execution, file operations, and sequential problem-solving capabilities designed specifically for software engineering tasks.\n\n- **Manus**: Our system prompt architecture draws inspiration from Manus's work, which has helped us create more effective and contextually aware AI interactions.\n\n- **Index Browser Use**: We have built upon and extended the functionality of the [Index Browser Use project](https://github.com/lmnr-ai/index/tree/main), particularly in our web interaction and browsing capabilities. Their foundational work has enabled us to create more sophisticated web-based agent behaviors.\n\nWe are committed to open source collaboration and believe in acknowledging the work that has helped us build this project. If you feel your work has been used in this project but hasn't been properly acknowledged, please reach out to us.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntelligent-Internet%2Fii-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIntelligent-Internet%2Fii-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntelligent-Internet%2Fii-agent/lists"}