{"id":24161563,"url":"https://github.com/zcaceres/easy-agent","last_synced_at":"2025-07-23T18:33:14.659Z","repository":{"id":253476095,"uuid":"843622787","full_name":"zcaceres/easy-agent","owner":"zcaceres","description":"A very easy framework to make and use tool-wielding AI Agents in Typescript","archived":false,"fork":false,"pushed_at":"2024-12-14T21:36:00.000Z","size":329,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-14T22:26:13.312Z","etag":null,"topics":["agents","ai","anthropic-ai","anthropic-claude","cli","command-line-tool","framework","typescript","typescript-library"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/zcaceres.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}},"created_at":"2024-08-17T00:00:33.000Z","updated_at":"2024-12-14T21:36:04.000Z","dependencies_parsed_at":"2024-08-30T00:13:47.930Z","dependency_job_id":null,"html_url":"https://github.com/zcaceres/easy-agent","commit_stats":null,"previous_names":["zcaceres/easy-agent"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Feasy-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Feasy-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Feasy-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcaceres%2Feasy-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zcaceres","download_url":"https://codeload.github.com/zcaceres/easy-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233634069,"owners_count":18705953,"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","ai","anthropic-ai","anthropic-claude","cli","command-line-tool","framework","typescript","typescript-library"],"created_at":"2025-01-12T17:17:21.266Z","updated_at":"2025-07-23T18:33:14.645Z","avatar_url":"https://github.com/zcaceres.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# easy-agent\n\n![easy-agent logo](logo.jpg)\n\n![NPM Version](https://img.shields.io/npm/v/easy-agent)\n\n## What?\n\nA very simple Typescript framework to build tool-wielding AI Agents.\n\n`easy-agent` is a powerful, lightweight TypeScript framework designed for building AI agents with tool-use capabilities and prompt-caching. It supports Anthropic's Claude family of models.\n\n## Why?\n\n- **Simple**: There's too much plumbing and setup in vanilla AI SDKs. You spend more time parsing JSON than iterating on your agent.\n- **Typescript First**: TS \u003e Python if you're already working in web apps.\n- **Minimal**: You only need two concepts to make an awesome AI Agent: Agents and Tools. This package hides everything else and focuses on a good experience with those two concepts.\n\n## Features\n\n- Hides configuration and plumbing behind two simple typesafe `Agent` and `Tool` classes.\n- Start making a custom Agent with one function call in one file: `start-here.ts`.\n- Sensible defaults which you can easily override\n- Automatically handles the tool request/response cycle\n- Supports message \u0026 stream modes\n- Vigorous type-safety\n- A few fun pre-baked Agents\n- Use Agents in either CLI and Server Modes\n- Prompt caching support\n\n## Setup\n\n\u003e Make sure you have an ANTHROPIC_API_KEY key in your environment.\n\nInstall:\n\n```bash\nbun install\n```\n\nRun:\n\n```bash\nbun start\n```\n\n## Usage\n\nYou can use `easy-agent` as project boilerplate or as a library.\n\n\n### Using As Project Boilerplate\n\n#### Starting in CLI Mode\n\nSee `example.cli.ts` for a typical project setup in CLI Mode.\n\nCLI Mode allows you to interact with your agents in a simple command-line interface.\n\nStart it with `bun run start` or `bun run cli`.\n\n#### Starting in Server Mode\n\nServer Mode runs an Express server, allowing interaction with agents via HTTP requests.\n\nSee `example.server.ts` for a typical project setup in Server Mode.\n\n1. Start the server:\n\n   ```bash\n   bun run server\n   ```\n\n2. The server will start on `http://localhost:3000`.\n\n3. Interact with agents via HTTP:\n\nList available agents:\n```bash\ncurl http://localhost:3000\n```\n\nSend a message to an agent:\n```bash\ncurl -X POST http://localhost:3000 -H \"Content-Type: application/json\" \\\n    -d '{\"agentName\": \"summarizer\", \"message\": \"Summarize this: https://example.com\"}'\n```\n\nNote: Server Mode currently supports stateless interactions only. You'll need to handle state on the client side.\n\n### Using As a Library\n\nYou can use `easy-agent` as a library in your project.\n\nFirst, import an `EasyAgentCLI` or `EasyAgentServer` mode from `easy-agent`. Then, create an instance of that mode and pass your agents to it.\n\n```typescript\nimport { EasyAgentCLI, Agent } from \"easy-agent\";\n\nEasyAgentCLI.start([\n  Agent.create({\n    name: \"MyAgent\",\n    prompt: \"I am a helpful assistant that...\",\n    tools: [MyCustomTool],\n  }),\n]);\n\n```\n\nThis will start a CLI session with any agents you register in the array.\n\n## How to Make an Agent\n\nThe simplest possible way to make an agent is to call `bun run add-agent` and follow the prompts.\n\nYou can also check out `example.cli.ts` and add code like the following:\n\n```typescript\nAgent.create({\n  name: \"Dad Joke Agent\",\n  prompt: \"I tell Dad Jokes and only Dad Jokes\"\n})\n```\n\nNow type `bun start` and `dad-joke-agent` will be available to use.\n\nFor more advanced use cases, you can follow patterns in the `agents` and `tools` directories:\n\n1. Create a new file in the `agents` directory, e.g., `agents/my-agent.ts`:\n\n   ```typescript\n   import Agent from \"src/lib/agent\";\n   import MyCustomTool from \"src/tools/my-custom-tool\";\n\n   const MY_PROMPT = `You are a helpful assistant that...`;\n\n   export default Agent.create({\n     name: \"MyAgent\",\n     prompt: MY_PROMPT,\n     tools: [MyCustomTool],\n     // Optionally customize other settings...\n     // mode: \"stream\",\n     // model: \"claude-3-opus-20240229\",\n     // maxTokens: 4000,\n     // cacheOptions: [\"system\", \"tools\"],\n   });\n   ```\n\n2. Register your agent wherever you've called an EasyAgent mode (see `example.cli.ts`):\n\n   ```typescript\n   import { EasyAgentCLI } from \"easy-agent/modes\";\n   import MyAgent from \"easy-agent/agents/my-agent\";\n\n   EasyAgentCLI.start([\n     // ... other agents\n     MyAgent,\n   ]);\n   ```\n\n3. Your agent is now available in both CLI and Server modes!\n\nTo create more complex agents:\n- Add custom tools in the `tools` directory\n- Experiment with different prompts and configurations\n- Use the `cacheOptions` to optimize performance for frequently used contexts\n\n## How to Make a Tool\n\nThe simplest possible way to make an agent is to call `bun run add-tool` and follow the prompts.\n\n1. Create a new file in the `tools` directory, e.g., `tools/my-custom-tool.ts`:\n\n   ```typescript\n   import Tool from \"src/lib/tool\";\n\n   async function fetchWeather(city: string): Promise\u003cstring\u003e {\n     // Implement weather fetching logic here\n     return `The weather in ${city} is sunny.`;\n   }\n\n   export default Tool.create({\n     name: \"fetch_weather\",\n     description: \"Fetch current weather for a given city\",\n     inputs: [\n       {\n         name: \"city\",\n         type: \"string\",\n         description: \"The name of the city\",\n         required: true,\n       },\n     ],\n     fn: async ({ city }: { city: string }) =\u003e {\n       const weather = await fetchWeather(city);\n       return { weather };\n     },\n   });\n   ```\n\n2. Import and use your tool in an agent:\n\n   ```typescript\n   // in agents/weather-agent.ts\n   import Agent from \"src/lib/agent\";\n   import FetchWeather from \"src/tools/my-custom-tool\";\n\n   export default Agent.create({\n     name: \"WeatherAgent\",\n     prompt: \"You are a helpful weather assistant. Use the fetch_weather tool to provide accurate weather information.\",\n     tools: [FetchWeather],\n   });\n   ```\n\n3. Register your new agent in `start-here.ts` to make it available. Your agent will not intelligently use the tool.\n\nTips for creating effective tools:\n- Provide clear, concise descriptions for your tool and its inputs.\n- Handle errors gracefully and return informative error messages.\n- Consider adding type definitions for complex input/output structures.\n\n### Toolmaker Mode\n\neasy-agent comes bundled with an agent named Toolmaker, which can make tools for your agents.\n\nTo use:\n\n1. Start easy-agent in CLI mode: `bun run start`.\n2. Select `toolmaker`\n3. Tell it the kind of tool you want e.g. `Create a tool that fetches the current price of Bitcoin`\n4. The tool will appear in the `tools` directory.\n5. Fix up the tool as needed.\n6. Import the tool into your agent.\n\nToolmaker writes all tools in Typescript. It can also fetch data from websites if needed, so feel free to send in a url for API docs or other data sources.\n\n#### Important\n\u003e Toolmaker creates tools but does not use them immediately. You'll need to manually import and add new tools to your agents.\n\u003e Always review and test automatically generated tools before using them in production environments.\n\n## Other Agent Examples\n\nHere are some more advanced examples of agent configurations:\n\n### Streaming Agent with Model Override\n\n```typescript\nexport default Agent.create({\n  name: \"StreamingExpert\",\n  prompt: \"You are an AI that provides real-time analysis of streaming data.\",\n  mode: \"stream\",\n  model: \"claude-3-opus-20240229\",\n  maxTokens: 4000,\n  tools: [StreamDataAnalyzer, DataVisualizer],\n});\n```\n\n### Multi-Tool Agent with Caching\n\n```typescript\nexport default Agent.create({\n  name: \"ResearchAssistant\",\n  prompt: \"You are a research assistant capable of gathering and analyzing information from multiple sources.\",\n  tools: [WebSearchTool, PDFExtractor, DataAnalyzer, CitationGenerator],\n  cacheOptions: [\"system\", \"tools\"],\n  maxTokens: 8000,\n});\n```\n\n### Specialized Agent with Custom Configuration\n\n```typescript\nexport default Agent.create({\n  name: \"CodeReviewer\",\n  prompt: \"You are an expert code reviewer. Analyze code snippets for best practices, potential bugs, and suggest improvements.\",\n  tools: [CodeParser, StaticAnalyzer, BenchmarkTool],\n  model: \"claude-3-opus-20240229\",\n  maxTokens: 16000,\n  cacheOptions: [\"system\"],\n});\n```\n\n## Prompt Caching\n\nEasy-agent supports Anthropic's prompt caching feature, which can significantly improve response times and reduce token usage for repeated interactions.\n\n### How Caching Works\n\nPrompt caching allows certain parts of the context to be stored on Anthropic's servers, reducing the need to resend this information with each request. In easy-agent, caching is implemented with a focus on efficiency and adherence to Anthropic's limits.\n\n### Caching Order and Priority\n\n1. **System Prompt**: The system prompt is cached first, as it's typically the most static and frequently used part of the context.\n\n2. **Tools**: After the system prompt, tools are cached in the order they are configured in the agent. This ensures that the most important or frequently used tools are prioritized for caching.\n\n### Caching Limits\n\nAnthropic imposes a limit on the number of items that can be cached (currently set to `globals.ANTHROPIC_MAX_PROMPT_CACHE_SIZE`). Easy-agent respects this limit by:\n\n- Caching the system prompt first (if enabled)\n- Caching tools in order until the limit is reached\n- Stopping cache attempts for additional tools once the limit is hit\n\n### Enabling Caching\n\nTo enable caching for your agent, use the `cacheOptions` parameter in your agent configuration:\n\n```typescript\nAgent.create({\n  name: \"CachedAgent\",\n  prompt: \"Your prompt here\",\n  tools: [Tool1, Tool2, Tool3],\n  cacheOptions: [\"system\", \"tools\"],\n  // ... other configurations\n});\n```\n\nThis setup will cache both the system prompt and tools, in that order, up to the Anthropic-imposed limit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzcaceres%2Feasy-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzcaceres%2Feasy-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzcaceres%2Feasy-agent/lists"}