{"id":47566442,"url":"https://github.com/lemopian/strands-deep-agents","last_synced_at":"2026-04-27T09:32:20.014Z","repository":{"id":322771546,"uuid":"1089625948","full_name":"lemopian/strands-deep-agents","owner":"lemopian","description":"A planning-capable agent implementation using the Strands Agents SDK, inspired by the DeepAgents pattern. This library enables sophisticated multi-agent systems with autonomous planning, sub-agent delegation, and persistent state management.","archived":false,"fork":false,"pushed_at":"2025-11-18T08:47:03.000Z","size":868,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T01:03:36.547Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.pierreange.ai/blog/deep-agents-using-strands","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lemopian.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-11-04T15:40:50.000Z","updated_at":"2026-03-13T19:06:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"8a503b9e-d3dd-438d-83a4-375fc256d05e","html_url":"https://github.com/lemopian/strands-deep-agents","commit_stats":null,"previous_names":["lemopian/strands-deep-agents"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/lemopian/strands-deep-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemopian%2Fstrands-deep-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemopian%2Fstrands-deep-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemopian%2Fstrands-deep-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemopian%2Fstrands-deep-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lemopian","download_url":"https://codeload.github.com/lemopian/strands-deep-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lemopian%2Fstrands-deep-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32331305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-03-30T06:00:24.600Z","updated_at":"2026-04-27T09:32:19.992Z","avatar_url":"https://github.com/lemopian.png","language":"Python","funding_links":[],"categories":["Community Projects"],"sub_categories":["For PyPI Packages"],"readme":"# Strands Deep Agents\n\nBuild sophisticated AI agent systems with planning, sub-agent delegation, and multi-step workflows. Built on the [Strands Agents SDK](https://github.com/strands-ai/strands-agents).\n\n## What is Deep Agents?\n\n![Deep Agents Overview](https://raw.githubusercontent.com/lemopian/strands-deep-agents/main/docs/img/deep-agent-overview.png)\n\nCheck the related [article](http://pierreange.ai/blog/deep-agents-using-strands) for more details.\n\nDeep Agents enables AI systems to handle complex, multi-step tasks through:\n- 🧠 **Strategic Planning** - Break down complex tasks into actionable TODOs\n- 🤝 **Sub-agent Orchestration** - Delegate specialized tasks to focused agents\n- 📁 **Context Management** - Efficient file-based operations to keep context lean\n- 💾 **Session Persistence** - Resume work across sessions\n- 🔬 **Research \u0026 Analysis** - Multi-perspective investigation and synthesis\n\n**Featured Example**: [DeepSearch](#deepsearch-advanced-research-agent) - A production-ready research agent demonstrating sub-agent orchestration, parallel research, and intelligent synthesis.\n\n\n## Installation\n\n```bash\n# Using UV\nuv add strands-deep-agents\n\n# Using pip\npip install strands-deep-agents\n```\n\n**Requirements:** Python \u003e= 3.12\n\n## Quick Start\n\n### Basic Agent\n\n```python\nfrom strands_deep_agents import create_deep_agent\n\nagent = create_deep_agent(\n    instructions=\"You are a helpful coding assistant.\",\n    model=\"global.anthropic.claude-sonnet-4-5-20250929-v1:0\"\n)\n\nresult = agent(\"Create a Python calculator module with add, subtract, multiply, divide functions\")\nprint(result)\n```\n\nThe agent will automatically:\n1. Plan the task using TODOs\n2. Create the file with proper structure\n3. Add docstrings and examples\n\n### Check Task Progress\n\n```python\n# View the agent's planned tasks\nfor todo in agent.state.get(\"todos\", []):\n    print(f\"[{todo['status']}] {todo['content']}\")\n```\n\nOutput:\n```\n[completed] Plan calculator module structure\n[completed] Create calculator.py file\n[completed] Add arithmetic functions\n[completed] Add docstrings and examples\n```\n\n## DeepSearch: Advanced Research Agent\n\nDeepSearch demonstrates the full power of Deep Agents through a production-ready research agent system with intelligent orchestration and parallel research capabilities.\n\nFor this example, we can use any internet search tool, for example [Linkup] (https://app.linkup.so/) or tavily tool for web search.\n\n### Architecture\n\nDeepSearch uses a **three-tier agent architecture**:\n\n1. **Research Lead Agent** - Strategic planning, task decomposition, and synthesis\n2. **Research Sub-agents** - Parallel, focused investigation on specific topics\n3. **Citations Agent** - Post-processing to add proper source references\n\n### Key Features\n\n- **Intelligent Task Decomposition**: Analyzes queries as depth-first (multiple perspectives) or breadth-first (independent sub-questions)\n- **Parallel Research**: Deploys multiple sub-agents simultaneously for efficient information gathering\n- **Context Management**: Sub-agents write findings to files, keeping context lean\n- **Source Citation**: Automated citation agent adds proper references to final reports\n- **Session Persistence**: Resume research across sessions\n\n### Running DeepSearch\n\n```bash\ncd examples/deepsearch\n\n# Basic usage with default prompt\npython agent.py\n\n# Custom research prompt\npython agent.py -p \"Research the impact of AI on healthcare in 2025\"\n```\n\n### DeepSearch Implementation\n\n```python\nfrom strands_deep_agents import create_deep_agent, SubAgent\nfrom strands_tools import tavily, file_read, file_write\n\n# Research sub-agent - performs focused investigations\nresearch_subagent = SubAgent(\n    name=\"research_subagent\",\n    description=(\n        \"Specialized research agent for focused investigations. \"\n        \"Researches specific questions, gathers facts, analyzes sources. \"\n        \"Has access to web search. Writes findings to files.\"\n    ),\n    tools=[tavily, file_write],\n    prompt=\"You are a thorough researcher. Gather comprehensive, accurate information...\"\n)\n\n# Citations agent - adds source references\ncitations_agent = SubAgent(\n    name=\"citations_agent\",\n    description=\"Adds proper citations to research reports.\",\n    tools=[file_read, file_write],\n    prompt=\"Add citations to research text using provided sources...\"\n)\n\n# Create the research lead agent\nagent = create_deep_agent(\n    instructions=\"\"\"\n    You are an expert research lead. Your role:\n    1. Analyze the research question\n    2. Create a research plan\n    3. Deploy research sub-agents for focused investigations\n    4. Synthesize findings into a comprehensive report\n    5. Call citations agent to add references\n    \"\"\",\n    subagents=[research_subagent, citations_agent],\n    tools=[file_read, file_write]\n)\n\n# Execute research\nresult = agent(\"\"\"\nResearch AI safety in 2025:\n1. Main challenges and concerns\n2. Leading organizations and initiatives\nCreate a comprehensive report with executive summary.\n\"\"\")\n```\n\n### How DeepSearch Works\n\n1. **Planning Phase**: Lead agent analyzes the query and creates a research plan\n2. **Parallel Research**: Multiple research sub-agents investigate different aspects simultaneously\n3. **File-Based Context**: Sub-agents write findings to `./research_findings_*.md` files\n4. **Synthesis**: Lead agent reads all findings and synthesizes a comprehensive report\n5. **Citations**: Citations agent adds proper source references to the final report\n\n### Example Output Structure\n\n```\nResearch findings written to: research_findings_1.md, research_findings_2.md, ...\nFinal report: ai_safety_2025_report.md\n\nTODOs:\n✅ Analyze research question and create plan\n✅ Deploy subagent: AI safety challenges\n✅ Deploy subagent: Leading organizations\n✅ Deploy subagent: Recent initiatives\n✅ Synthesize findings into report\n✅ Add citations to report\n```\n\n## Core Patterns\n\n### Sub-agent Delegation\n\nDeep Agents excel at delegating specialized tasks:\n\n```python\nfrom strands_deep_agents import create_deep_agent\n\nsubagents = [\n    {\n        \"name\": \"researcher\",\n        \"description\": \"Conducts focused research on specific topics\",\n        \"prompt\": \"You are a thorough researcher. Gather comprehensive information.\"\n    },\n    {\n        \"name\": \"analyst\",\n        \"description\": \"Analyzes data and identifies patterns\",\n        \"prompt\": \"You are a data analyst. Find insights and patterns.\"\n    }\n]\n\nagent = create_deep_agent(\n    instructions=\"You are a research coordinator.\",\n    subagents=subagents\n)\n```\n\n### Session Persistence\n\nResume work across sessions:\n\n```python\nfrom strands.session.file_session_manager import FileSessionManager\n\nsession_manager = FileSessionManager(\n    session_id=\"project-xyz\",\n    storage_dir=\"./sessions\"\n)\n\nagent = create_deep_agent(\n    instructions=\"You are a research assistant.\",\n    session_manager=session_manager\n)\n\n# First session\nagent(\"Start researching quantum computing\")\n\n# Later - conversation history and TODOs restored\nagent(\"Continue where we left off\")\n```\n\n### Custom Tools\n\nExtend agents with your own tools:\n\n```python\nfrom strands import tool\n\n@tool\ndef web_search(query: str) -\u003e str:\n    \"\"\"Search the web for information.\"\"\"\n    # Your implementation\n    return search_results\n\nagent = create_deep_agent(\n    instructions=\"You are a research assistant.\",\n    tools=[web_search]\n)\n```\n\n## API Reference\n\n### `create_deep_agent()`\n\nCreate a deep agent with planning and sub-agent capabilities.\n\n```python\nfrom strands_deep_agents import create_deep_agent\n\nagent = create_deep_agent(\n    instructions=\"System prompt for the agent\",\n    model=None,                          # Default: Claude Sonnet 4\n    subagents=None,                      # List of SubAgent configs\n    tools=None,                          # Additional custom tools\n    session_manager=None,                # For persistence\n    disable_parallel_tool_calling=False, # Force sequential execution\n    **kwargs                             # Additional Agent params\n)\n```\n\n### `SubAgent`\n\nDefine specialized sub-agents:\n\n```python\nfrom strands_deep_agents import SubAgent\n\nsubagent = SubAgent(\n    name=\"unique_name\",\n    description=\"When to use this agent (helps main agent decide)\",\n    prompt=\"System prompt for sub-agent\",\n    tools=[...],     # Optional: specific tools\n    model=model      # Optional: override model\n)\n```\n\n### Async Support\n\n```python\nfrom strands_deep_agents import async_create_deep_agent\n\nagent = await async_create_deep_agent(\n    instructions=\"You are a research assistant.\"\n)\nresult = await agent.invoke_async(\"Your task\")\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# AWS Bedrock (default provider)\nexport AWS_REGION=us-east-1\nexport AWS_ACCESS_KEY_ID=your_key\nexport AWS_SECRET_ACCESS_KEY=your_secret\n\n# Optional: Skip tool consent prompts\nexport BYPASS_TOOL_CONSENT=true\n```\n\n### Model Options\n\n```python\n# Use AWS Bedrock models (default)\nagent = create_deep_agent(\n    model=\"global.anthropic.claude-sonnet-4-5-20250929-v1:0\"\n)\n\n# Custom model configuration\nfrom strands.models import Model\n\ncustom_model = Model(\n    provider=\"bedrock\",\n    name=\"claude-3-5-sonnet-20241022-v2:0\",\n    region=\"us-east-1\"\n)\n\nagent = create_deep_agent(model=custom_model)\n```\n\n## Additional Examples\n\nThe `examples/` directory contains more patterns:\n\n```bash\n# Basic agent usage\npython examples/basic_usage.py\n\n# Sub-agent delegation patterns\npython examples/sub_agents.py\n\n# Session persistence\npython examples/session_persistence.py\n\n# DeepSearch - Advanced research agent (recommended)\ncd examples/deepsearch\npython agent.py\n```\n\n## Best Practices\n\n1. **Clear Instructions** - Be specific about agent roles and expectations\n2. **Strategic Sub-agents** - Use sub-agents for specialized, focused tasks\n3. **Context Management** - Use file operations to keep context lean\n4. **Session Persistence** - Enable for long-running or resumable tasks\n5. **Prompt for Planning** - Encourage agents to create plans before execution\n\n\n## Links\n\n- **GitHub**: https://github.com/lemopian/strands-deep-agents\n- **Strands Agents SDK**: https://github.com/strands-ai/strands-agents\n- **Article**: [Deep Agents Using Strands](http://pierreange.ai/blog/deep-agents-using-strands)\n- **Inspiration**: https://github.com/langchain-ai/deepagents\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Built with ❤️ by PA**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemopian%2Fstrands-deep-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flemopian%2Fstrands-deep-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flemopian%2Fstrands-deep-agents/lists"}