@robota-sdk/agent-core 3.0.0-beta.4 → 3.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +59 -181
  2. package/dist/browser/index.js +4 -4
  3. package/dist/node/index.cjs +4 -4
  4. package/dist/node/index.js +4 -4
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,33 +1,27 @@
1
1
  # @robota-sdk/agent-core
2
2
 
3
- The comprehensive AI agent framework with type-safe architecture and advanced plugin system.
4
-
5
- ## Overview
6
-
7
- The `@robota-sdk/agent-core` package is the unified core of the Robota SDK, providing a complete AI agent system with advanced capabilities for conversation management, tool execution, and extensible plugin architecture.
3
+ The foundation layer of the Robota SDK. Provides the `Robota` agent class, abstract base classes for providers/tools/plugins, the permission system, hook system, event services, and error hierarchy.
8
4
 
9
5
  ## Installation
10
6
 
11
7
  ```bash
12
8
  npm install @robota-sdk/agent-core
13
- # or
14
- pnpm add @robota-sdk/agent-core
15
9
  ```
16
10
 
17
11
  ## Quick Start
18
12
 
19
13
  ```typescript
20
14
  import { Robota } from '@robota-sdk/agent-core';
21
- import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
15
+ import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
22
16
 
23
- const openaiProvider = new OpenAIProvider({ apiKey: 'sk-...' });
17
+ const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });
24
18
 
25
19
  const agent = new Robota({
26
20
  name: 'MyAgent',
27
- aiProviders: [openaiProvider],
21
+ aiProviders: [provider],
28
22
  defaultModel: {
29
- provider: 'openai',
30
- model: 'gpt-4',
23
+ provider: 'anthropic',
24
+ model: 'claude-sonnet-4-6',
31
25
  systemMessage: 'You are a helpful assistant.',
32
26
  },
33
27
  });
@@ -36,194 +30,78 @@ const response = await agent.run('Hello, world!');
36
30
  console.log(response);
37
31
  ```
38
32
 
39
- ### Browser Quick Start
40
-
41
- ```typescript
42
- import { Robota, LoggingPlugin, UsagePlugin } from '@robota-sdk/agent-core';
43
- import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
44
-
45
- const openaiProvider = new OpenAIProvider({
46
- apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY, // or proxy endpoint
47
- });
48
-
49
- // Browser-optimized configuration
50
- const agent = new Robota({
51
- name: 'BrowserAgent',
52
- aiProviders: [openaiProvider],
53
- defaultModel: {
54
- provider: 'openai',
55
- model: 'gpt-3.5-turbo',
56
- },
57
- plugins: [
58
- new LoggingPlugin({ strategy: 'console' }), // Console logging
59
- new UsagePlugin({ strategy: 'memory' }), // Memory storage
60
- ],
61
- });
62
-
63
- const response = await agent.run('Hello from browser!');
64
- console.log(response);
65
- ```
66
-
67
33
  ## Key Features
68
34
 
69
- ### 🌐 Cross-Platform Compatibility
70
-
71
- - **Universal Runtime Support**: Works seamlessly in Node.js, browsers, and WebWorkers
72
- - **Zero Breaking Changes**: Existing Node.js code runs unchanged in browsers
73
- - **Pure JavaScript Implementation**: No Node.js-specific dependencies in core functionality
74
- - **Browser-Optimized Storage**: Memory-based alternatives for file system operations
75
- - **Secure API Patterns**: Proxy server support for secure browser deployments
76
-
77
- ### 🤖 Agent System
78
-
79
- - **Type-Safe Architecture**: Full TypeScript support with generic type parameters
80
- - **Robota Class**: Complete AI agent implementation with conversation + tool system + plugin integration
81
- - **Stateless Service Layer**: ConversationService, ToolExecutionService, ExecutionService for business logic
82
- - **Manager Layer**: AIProviders, Tools, AgentFactory, Plugins, ConversationHistory for resource management
83
- - **Parallel Tool Execution**: Concurrent multi-tool calling support
84
-
85
- ### 🌊 Streaming Response System
86
-
87
- - **Real-time Streaming**: Full streaming support across all AI providers
88
- - **Modular Architecture**: Separate streaming/parsing logic for each provider
89
- - **Provider Support**: OpenAI, Anthropic, Google with dedicated stream handlers
90
-
91
- ### 🔧 Tool System
92
-
93
- - **Type-Safe Tools**: `BaseTool<TParameters, TResult>` with compile-time type checking
94
- - **ToolRegistry**: Schema storage and validation system
95
- - **Function Tools**: Zod schema-based function tool implementation
96
- - **OpenAPI/MCP Support**: Basic structure for extensibility
97
-
98
- ## Recent Updates
99
-
100
- - Tool execution results preserve `executionId` mappings for both success and failure to keep deterministic ordering.
101
-
102
- ### 🔌 Plugin System
35
+ - **Robota class**: AI agent with conversation history, tool execution, and plugin support
36
+ - **Multi-provider**: Register multiple providers, switch dynamically with `setModel()`
37
+ - **Permission system**: Deterministic 3-step policy evaluation (`evaluatePermission`)
38
+ - **Hook system**: Shell command-based lifecycle hooks (`runHooks`)
39
+ - **Plugin system**: `AbstractPlugin` base class with lifecycle hooks (beforeRun, afterRun, onError, etc.)
40
+ - **Event services**: Unified event emission with owner path tracking
41
+ - **Error hierarchy**: Typed errors extending `RobotaError` (ProviderError, RateLimitError, etc.)
42
+ - **Type safety**: Strict TypeScript, zero `any` in production code
103
43
 
104
- Eight core plugins with type-safe configuration and BasePluginOptions integration:
105
-
106
- - **ConversationHistoryPlugin**: Comprehensive conversation storage with support for memory, file, and database backends. Features auto-save, batch processing, and configurable limits.
107
- - **UsagePlugin**: Advanced usage analytics including token counting, cost calculation, aggregated statistics, and multiple storage strategies (memory/file/remote).
108
- - **LoggingPlugin**: Multi-level logging system with console, file, and remote endpoints. Supports custom formatters, batch processing, and structured logging.
109
- - **PerformancePlugin**: Real-time performance monitoring including execution time tracking, memory usage, CPU metrics, and customizable performance thresholds.
110
- - **ErrorHandlingPlugin**: Robust error management with multiple strategies (simple, exponential-backoff, circuit-breaker, silent) and custom error handlers.
111
- - **LimitsPlugin**: Advanced rate limiting with token bucket, sliding window, and fixed window strategies. Supports cost tracking and custom calculators.
112
- - **EventEmitterPlugin**: Comprehensive event system with async/sync event handling, filtering, buffering, and lifecycle event tracking.
113
- - **WebhookPlugin**: HTTP webhook notifications with batch processing, retry logic, custom transformers, and concurrent request management.
114
-
115
- #### Plugin Features
116
-
117
- - **Type Safety**: All plugins extend BasePluginOptions for consistent configuration
118
- - **Lifecycle Integration**: Automatic integration with agent lifecycle events
119
- - **Resource Management**: Built-in cleanup and resource optimization
120
- - **Performance Monitoring**: All plugins include built-in statistics and monitoring
121
- - **Error Resilience**: Graceful error handling across all plugin operations
122
-
123
- #### Plugin Control and Configuration
124
-
125
- - **Clear Disable Options**: Every plugin provides multiple ways to disable functionality
126
- - **No Arbitrary Decisions**: Plugins avoid making policy decisions without explicit configuration
127
- - **Explicit Configuration**: All automatic behaviors can be controlled through configuration
128
- - **Silent Modes**: Most plugins support 'silent' strategies for performance-critical scenarios
44
+ ## Robota API
129
45
 
130
46
  ```typescript
131
- // Complete plugin disable
132
- const agent = new Robota({
133
- plugins: [], // No plugins
134
- });
47
+ const agent = new Robota(config);
135
48
 
136
- // Selective plugin disable
137
- const agent = new Robota({
138
- plugins: [
139
- new LoggingPlugin({ strategy: 'silent', enabled: false }),
140
- new LimitsPlugin({ strategy: 'none' }),
141
- new UsagePlugin({ strategy: 'silent' }),
142
- ],
143
- });
144
- ```
49
+ // Send a message (executes tool calls automatically)
50
+ const response = await agent.run('Hello');
145
51
 
146
- #### Plugin Documentation
52
+ // Conversation history
53
+ const history = agent.getHistory(); // TUniversalMessage[]
54
+ agent.clearHistory();
147
55
 
148
- - **[Plugin Guide](./docs/PLUGINS.md)**: Unified plugin behavior and configuration guide
56
+ // Switch provider/model mid-conversation
57
+ agent.setModel({ provider: 'openai', model: 'gpt-4o' });
58
+ ```
149
59
 
150
- ### 🔒 Type Safety Features
60
+ ## IAgentConfig
151
61
 
152
- - **Generic Type Parameters**: `BaseAgent<TConfig, TContext, TMessage>`
153
- - **Provider Agnostic**: Dynamic provider registration with type safety
154
- - **Extended RunContext**: Provider-specific options with type preservation
155
- - **Plugin Type Parameters**: `BasePlugin<TOptions, TStats>` for specialized configurations
62
+ | Field | Type | Description |
63
+ | ---------------------------- | -------------------------- | ------------------------------ |
64
+ | `name` | `string` | Agent name |
65
+ | `aiProviders` | `IAIProvider[]` | One or more provider instances |
66
+ | `defaultModel.provider` | `string` | Provider name |
67
+ | `defaultModel.model` | `string` | Model identifier |
68
+ | `defaultModel.systemMessage` | `string?` | System prompt |
69
+ | `tools` | `IToolWithEventService[]?` | Tools the agent can call |
70
+ | `plugins` | `IPluginContract[]?` | Plugins for lifecycle hooks |
156
71
 
157
72
  ## Architecture
158
73
 
159
- ### Core Abstraction Layers
160
-
161
74
  ```
162
- BaseAgent<TConfig, TContext, TMessage> (Abstract Class)
163
- └── Robota (Implementation - AI conversation + tool system + plugins)
164
-
165
- BaseAIProvider<TConfig, TMessage, TResponse>
166
- ├── OpenAIProvider (via @robota-sdk/agent-provider-openai)
167
- ├── AnthropicProvider (via @robota-sdk/agent-provider-anthropic)
168
- └── GoogleProvider (via @robota-sdk/agent-provider-google)
169
-
170
- BaseTool<TParameters, TResult>
171
- ├── FunctionTool (Zod schema-based)
172
- ├── OpenAPITool (API specification-based)
173
- └── MCPTool (Model Context Protocol)
174
-
175
- BasePlugin<TOptions, TStats>
176
- ├── Core Plugins (8 essential plugins)
177
- └── Custom Plugins (User-defined extensions)
75
+ agent-core (this package — zero workspace dependencies)
76
+ ↑
77
+ agent-sessions ← Session lifecycle
78
+ agent-tools ← Tool implementations
79
+ agent-providers ← AI provider implementations
80
+ agent-plugins ← Plugin implementations (8 extracted packages)
81
+ ↑
82
+ agent-sdk ← Assembly layer
83
+ ↑
84
+ agent-cli ← Terminal UI
178
85
  ```
179
86
 
180
- ### Module Structure
181
-
182
- ```
183
- packages/agents/src/
184
- ├── abstracts/ # Abstract base classes with type parameters
185
- ├── interfaces/ # Type-safe interface definitions
186
- ├── agents/ # Main agent system
187
- │ ├── managers/ # Resource managers
188
- │ ├── services/ # Stateless business logic
189
- │ └── tools/ # Tool system
190
- ├── plugins/ # Plugin system with Facade pattern
191
- └── utils/ # Core utilities
192
- ```
193
-
194
- ## Development
195
-
196
- See [Development Guide](./docs/DEVELOPMENT.md) for development guidelines.
197
-
198
- ## API Reference
199
-
200
- See [api.md](api.md) for complete API documentation.
201
-
202
- ## Architecture Guide
203
-
204
- See [Architecture](./docs/ARCHITECTURE.md) for detailed architecture information.
205
-
206
- ## Examples
207
-
208
- - [Basic Usage](../../../docs/examples/basic-usage.md)
209
- - [Browser Usage](../../../docs/examples/browser-usage.md) 🌐
210
- - [Tool Integration](../../../docs/examples/tool-integration.md)
211
- - [Plugin Development](../../../docs/examples/plugin-development.md)
212
- - [Streaming Responses](../../../docs/examples/streaming.md)
213
-
214
- ## Package Compatibility
215
-
216
- ### Integrated Packages
87
+ ## What This Package Provides
217
88
 
218
- - **@robota-sdk/agent-provider-openai**: Complete agents standard migration
219
- - **@robota-sdk/agent-provider-anthropic**: Complete agents standard migration
220
- - **@robota-sdk/agent-provider-google**: Complete agents standard migration
221
- - **@robota-sdk/agent-team**: assignTask MCP tool collection (team creation removed)
89
+ | Category | Exports |
90
+ | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
91
+ | **Core** | `Robota`, `AbstractAgent`, `AbstractAIProvider`, `AbstractPlugin`, `AbstractTool`, `AbstractExecutor`, `LocalExecutor` |
92
+ | **Permissions** | `evaluatePermission`, `MODE_POLICY`, `TRUST_TO_MODE`, `TPermissionMode`, `TToolArgs` |
93
+ | **Hooks** | `runHooks`, `THookEvent` (PreToolUse, PostToolUse, PreCompact, PostCompact, SessionStart, Stop) |
94
+ | **Events** | `AbstractEventService`, `DefaultEventService`, `StructuredEventService`, `EventEmitterPlugin` |
95
+ | **Types** | `TUniversalMessage`, `IAgentConfig`, `IAIProvider`, `IToolSchema`, `IContextWindowState` |
96
+ | **Errors** | `RobotaError`, `ProviderError`, `RateLimitError`, `AuthenticationError`, `ToolExecutionError`, etc. |
222
97
 
223
- ### Deprecated Packages
98
+ ## What Moved Out in v3
224
99
 
225
- - **@robota-sdk/core**: Deprecated - functionality moved to agents
226
- - **@robota-sdk/agent-tools**: Deprecated - functionality moved to agents
100
+ | What | Moved to |
101
+ | --------------------------------------------- | ---------------------------- |
102
+ | `FunctionTool`, `ToolRegistry`, `OpenAPITool` | `@robota-sdk/agent-tools` |
103
+ | `MCPTool`, `RelayMcpTool` | `@robota-sdk/agent-tool-mcp` |
104
+ | 8 plugins (logging, usage, performance, etc.) | `@robota-sdk/agent-plugin-*` |
227
105
 
228
106
  ## License
229
107