{"id":40245183,"url":"https://github.com/agentage/agentkit","last_synced_at":"2026-01-20T00:09:38.375Z","repository":{"id":322855832,"uuid":"1087946343","full_name":"agentage/agentkit","owner":"agentage","description":"Complete AI agent toolkit - fluent API, CLI, and core in one monorepo","archived":false,"fork":false,"pushed_at":"2026-01-12T22:56:35.000Z","size":979,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-13T02:50:14.268Z","etag":null,"topics":["agent","agent-kit","agent-sdk"],"latest_commit_sha":null,"homepage":"","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/agentage.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-02T01:02:39.000Z","updated_at":"2026-01-12T22:56:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"057d4a47-70ae-48c2-95b1-f601a1eeef65","html_url":"https://github.com/agentage/agentkit","commit_stats":null,"previous_names":["agentage/agentkit"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/agentage/agentkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentage%2Fagentkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentage%2Fagentkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentage%2Fagentkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentage%2Fagentkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentage","download_url":"https://codeload.github.com/agentage/agentkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentage%2Fagentkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28590676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T00:01:37.455Z","status":"ssl_error","status_checked_at":"2026-01-19T23:58:17.328Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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","agent-kit","agent-sdk"],"created_at":"2026-01-20T00:09:37.569Z","updated_at":"2026-01-20T00:09:38.368Z","avatar_url":"https://github.com/agentage.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentKit\n\n[![npm version](https://img.shields.io/npm/v/@agentage/sdk.svg)](https://www.npmjs.com/package/@agentage/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/agentage/agentkit/actions/workflows/ci.yml/badge.svg)](https://github.com/agentage/agentkit/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/agentage/agentkit/branch/master/graph/badge.svg)](https://codecov.io/gh/agentage/agentkit)\n\n\n\n## Table of contents\n- [AgentKit](#agentkit)\n  - [Table of contents](#table-of-contents)\n  - [Installation](#installation)\n  - [Features](#features)\n  - [Quick Start](#quick-start)\n  - [More Examples](#more-examples)\n  - [Philosophy](#philosophy)\n  - [API Reference](#api-reference)\n    - [Core API Patterns](#core-api-patterns)\n      - [Pattern 1: Builder (Express-like)](#pattern-1-builder-express-like)\n      - [Pattern 2: Config Object](#pattern-2-config-object)\n    - [Defining Tools](#defining-tools)\n  - [Troubleshooting](#troubleshooting)\n  - [FAQ](#faq)\n  - [Contributing](#contributing)\n    - [Running Tests](#running-tests)\n  - [License](#license)\n\n## Installation\n\nThis is a [Node.js](https://nodejs.org/en/) module available through the [npm registry](https://www.npmjs.com/).\n\nBefore installing, [download and install Node.js](https://nodejs.org/en/download/). Node.js 20 or higher is required.\n\nInstallation is done using the [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):\n\n```bash\nnpm install @agentage/sdk\n```\n\n## Features\n\n- **Functional API** - Fast and reliable - with no state management\n- **Builder pattern** - Builder chainable API\n- **Type-safe tools** - Zod-based schema validation\n- **Multiple models** - Support for OpenAI, Anthropic, and custom adapters\n- **Zero configuration** - Start building agents immediately\n\n## Quick Start\n\n```typescript\nimport { agent } from '@agentage/sdk';\n\nconst assistant = agent('assistant')\n  .model('gpt-4', { temperature: 0.7 })\n  .instructions('You are a helpful assistant')\n  .tools([searchTool, calculatorTool]);\n\nconst result = await assistant.send('Help me with this task');\nconsole.log(result.content);\n```\n\n## More Examples\n\n### 1. Simple Q\u0026A Agent\n\n```typescript\nimport { agent } from '@agentage/sdk';\n\nconst qa = agent('qa-bot')\n  .model('gpt-4')\n  .instructions('Answer questions concisely and accurately');\n\nconst answer = await qa.send('What is TypeScript?');\nconsole.log(answer.content);\n```\n\n### 2. Code Reviewer\n\n```typescript\nimport { agent, tool } from '@agentage/sdk';\nimport { z } from 'zod';\nimport { readFile } from 'fs/promises';\n\nconst readFileTool = tool(\n  {\n    name: 'read_file',\n    description: 'Read a file from disk',\n    inputSchema: {\n      path: z.string().describe('File path to read')\n    }\n  },\n  async ({ path }) =\u003e {\n    return await readFile(path, 'utf-8');\n  }\n);\n\nconst reviewer = agent('code-reviewer')\n  .model('gpt-4')\n  .instructions('Review code for bugs, security issues, and best practices')\n  .tools([readFileTool]);\n\nconst review = await reviewer.send('Review src/index.ts');\nconsole.log(review.content);\n```\n\n### 3. Data Analyzer\n\n```typescript\nimport { agent, tool } from '@agentage/sdk';\nimport { z } from 'zod';\n\nconst fetchDataTool = tool(\n  {\n    name: 'fetch_data',\n    description: 'Fetch data from API',\n    inputSchema: {\n      endpoint: z.string(),\n      params: z.record(z.string()).optional()\n    }\n  },\n  async ({ endpoint, params }) =\u003e {\n    const url = new URL(endpoint);\n    if (params) {\n      Object.entries(params).forEach(([key, value]) =\u003e {\n        url.searchParams.append(key, value);\n      });\n    }\n    const response = await fetch(url.toString());\n    return response.json();\n  }\n);\n\nconst calculateStatsTool = tool(\n  {\n    name: 'calculate_stats',\n    description: 'Calculate statistics on numeric data',\n    inputSchema: {\n      data: z.array(z.number()),\n      metrics: z.array(z.enum(['mean', 'median', 'sum', 'min', 'max']))\n    }\n  },\n  async ({ data, metrics }) =\u003e {\n    const stats: Record\u003cstring, number\u003e = {};\n    if (metrics.includes('mean')) {\n      stats.mean = data.reduce((a, b) =\u003e a + b, 0) / data.length;\n    }\n    if (metrics.includes('sum')) {\n      stats.sum = data.reduce((a, b) =\u003e a + b, 0);\n    }\n    if (metrics.includes('min')) {\n      stats.min = Math.min(...data);\n    }\n    if (metrics.includes('max')) {\n      stats.max = Math.max(...data);\n    }\n    return stats;\n  }\n);\n\nconst analyzer = agent('data-analyzer')\n  .model('gpt-4')\n  .instructions('Analyze data and provide insights')\n  .tools([fetchDataTool, calculateStatsTool]);\n\nconst result = await analyzer.send('Analyze sales data for Q4 2024');\nconsole.log(result.content);\n```\n\n### 4. Multi-step Workflow\n\n```typescript\nconst workflow = agent('workflow')\n  .model('gpt-4')\n  .instructions('Execute multi-step tasks systematically')\n  .tools([searchWebTool, readFileTool, writeFileTool, sendEmailTool]);\n\nawait workflow.send('Research AI trends, create summary, and email to team');\n```\n\n### 5. Custom Model Configuration\n\n```typescript\n// More creative (higher temperature)\nconst creative = agent('writer')\n  .model('gpt-4', {\n    temperature: 0.9,\n    max_tokens: 2000,\n    top_p: 1.0\n  })\n  .instructions('Write creative and engaging content');\n\n// More deterministic (lower temperature)\nconst analyst = agent('analyst')\n  .model('gpt-4', {\n    temperature: 0.1,\n    max_tokens: 1000\n  })\n  .instructions('Provide precise, factual analysis');\n```\n\n## Philosophy\n\nThe AgentKit philosophy is to provide small, functional tooling for building AI agents, making it a great solution for chatbots, automation, data processing, or AI-powered applications.\n\nAgentKit does not force you to use any specific model or tool. With support for multiple model providers and custom adapters, you can quickly craft your perfect AI workflow.\n\n## API Reference\n\n### Core API Patterns\n\n#### Pattern 1: Builder (Express-like)\n\n```typescript\nconst assistant = agent('assistant')\n  .model('gpt-4', { temperature: 0.7 })\n  .instructions('You are a helpful assistant')\n  .tools([searchTool, calculatorTool]);\n\nawait assistant.send('Help me with this');\n```\n\n#### Pattern 2: Config Object\n\n```typescript\nconst assistant = agent({\n  name: 'assistant',\n  model: {\n    name: 'gpt-4',\n    config: {\n      temperature: 0.7\n    }\n  },\n  instructions: 'You are a helpful assistant',\n  tools: [searchTool, calculatorTool]\n});\n\nawait assistant.send('Help me with this');\n```\n\nBoth patterns produce the same result - choose based on preference.\n\n### Defining Tools\n\n```typescript\nimport { tool } from '@agentage/sdk';\nimport { z } from 'zod';\n\nconst githubTool = tool(\n  {\n    name: 'github',\n    title: 'GitHub Tool',\n    description: 'Access GitHub repositories',\n    inputSchema: {\n      repo: z.string(),\n      action: z.enum(['get', 'list', 'search'])\n    }\n  },\n  async ({ repo, action }) =\u003e {\n    const response = await fetch(`https://api.github.com/repos/${repo}`);\n    return response.json();\n  }\n);\n\nconst databaseTool = tool(\n  {\n    name: 'database',\n    title: 'Database Tool',\n    description: 'Query database',\n    inputSchema: {\n      query: z.string(),\n      limit: z.number().optional() \n    }\n  },\n  async ({ query, limit = 10 }) =\u003e {\n    return await db.execute(query, { limit });\n  }\n);\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Error: \"OpenAI API key not found\"\n\n**Solution**: Set your API key in environment variables\n\n```bash\nexport OPENAI_API_KEY='sk-...'\n```\n\nOr use a `.env` file:\n\n```env\nOPENAI_API_KEY=sk-your-key-here\n```\n\n```typescript\nimport 'dotenv/config';\nimport { agent } from '@agentage/sdk';\n```\n\n#### Error: \"Tool execution failed\"\n\n**Causes**:\n- Invalid tool schema\n- Missing required parameters\n- Tool handler threw exception\n\n**Solution**: Check tool definition and handler implementation\n\n```typescript\n// ✅ Correct\nconst myTool = tool(\n  {\n    name: 'my_tool',\n    description: 'Clear description of what the tool does',\n    inputSchema: {\n      param: z.string()  // Explicit schema\n    }\n  },\n  async (input) =\u003e {\n    // Handle errors gracefully\n    try {\n      return await doSomething(input.param);\n    } catch (error) {\n      throw new Error(`Tool failed: ${error.message}`);\n    }\n  }\n);\n```\n\n#### Error: \"Agent not responding\"\n\n**Causes**:\n- Model name incorrect\n- API quota exceeded\n- Network issues\n- Invalid API key\n\n**Solution**: Check model name and API status\n\n```typescript\n// ✅ Correct model names\n.model('gpt-4')\n.model('gpt-3.5-turbo')\n\n// ❌ Incorrect\n.model('gpt4')  // Missing hyphen\n.model('GPT-4')  // Wrong case\n```\n\n#### Build Errors\n\n```bash\n# Clean and rebuild\nnpm run clean\nnpm install\nnpm run build\n```\n\n#### Type Errors\n\nMake sure you have the correct TypeScript version:\n\n```bash\nnpm install -D typescript@^5.3.0\n```\n\n### Getting Help\n\n- **Documentation**: [docs/](./docs/)\n- **GitHub Issues**: [Report bugs](https://github.com/agentage/agentkit/issues)\n- **GitHub Discussions**: [Ask questions](https://github.com/agentage/agentkit/discussions)\n- **API Reference**: [docs/api-reference.md](./docs/api-reference.md)\n\n## FAQ\n\n### Can I use models other than OpenAI?\n\nYes! AgentKit supports multiple model providers:\n- **OpenAI** (built-in via `@agentage/model-openai`)\n- **Anthropic** (coming soon)\n- **Custom adapters** (implement `ModelProvider` interface from `@agentage/core`)\n\n### How do I create custom tools?\n\nUse the `tool()` function with Zod schemas:\n\n```typescript\nimport { tool } from '@agentage/sdk';\nimport { z } from 'zod';\n\nconst myTool = tool(\n  {\n    name: 'my_tool',\n    description: 'What the tool does',\n    inputSchema: {\n      param1: z.string().describe('Description of param1'),\n      param2: z.number().optional().describe('Optional parameter')\n    }\n  },\n  async (input) =\u003e {\n    // Your logic here\n    return result;\n  }\n);\n```\n\nSee [docs/tool-development.md](./docs/tool-development.md) for more details.\n\n### Can I use this in production?\n\nYes, but be aware of:\n- **API costs**: AI model calls can add up quickly\n- **Rate limiting**: Monitor your API usage\n- **Error handling**: Implement robust error handling\n- **Monitoring**: Track usage and costs\n- **Security**: Never expose API keys in client-side code\n\n### How do I contribute?\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for complete guidelines.\n\n### What's the difference between builder and config patterns?\n\nBoth patterns work identically - choose based on your preference:\n\n```typescript\n// Builder pattern (chainable)\nconst a1 = agent('name')\n  .model('gpt-4')\n  .instructions('...');\n\n// Config pattern (object)\nconst a2 = agent({\n  name: 'name',\n  model: { name: 'gpt-4' },\n  instructions: '...'\n});\n```\n\n### How do I handle streaming responses?\n\nStreaming is not currently supported in v0.1.x. This feature is planned for a future release.\n\n### Can I save agent state?\n\nAgent execution is stateless by design. For persistence:\n- Save agent definitions in YAML files (use CLI)\n- Store conversation history separately\n- Implement custom state management as needed\n\n### What Node.js version do I need?\n\nNode.js 20.0.0 or higher is required.\n\n### How do I test my agents?\n\nWrite unit tests using Jest or your preferred testing framework:\n\n```typescript\nimport { describe, it, expect } from '@jest/globals';\nimport { agent } from '@agentage/sdk';\n\ndescribe('my agent', () =\u003e {\n  it('should respond correctly', async () =\u003e {\n    const myAgent = agent('test')\n      .model('gpt-4')\n      .instructions('Be helpful');\n    \n    const result = await myAgent.send('Hello');\n    expect(result.content).toBeDefined();\n  });\n});\n```\n\n## Contributing\n\nThe AgentKit project welcomes all constructive contributions.\n\n### Running Tests\n\nTo run the test suite, first install the dependencies:\n\n```bash\nnpm install\n```\n\nThen run `npm test`:\n\n```bash\nnpm test\n```\n\n## License\n\n[MIT](https://github.com/agentage/agentkit/blob/master/LICENSE)\n\n---\n\n**Simple. Functional. Powerful.**\n\nBuilt with ❤️ by the Agentage team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentage%2Fagentkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentage%2Fagentkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentage%2Fagentkit/lists"}