Robota SDK

Appearance

agents / Exports

agents ​

Fileoverview

Robota SDK Agents Package - Comprehensive AI Agent Framework

The @robota-sdk/agents package provides a complete AI agent framework with support for multiple AI providers, tool calling, plugin systems, and streaming responses. This package provides a modern, modular architecture for building powerful AI applications.

Key Features ​

  • Multi-Provider Support: OpenAI, Anthropic, Google, and custom AI providers
  • Tool Calling: Zod-based schema validation for function calls
  • Plugin System: Extensible lifecycle hooks for logging, analytics, error handling
  • Streaming Responses: Real-time response streaming from all providers
  • Conversation Management: Centralized history and session management
  • Type Safety: Full TypeScript support with strict type checking
  • Modular Architecture: Independent packages with clear separation of concerns

Quick Start ​

typescript
import { Robota } from '@robota-sdk/agents';
import { OpenAIProvider } from '@robota-sdk/openai';

const robota = new Robota({
  name: 'MyAgent',
  aiProviders: { 
    openai: new OpenAIProvider({ apiKey: 'sk-...' }) 
  },
  currentProvider: 'openai',
  currentModel: 'gpt-4'
});

const response = await robota.run('Hello, world!');
console.log(response);

Package Structure ​

  • Core Agent: Robota class for AI conversations
  • Abstracts: Base classes for extending functionality
  • Interfaces: TypeScript definitions for all components
  • Plugins: Extensible functionality (8+ built-in plugins)
  • Tools: Function calling and tool management
  • Managers: Resource and state management
  • Utils: Logging, error handling, validation utilities

Table of contents ​

References ​

Enumerations ​

Classes ​

Interfaces ​

Type Aliases ​

Variables ​

Functions ​

References ​

FunctionSchema ​

Renames and re-exports ToolSchema

Type Aliases ​

ProviderLoggingData ​

Ƭ ProviderLoggingData: Record<string, string | number | boolean | Date | string[]>

Provider logging data type Used for storing logging information in provider operations

Defined in ​

packages/agents/src/abstracts/base-ai-provider.ts:9

BaseToolParameters ​

Ƭ BaseToolParameters: Record<string, string | number | boolean | string[] | number[] | boolean[] | (string | number | boolean)[] | Record<string, string | number | boolean> | null | undefined>

Base tool parameters type - extended for full ToolParameters compatibility Used for parameter validation and execution in base tool context

REASON: Extended to include all ToolParameterValue types for complete compatibility ALTERNATIVES_CONSIDERED:

  1. Keep narrow type and use type assertions everywhere (increases maintenance burden)
  2. Create separate conversion functions (adds complexity without benefit)
  3. Use intersection types (unnecessary complexity for this use case)
  4. Modify ToolParameters to remove complex types (breaks existing APIs)
  5. Create type conversion utilities (adds runtime overhead) TODO: Monitor usage patterns and consider narrowing if complex types cause runtime issues

Defined in ​

packages/agents/src/abstracts/base-tool.ts:17

ToolExecutionFunction ​

Ƭ ToolExecutionFunction<TParams, TResult>: (parameters: TParams) => Promise<TResult> | TResult

Tool execution function type with proper parameter constraints

Type parameters ​

NameType
TParamsBaseToolParameters
TResultToolResult

Type declaration ​

▸ (parameters): Promise<TResult> | TResult

Parameters ​
NameType
parametersTParams
Returns ​

Promise<TResult> | TResult

Defined in ​

packages/agents/src/abstracts/base-tool.ts:33

Message ​

Ƭ Message: UserMessage | AssistantMessage | SystemMessage | ToolMessage

Universal message type

Defined in ​

packages/agents/src/interfaces/agent.ts:58

AgentCreationMetadata ​

Ƭ AgentCreationMetadata: Record<string, string | number | boolean | Date>

Agent creation metadata type Used for storing additional information about agent creation and configuration

Defined in ​

packages/agents/src/interfaces/manager.ts:14

ParameterDefaultValue ​

Ƭ ParameterDefaultValue: string | number | boolean | null

JSON Schema parameter default value type Used for default values in parameter schemas

Defined in ​

packages/agents/src/interfaces/provider.ts:17

JSONSchemaType ​

Ƭ JSONSchemaType: "string" | "number" | "integer" | "boolean" | "array" | "object" | "null"

JSON Schema primitive types

Defined in ​

packages/agents/src/interfaces/provider.ts:22

JSONSchemaEnum ​

Ƭ JSONSchemaEnum: string[] | number[] | boolean[] | (string | number | boolean)[]

JSON Schema enum values

Defined in ​

packages/agents/src/interfaces/provider.ts:27

ConversationContextMetadata ​

Ƭ ConversationContextMetadata: Record<string, string | number | boolean | Date>

Metadata type for conversation and execution context Used for storing additional information about conversations, responses, and execution

Defined in ​

packages/agents/src/interfaces/service.ts:18

ToolMetadata ​

Ƭ ToolMetadata: Record<string, string | number | boolean | string[] | number[] | boolean[] | ToolParameters>

Tool metadata structure - specific type definition

Defined in ​

packages/agents/src/interfaces/tool.ts:26

ToolExecutionData ​

Ƭ ToolExecutionData: string | number | boolean | Record<string, string | number | boolean | ToolParameters> | (string | number | boolean | ToolParameters)[] | ToolParameters | ToolResult | null | undefined

Generic tool execution data - supports complex nested structures including ToolResult

REASON: Extended to include ToolResult and Record types for tool adapter compatibility ALTERNATIVES_CONSIDERED:

  1. Create separate adapter functions (increases complexity without benefit)
  2. Use type assertions at tool registration (decreases type safety)
  3. Modify tool return types throughout codebase (massive breaking change)
  4. Use intersection types (unnecessary complexity) TODO: Consider creating stricter variants if broad typing causes issues

Defined in ​

packages/agents/src/interfaces/tool.ts:39

ToolExecutor ​

Ƭ ToolExecutor<TParams, TResult>: (parameters: TParams, context?: ToolExecutionContext) => Promise<TResult>

Generic tool executor function

Type parameters ​

NameType
TParamsToolParameters
TResultToolExecutionData

Type declaration ​

▸ (parameters, context?): Promise<TResult>

Parameters ​
NameType
parametersTParams
context?ToolExecutionContext
Returns ​

Promise<TResult>

Defined in ​

packages/agents/src/interfaces/tool.ts:117

PrimitiveValue ​

Ƭ PrimitiveValue: string | number | boolean | null | undefined

Primitive value types - foundation for all other types

Defined in ​

packages/agents/src/interfaces/types.ts:9

ArrayValue ​

Ƭ ArrayValue: string[] | number[] | boolean[] | PrimitiveValue[] | ObjectValue[]

Array value types - well-defined array structures (includes object arrays for complex data)

Defined in ​

packages/agents/src/interfaces/types.ts:14

ObjectValue ​

Ƭ ObjectValue: Record<string, PrimitiveValue | ArrayValue | Date>

Object value types - structured object definitions (includes Date for compatibility)

Defined in ​

packages/agents/src/interfaces/types.ts:19

UniversalValue ​

Ƭ UniversalValue: PrimitiveValue | ArrayValue | ObjectValue

Universal value type - covers all valid data types

Defined in ​

packages/agents/src/interfaces/types.ts:24

MetadataValue ​

Ƭ MetadataValue: PrimitiveValue | ArrayValue | Date

Metadata type - consistent across all components (includes Date for compatibility)

Defined in ​

packages/agents/src/interfaces/types.ts:29

Metadata ​

Ƭ Metadata: Record<string, MetadataValue>

Defined in ​

packages/agents/src/interfaces/types.ts:30

ContextData ​

Ƭ ContextData: Record<string, UniversalValue>

Context data type - for execution contexts

Defined in ​

packages/agents/src/interfaces/types.ts:35

LoggerData ​

Ƭ LoggerData: Record<string, UniversalValue | Date | Error>

Logger data type - for logging contexts (includes Date for timestamps)

Defined in ​

packages/agents/src/interfaces/types.ts:40

ComplexConfigValue ​

Ƭ ComplexConfigValue: Record<string, PrimitiveValue | ArrayValue | ObjectValue>

Configuration value type - for all configuration objects

REASON: Configuration needs to support complex objects like BaseTool[], BasePlugin[], and nested configurations ALTERNATIVES_CONSIDERED:

  1. Strict primitive types (breaks existing configuration functionality)
  2. Union types with all possible objects (becomes unwieldy and incomplete)
  3. Generic constraints (too complex for configuration scenarios)
  4. Interface definitions (too rigid for varied configuration objects)
  5. Type assertions at usage sites (decreases type safety)
  6. Separate configuration types (breaks existing functionality)
  7. Using 'any' type (violates type safety requirements) TODO: Consider creating specific configuration interfaces if runtime issues occur

Defined in ​

packages/agents/src/interfaces/types.ts:56

ConfigValue ​

Ƭ ConfigValue: PrimitiveValue | ArrayValue | ObjectValue | ComplexConfigValue[] | Record<string, PrimitiveValue | ArrayValue | ObjectValue>[] | ComplexConfigValue[] | ComplexConfigValue

Defined in ​

packages/agents/src/interfaces/types.ts:57

ConfigData ​

Ƭ ConfigData: Record<string, ConfigValue>

Defined in ​

packages/agents/src/interfaces/types.ts:58

ToolParameterValue ​

Ƭ ToolParameterValue: PrimitiveValue | ArrayValue | ObjectValue

Tool parameter value type - specific for tool parameters

Defined in ​

packages/agents/src/interfaces/types.ts:63

ToolParameters ​

Ƭ ToolParameters: Record<string, ToolParameterValue>

Defined in ​

packages/agents/src/interfaces/types.ts:64

ToolResultData ​

Ƭ ToolResultData: UniversalValue

Tool result data type - for tool execution results

Defined in ​

packages/agents/src/interfaces/types.ts:69

ProviderConfigValue ​

Ƭ ProviderConfigValue: PrimitiveValue | ArrayValue | ObjectValue

Provider configuration value type - for AI provider configs Note: ProviderConfig is defined in agent.ts to avoid export conflicts

Defined in ​

packages/agents/src/interfaces/types.ts:75

UniversalMessage ​

Ƭ UniversalMessage: UserMessage | AssistantMessage | SystemMessage | ToolMessage

Universal message type covering all possible message variations

This union type ensures type safety by requiring specific properties based on the message role, preventing invalid combinations.

Defined in ​

packages/agents/src/managers/conversation-history-manager.ts:111

HistoryStorageStrategy ​

Ƭ HistoryStorageStrategy: "memory" | "file" | "database"

Storage strategy for conversation history

Defined in ​

packages/agents/src/plugins/conversation-history/types.ts:7

ErrorHandlingStrategy ​

Ƭ ErrorHandlingStrategy: "simple" | "circuit-breaker" | "exponential-backoff" | "silent"

Error handling strategy types

Defined in ​

packages/agents/src/plugins/error-handling/types.ts:17

EventType ​

Ƭ EventType: "execution.start" | "execution.complete" | "execution.error" | "conversation.start" | "conversation.complete" | "conversation.error" | "tool.beforeExecute" | "tool.afterExecute" | "tool.success" | "tool.error" | "plugin.error" | "module.initialize.start" | "module.initialize.complete" | "module.initialize.error" | "module.execution.start" | "module.execution.complete" | "module.execution.error" | "module.dispose.start" | "module.dispose.complete" | "module.dispose.error" | "module.registered" | "module.unregistered" | "custom"

Event types that can be emitted

Defined in ​

packages/agents/src/plugins/event-emitter-plugin.ts:9

EventListener ​

Ƭ EventListener: (event: EventData) => void | Promise<void>

Event listener function

Type declaration ​

▸ (event): void | Promise<void>

Parameters ​
NameType
eventEventData
Returns ​

void | Promise<void>

Defined in ​

packages/agents/src/plugins/event-emitter-plugin.ts:111

LimitsStrategy ​

Ƭ LimitsStrategy: "token-bucket" | "sliding-window" | "fixed-window" | "none"

Rate limiting strategies

Defined in ​

packages/agents/src/plugins/limits/types.ts:6

LoggingStrategy ​

Ƭ LoggingStrategy: "console" | "file" | "remote" | "silent"

Logging strategy types

Defined in ​

packages/agents/src/plugins/logging/types.ts:4

LogLevel ​

Ƭ LogLevel: "debug" | "info" | "warn" | "error"

Log levels

Defined in ​

packages/agents/src/plugins/logging/types.ts:9

PerformanceMonitoringStrategy ​

Ƭ PerformanceMonitoringStrategy: "memory" | "file" | "prometheus" | "remote" | "silent"

Performance monitoring strategy types

Defined in ​

packages/agents/src/plugins/performance/types.ts:4

UsageTrackingStrategy ​

Ƭ UsageTrackingStrategy: "memory" | "file" | "remote" | "silent"

Usage tracking strategy types

Defined in ​

packages/agents/src/plugins/usage/types.ts:4

WebhookEventType ​

Ƭ WebhookEventType: "execution.start" | "execution.complete" | "execution.error" | "conversation.complete" | "tool.executed" | "error.occurred" | "custom"

Webhook event types for different lifecycle events

Defined in ​

packages/agents/src/plugins/webhook/types.ts:9

ErrorContextData ​

Ƭ ErrorContextData: Record<string, string | number | boolean | Date | Error | string[]>

Error context data type Used for storing contextual information in error instances

Defined in ​

packages/agents/src/utils/errors.ts:9

ErrorExternalInput ​

Ƭ ErrorExternalInput: Error | string | Record<string, string | number | boolean> | null | undefined

Error external input type Used for handling external errors from unknown sources

Defined in ​

packages/agents/src/utils/errors.ts:15

LoggerContextData ​

Ƭ LoggerContextData: LoggerData

Logger context data type - uses centralized type definition

Defined in ​

packages/agents/src/utils/logger.ts:10

UtilLogLevel ​

Ƭ UtilLogLevel: "debug" | "info" | "warn" | "error" | "silent"

Log levels for the logger

Defined in ​

packages/agents/src/utils/logger.ts:15

Variables ​

TypeUtils ​

• Const TypeUtils: Object

Type utility functions for safe type checking

REASON: Type guards need to accept any input for runtime validation. Using specific input type for type-safe validation. ALTERNATIVES_CONSIDERED:

  1. Using 'any' type (violates type safety requirements)
  2. Multiple overloaded signatures (creates maintenance burden)
  3. Generic constraints (too complex for simple type checking)
  4. Separate validation functions (unnecessary complexity)
  5. Interface-based approach (overkill for simple type guards) TODO: Consider adding more specific type guards if needed

Type declaration ​

NameType
isPrimitive(value: Date | UniversalValue | Record<string, UniversalValue>) => value is PrimitiveValue
isArray(value: Date | UniversalValue | Record<string, UniversalValue>) => value is ArrayValue
isObject(value: Date | UniversalValue | Record<string, UniversalValue>) => value is ObjectValue
isUniversalValue(value: Date | UniversalValue | Record<string, UniversalValue>) => value is UniversalValue

Defined in ​

packages/agents/src/interfaces/types.ts:101

logger ​

• Const logger: Logger

Default logger for the agents package

Defined in ​

packages/agents/src/utils/logger.ts:173

Functions ​

createFunctionTool ​

▸ createFunctionTool(name, description, parameters, fn): FunctionTool

Helper function to create a function tool from a simple function

Parameters ​

NameType
namestring
descriptionstring
parametersObject
parameters.type"object"
parameters.propertiesRecord<string, ParameterSchema>
parameters.required?string[]
fnToolExecutor

Returns ​

FunctionTool

Defined in ​

packages/agents/src/tools/implementations/function-tool.ts:228

createZodFunctionTool ​

▸ createZodFunctionTool(name, description, zodSchema, fn): FunctionTool

Helper function to create a function tool from Zod schema

Parameters ​

NameType
namestring
descriptionstring
zodSchemaZodSchema
fnToolExecutor

Returns ​

FunctionTool

Defined in ​

packages/agents/src/tools/implementations/function-tool.ts:246

createLogger ​

▸ createLogger(packageName): Logger

Create a logger instance for a package

Parameters ​

NameType
packageNamestring

Returns ​

Logger

Defined in ​

packages/agents/src/utils/logger.ts:152

setGlobalLogLevel ​

▸ setGlobalLogLevel(level): void

Set global log level for all loggers

Parameters ​

NameType
levelUtilLogLevel

Returns ​

void

Defined in ​

packages/agents/src/utils/logger.ts:159

getGlobalLogLevel ​

▸ getGlobalLogLevel(): UtilLogLevel

Get global log level

Returns ​

UtilLogLevel

Defined in ​

packages/agents/src/utils/logger.ts:166

validateAgentConfig ​

▸ validateAgentConfig(config): ValidationResult

Validate agent configuration

Parameters ​

NameType
configPartial<AgentConfig>

Returns ​

ValidationResult

Defined in ​

packages/agents/src/utils/validation.ts:190

validateUserInput ​

▸ validateUserInput(input): ValidationResult

Validate user input string

Parameters ​

NameType
inputstring

Returns ​

ValidationResult

Defined in ​

packages/agents/src/utils/validation.ts:191

validateProviderName ​

▸ validateProviderName(name): ValidationResult

Validate provider name

Parameters ​

NameType
namestring

Returns ​

ValidationResult

Defined in ​

packages/agents/src/utils/validation.ts:192

validateModelName ​

▸ validateModelName(name): ValidationResult

Validate model name

Parameters ​

NameType
namestring

Returns ​

ValidationResult

Defined in ​

packages/agents/src/utils/validation.ts:193

validateApiKey ​

▸ validateApiKey(apiKey, provider?): ValidationResult

Validate API key format (basic check)

Parameters ​

NameType
apiKeystring
provider?string

Returns ​

ValidationResult

Defined in ​

packages/agents/src/utils/validation.ts:194

Released under the MIT License.

Copyright © 2023-present