{"_id":"@agenkit/core","name":"@agenkit/core","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@agenkit/core","version":"0.2.0","description":"Minimal, composable interfaces for AI agents - TypeScript implementation","keywords":["ai","agents","llm","framework","typescript","openai","anthropic","claude"],"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","watch":"tsc --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src/**/*.ts","format":"prettier --write \"src/**/*.ts\"","prepublishOnly":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/scttfrdmn/agenkit.git","directory":"agenkit-ts"},"author":{"name":"Scott Freedman"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"@anthropic-ai/sdk":"^0.28.0","@grpc/grpc-js":"^1.14.1","@grpc/proto-loader":"^0.8.0","openai":"^4.67.0","ws":"^8.18.0"},"devDependencies":{"@types/google-protobuf":"^3.15.12","@types/jest":"^29.5.11","@types/node":"^20.10.0","@types/ws":"^8.5.10","@typescript-eslint/eslint-plugin":"^6.15.0","@typescript-eslint/parser":"^6.15.0","@vitest/coverage-v8":"^4.0.9","@vitest/ui":"^4.0.9","eslint":"^8.56.0","prettier":"^3.1.1","typescript":"^5.3.3","vitest":"^4.0.9"},"gitHead":"1094eac1eac0e0291874faa3ab0b301464147dd6","_id":"@agenkit/core@0.2.0","bugs":{"url":"https://github.com/scttfrdmn/agenkit/issues"},"homepage":"https://github.com/scttfrdmn/agenkit#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-E6o7etl17BQJi5oIKFXXVhmp5zKZjhm/+ZOU/9T8NbttdIIs9Amj8eGDeKIwjrGb2RfAlNnhwdmWIFhBFbgyjw==","shasum":"9dea16947948a4f57892cb4364b4f79bc4adf314","tarball":"https://registry.npmjs.org/@agenkit/core/-/core-0.2.0.tgz","fileCount":51,"unpackedSize":160071,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDl45v+YE1hH3nK7E5Zm8B2v3DMlW4+phXZeozmAuQxzAIhAPD9ZZkuG5ca6eSjFsxJH6eGsV1xop+8q3yNa2pdzrUY"}]},"_npmUser":{"name":"scttfrdmn","email":"scttfrdmn@gmail.com"},"directories":{},"maintainers":[{"name":"scttfrdmn","email":"scttfrdmn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.2.0_1763973347003_0.2914917054819477"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-24T08:35:46.904Z","0.2.0":"2025-11-24T08:35:47.174Z","modified":"2025-11-24T08:35:47.595Z"},"maintainers":[{"name":"scttfrdmn","email":"scttfrdmn@gmail.com"}],"description":"Minimal, composable interfaces for AI agents - TypeScript implementation","homepage":"https://github.com/scttfrdmn/agenkit#readme","keywords":["ai","agents","llm","framework","typescript","openai","anthropic","claude"],"repository":{"type":"git","url":"git+https://github.com/scttfrdmn/agenkit.git","directory":"agenkit-ts"},"author":{"name":"Scott Freedman"},"bugs":{"url":"https://github.com/scttfrdmn/agenkit/issues"},"license":"MIT","readme":"# @agenkit/core\n\nMinimal, composable interfaces for AI agents in TypeScript.\n\n## Features\n\n- **Minimal API**: Only 2 required methods per agent (`name`, `process`)\n- **Type Safe**: Full TypeScript support with comprehensive type definitions\n- **Composable**: Easy middleware pattern for retry, timeout, caching, etc.\n- **Transport Agnostic**: HTTP, WebSocket, gRPC support\n- **LLM Ready**: Built-in adapters for OpenAI, Anthropic (Claude)\n- **Production Ready**: Middleware for resilience, observability, and control\n\n## Installation\n\n```bash\nnpm install @agenkit/core\n```\n\n## Quick Start\n\n### Local Agent\n\n```typescript\nimport { LocalAgent, createMessage } from '@agenkit/core';\n\nconst agent = new LocalAgent({\n  name: 'greeter',\n  process: async (message) => ({\n    role: 'assistant',\n    content: `Hello, ${message.content}!`,\n  }),\n});\n\nconst response = await agent.process(createMessage('user', 'World'));\nconsole.log(response.content); // \"Hello, World!\"\n```\n\n### OpenAI Agent\n\n```typescript\nimport { OpenAIAgent } from '@agenkit/core';\n\nconst agent = new OpenAIAgent({\n  apiKey: process.env.OPENAI_API_KEY!,\n  model: 'gpt-4o',\n});\n\nconst response = await agent.process({\n  role: 'user',\n  content: 'What is the capital of France?',\n});\n\nconsole.log(response.content); // \"The capital of France is Paris.\"\n```\n\n### Anthropic (Claude) Agent\n\n```typescript\nimport { AnthropicAgent } from '@agenkit/core';\n\nconst agent = new AnthropicAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY!,\n  model: 'claude-sonnet-4-20250514',\n});\n\nconst response = await agent.process({\n  role: 'user',\n  content: 'Explain TypeScript in one sentence.',\n});\n\nconsole.log(response.content);\n```\n\n### HTTP Transport\n\n```typescript\nimport { HTTPAgent } from '@agenkit/core';\n\nconst agent = new HTTPAgent({\n  baseUrl: 'http://localhost:8000',\n});\n\nconst response = await agent.process({\n  role: 'user',\n  content: 'Hello',\n});\n```\n\n### WebSocket Transport\n\n```typescript\nimport { WebSocketAgent } from '@agenkit/core';\n\nconst agent = new WebSocketAgent({\n  url: 'ws://localhost:8080',\n  maxRetries: 5,\n  pingInterval: 30000,\n});\n\nawait agent.connect();\n\nconst response = await agent.process({\n  role: 'user',\n  content: 'Hello',\n});\n\nawait agent.close();\n```\n\n### gRPC Transport\n\nHigh-performance RPC with Protocol Buffers:\n\n```typescript\nimport { GrpcAgent, GrpcServer } from '@agenkit/core';\n\n// Client\nconst client = new GrpcAgent('my-service', {\n  address: 'localhost:50051',\n  timeout: 5000,\n  useTLS: false,\n});\n\nconst response = await client.process({\n  role: 'user',\n  content: 'Hello',\n});\n\nawait client.close();\n\n// Server\nconst server = new GrpcServer(myAgent, {\n  address: '0.0.0.0:50051',\n  useTLS: false,\n});\n\nawait server.start();\n// ... handle requests ...\nawait server.stop();\n```\n\n### Middleware\n\nApply retry, timeout, or custom middleware:\n\n```typescript\nimport { LocalAgent, applyMiddleware, retry, timeout } from '@agenkit/core';\n\nconst baseAgent = new LocalAgent({\n  name: 'flaky',\n  process: async (msg) => {\n    // May fail occasionally\n    if (Math.random() < 0.3) throw new Error('Network error');\n    return { role: 'assistant', content: 'Success!' };\n  },\n});\n\n// Apply retry and timeout middleware\nconst robustAgent = applyMiddleware(baseAgent, [\n  retry({ maxAttempts: 3, initialDelay: 1000 }),\n  timeout({ timeout: 5000 }),\n]);\n\nconst response = await robustAgent.process({\n  role: 'user',\n  content: 'Hello',\n});\n```\n\n### Streaming\n\nStream responses for real-time interaction:\n\n```typescript\nimport { OpenAIAgent } from '@agenkit/core';\n\nconst agent = new OpenAIAgent({\n  apiKey: process.env.OPENAI_API_KEY!,\n});\n\nfor await (const chunk of agent.processStream({\n  role: 'user',\n  content: 'Count from 1 to 10',\n})) {\n  process.stdout.write(chunk.content);\n}\n```\n\n## Core Interfaces\n\n### Agent\n\n```typescript\ninterface Agent {\n  name: string;\n  process(message: Message): Promise<Message>;\n  processStream?(message: Message): AsyncGenerator<Message>;\n  capabilities?: string[];\n}\n```\n\n### Message\n\n```typescript\ninterface Message {\n  role: string; // \"user\", \"assistant\", \"system\", \"tool\"\n  content: unknown; // string, object, array, etc.\n  metadata?: Record<string, unknown>;\n  timestamp?: string; // ISO 8601\n}\n```\n\n### Tool\n\n```typescript\ninterface Tool {\n  name: string;\n  description: string;\n  parametersSchema?: Record<string, unknown>;\n  execute(params: Record<string, unknown>): Promise<ToolResult>;\n}\n```\n\n## Adapters\n\n- **LocalAgent**: Wrap TypeScript functions as agents\n- **HTTPAgent**: Communicate over HTTP/REST\n- **WebSocketAgent**: Real-time bidirectional communication\n- **GrpcAgent**: High-performance gRPC transport ✨ NEW\n- **OpenAIAgent**: OpenAI Chat Completion API (GPT-4, GPT-3.5)\n- **AnthropicAgent**: Anthropic Messages API (Claude 3)\n\n## Middleware\n\n- **retry**: Automatic retries with exponential backoff\n- **timeout**: Prevent long-running requests\n- **circuitBreaker**: Fail fast when service is unhealthy\n- **Custom**: Easy to implement your own\n\n## Why Agenkit?\n\n### Minimal\n\nOnly 2 required methods per agent. No complex inheritance, no framework lock-in.\n\n### Composable\n\nMiddleware pattern allows easy wrapping for cross-cutting concerns.\n\n### Type Safe\n\nFull TypeScript support with comprehensive type definitions.\n\n### Production Ready\n\nBuilt-in resilience patterns and LLM integrations.\n\n## Examples\n\nSee `examples/` directory for complete, runnable examples:\n\n- **basic-usage.ts**: Simple getting started examples\n- **middleware-example.ts**: Production resilience patterns (retry, timeout, circuit breaker) ✨ NEW\n- **transport-comparison.ts**: HTTP vs WebSocket vs gRPC comparison ✨ NEW\n- **llm-integration.ts**: OpenAI & Anthropic integration with best practices ✨ NEW\n\nRun any example:\n\n```bash\nnpx ts-node examples/middleware-example.ts\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Test\nnpm test\n\n# Lint\nnpm run lint\n\n# Format\nnpm run format\n```\n\n## License\n\nMIT\n\n## Contributing\n\nSee [CONTRIBUTING.md](../../CONTRIBUTING.md) in the main repository.\n","readmeFilename":"README.md","_rev":"1-737ee622c629cb0eed9a394465232fb9"}