{"id":29959856,"url":"https://github.com/shelex/deepagents-ts","last_synced_at":"2025-08-03T22:03:09.182Z","repository":{"id":307860945,"uuid":"1030909921","full_name":"Shelex/deepagents-ts","owner":"Shelex","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-02T16:12:46.000Z","size":287,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-02T18:29:02.212Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@shelex/deepagents-ts","language":"TypeScript","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/Shelex.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.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-08-02T15:38:54.000Z","updated_at":"2025-08-02T16:20:31.000Z","dependencies_parsed_at":"2025-08-02T18:29:04.963Z","dependency_job_id":"6ba4872d-e8d7-4685-98db-a7e082a59197","html_url":"https://github.com/Shelex/deepagents-ts","commit_stats":null,"previous_names":["shelex/deepagents-ts"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Shelex/deepagents-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shelex%2Fdeepagents-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shelex%2Fdeepagents-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shelex%2Fdeepagents-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shelex%2Fdeepagents-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shelex","download_url":"https://codeload.github.com/Shelex/deepagents-ts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shelex%2Fdeepagents-ts/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268618894,"owners_count":24279270,"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","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"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":"2025-08-03T22:01:38.229Z","updated_at":"2025-08-03T22:03:09.133Z","avatar_url":"https://github.com/Shelex.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## This is an unofficial port of the [hwchase17/deepagents](https://github.com/hwchase17/deepagents) Python package to TypeScript\n\n# 🧠🤖Deep Agents\n\nUsing an LLM to call tools in a loop is the simplest form of an agent.\nThis architecture, however, can yield agents that are “shallow” and fail to plan and act over longer, more complex tasks.\nApplications like “Deep Research”, \"Manus\", and “Claude Code” have gotten around this limitation by implementing a combination of four things:\na **planning tool**, **sub agents**, access to a **file system**, and a **detailed prompt**.\n\n\u003cimg src=\"deep_agents.png\" alt=\"deep agent\" width=\"600\"/\u003e\n\n`deepagents` is a Typescript package that implements these in a general purpose way so that you can easily create a Deep Agent for your application.\n\n**Acknowledgements: This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so.**\n\n## Installation\n\n```bash\nnpm install deepagents\n```\n\n## Usage\n\n\u003e NB! This part of documentation is not fully migrated\n\nSee [src/examples/research/agent.ts](src/examples/research/agent.ts) for a more complex example.\n\nThe agent created with `createDeepAgent` is just a LangGraph graph - so you can interact with it (streaming, human-in-the-loop, memory, studio)\nin the same way you would any LangGraph agent.\n\n## Creating a custom deep agent\n\nThere is an option argument with three properties you can pass to `createDeepAgent` to create your own custom deep agent.\n\n### `tools` (Required)\n\nThis should be a list of functions or LangChain `@tool` objects.\nThe agent (and any subagents) will have access to these tools.\n\n### `instructions` (Required)\n\nThis will serve as part of the prompt of the deep agent.\nNote that there is a [built in system prompt](#built-in-prompt) as well, so this is not the _entire_ prompt the agent will see.\n\n### `subagents` (Optional)\n\nThis can be used to specify any custom subagents this deep agent will have access to.\nYou can read more about why you would want to use subagents [here](#sub-agents)\n`subagents` should be a list of dictionaries, where each dictionary follow this schema:\n\n```js\nexport interface SubAgent {\n    name: string;\n    description: string;\n    prompt: string;\n    tools?: string[];\n}\n```\n\n-   **name**: This is the name of the subagent, and how the main agent will call the subagent\n-   **description**: This is the description of the subagent that is shown to the main agent\n-   **prompt**: This is the prompt used for the subagent\n-   **tools**: This is the list of tools that the subagent has access to. By default will have access to all tools passed in, as well as all built-in tools.\n\nTo use it looks like:\n\n```js\nimport { createDeepAgent, SubAgent } from \"deepagents\";\n\nconst researchSubAgent: SubAgent = {\n    name: \"research-agent\",\n    description: \"Used to research more in depth questions...\",\n    prompt: subResearchPrompt,\n    tools: [\"internet_search\"],\n};\nconst agent = createDeepAgent({\n    instructions: researchInstructions,\n    subagents: [researchSubAgent],\n    tools: [internetSearch],\n});\n```\n\n### `model` (Optional)\n\nBy default, `deepagents` will use local LM Studio. If you want to use a different model,\nyou can pass a [LangChain model object](https://js.langchain.com/docs/integrations/chat/).\n\n## Deep Agent Details\n\nThe below components are built into `deepagents` and helps make it work for deep tasks off-the-shelf.\n\n### System Prompt\n\n`deepagents` comes with a [built-in system prompt](src/prompts.ts). This is relatively detailed prompt that is heavily based on and inspired by [attempts](https://github.com/kn1026/cc/blob/main/claudecode.md) to [replicate](https://github.com/asgeirtj/system_prompts_leaks/blob/main/Anthropic/claude-code.md)\nClaude Code's system prompt. It was made more general purpose than Claude Code's system prompt.\nThis contains detailed instructions for how to use the built-in planning tool, file system tools, and sub agents.\nNote that part of this system prompt [can be customized](#promptprefix--required-)\n\nWithout this default system prompt - the agent would not be nearly as successful at going as it is.\nThe importance of prompting for creating a \"deep\" agent cannot be understated.\n\n### Planing Tool\n\n`deepagents` comes with a built-in planning tool. This planning tool is very simple and is based on ClaudeCode's TodoWrite tool.\nThis tool doesn't actually do anything - it is just a way for the agent to come up with a plan, and then have that in the context to help keep it on track.\n\n### File System Tools\n\n`deepagents` comes with four built-in file system tools: `ls`, `edit_file`, `read_file`, `write_file`.\nThese do not actually use a file system - rather, they mock out a file system using LangGraph's State object.\nThis means you can easily run many of these agents on the same machine without worrying that they will edit the same underlying files.\n\nRight now the \"file system\" will only be one level deep (no sub directories).\n\nThese files can be passed in (and also retrieved) by using the `files` key in the LangGraph State object.\n\n```js\nimport { createDeepAgent } from \"deepagents\";\n\nconst agent = createDeepAgent({\n    instructions: researchInstructions,\n    subagents: [critiqueSubAgent, researchSubAgent],\n    tools: [internetSearch],\n});\n\nconst result = await agent.invoke({\n    messages: [new HumanMessage(\"what is langchain?\")],\n    files: [{\"README.md\": \"# Deep Agents\\n\\nThis is a README file for the deep agents example.\"}],\n});\n\n# Access any files afterwards like this\nresult.files\n```\n\n### Sub Agents\n\n`deepagents` comes with the built-in ability to call sub agents (based on Claude Code).\nIt has access to a `general-purpose` subagent at all times - this is a subagent with the same instructions as the main agent and all the tools that is has access to.\nYou can also specify [custom sub agents](#subagents--optional-) with their own instructions and tools.\n\nSub agents are useful for [\"context quarantine\"](https://www.dbreunig.com/2025/06/26/how-to-fix-your-context.html#context-quarantine) (to help not pollute the overall context of the main agent)\nas well as custom instructions.\n\n## Roadmap\n\n-   [ ] Allow users to customize full system prompt\n-   [ ] Code cleanliness (type hinting, docstrings, formating)\n-   [ ] Allow for more of a robust virtual filesystem\n-   [ ] Create an example of a deep coding agent built on top of this\n-   [ ] Benchmark the example of [deep research agent](src/examples/research/agent.ts)\n-   [ ] Add human-in-the-loop support for tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshelex%2Fdeepagents-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshelex%2Fdeepagents-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshelex%2Fdeepagents-ts/lists"}