# Core API URL: https://cogitator.app/docs/api-reference/core > Public exports of @cogitator-ai/core — runtime, agents, tools, LLM backends and the advanced subsystems — with their signatures. Everything below is exported from `@cogitator-ai/core`. Types such as `AgentConfig`, `RunOptions` and `RunResult` live in [`@cogitator-ai/types`](/docs/api-reference/types) and are re-exported from core. ## Runtime ### `Cogitator` ```typescript new Cogitator(config?: CogitatorConfig) ``` | Member | Signature | Purpose | | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `run` | `run(agent: Agent, options: RunOptions): Promise` | Run an agent: LLM calls, tools, memory, guardrails, tracing | | `resume` | `resume(agent: Agent, target: RunCheckpoint \| string, options?: ResumeOptions): Promise` | Continue a run paused for [approvals](/docs/tools/approvals), by checkpoint or thread id | | `tools` | `readonly tools: ToolRegistry` | Tools offered to every agent this instance runs | | `prompts` | `get prompts(): PromptRegistry` | [Versioned instructions and A/B tests](/docs/advanced/prompt-versions) | | `getMemory` | `getMemory(): Promise` | The configured memory adapter, connected on first use | | `memory` | `get memory(): MemoryAdapter \| undefined` / `set memory(adapter)` | The connected adapter (`undefined` before first use), or set your own | | `resolveModel` | `resolveModel(agent: Agent): string` | The agent's model, else `llm.defaultModel`; throws `CONFIGURATION_ERROR` | | `route` | `route(modelString: string, explicitProvider?: string): ModelRoute` | Backend and provider-side model name for a model string | | `getLLMBackend` | `getLLMBackend(modelString: string, explicitProvider?: string): LLMBackend` | The backend a model string runs on | | `knowsProvider` | `knowsProvider(name: string): boolean` | Whether a `name/...` model prefix routes to `name` (backend, built-in or plugin) | | `estimateCost` | `estimateCost(params: { agent; input; options?: EstimateOptions; model? }): Promise` | Cost estimate before running | | `getCostSummary` | `getCostSummary(): CostSummary \| undefined` | Tracked spend (with `costRouting`) | | `getCostRouter` | `getCostRouter(): CostAwareRouter \| undefined` | The cost router (with `costRouting`) | | `getInsights` | `getInsights(agentId: string): Promise` | Reflection insights (with `reflection`) | | `getReflectionSummary` | `getReflectionSummary(agentId: string): Promise` | Reflection statistics | | `reflectionEngine` | `get reflectionEngine(): ReflectionEngine \| undefined` | The reflection engine | | `getGuardrails` | `getGuardrails(): ConstitutionalAI \| undefined` | The guardrails instance | | `setConstitution` | `setConstitution(constitution: Constitution): void` | Replace the guardrails constitution | | `close` | `close(): Promise` | Disconnect memory, stop sandboxes, release resources | See [Cogitator](/docs/core/cogitator) for the configuration. ### Run Checkpoints, Prompts, Threads | Export | Signature | Purpose | | -------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `InMemoryRunCheckpointStore` | `new InMemoryRunCheckpointStore()` | `RunCheckpointStore` in process memory | | `ThreadRunCheckpointStore` | `new ThreadRunCheckpointStore(memory: MemoryAdapter)` | Keeps paused runs in thread metadata (the default with memory) | | `PromptRegistry` | `new PromptRegistry(config?: PromptsConfig)` | `deploy`, `current`, `history`, `rollbackTo`, `startABTest`, `activeABTest`, `completeABTest`, `resolve`, `record` | | `promptKey` | `promptKey(target: Agent \| string): string` | Key instructions are versioned under (agent `id` if set, else `name`) | | `InMemoryInstructionVersionStore`, `InMemoryABTestStore` | `new …()` | Default prompt stores | | `threadOwner` | `threadOwner(thread: Thread): string \| undefined` | The `userId` a thread belongs to | | `threadMetadata` | `threadMetadata(owner: { agentId: string; userId?: string }): Record` | Metadata for a new thread owned by a user | | `assertThreadAccess` | `assertThreadAccess(memory, threadId, userId): Promise` | Throws `THREAD_ACCESS_DENIED` for another user's thread | | `ensureThreadAccess` | `ensureThreadAccess(memory, threadId, owner: { agentId; userId? }): Promise` | Check access and create the thread when missing | ## Agents and Skills | Export | Signature | Purpose | | --------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `Agent` | `new Agent(config: AgentConfig)` | An agent; defaults `temperature: 0.7`, `maxIterations: 10` | | `agent.clone` | `clone(overrides: Partial): Agent` | Copy with changes | | `agent.serialize` | `serialize(): AgentSnapshot` | JSON snapshot (tools by name) | | `Agent.deserialize` | `Agent.deserialize(snapshot: AgentSnapshot, options?: DeserializeOptions): Agent` | Restore from a snapshot (`toolRegistry`, `tools`, `overrides`) | | `Agent.validateSnapshot` | `Agent.validateSnapshot(snapshot: unknown): snapshot is AgentSnapshot` | Check a parsed snapshot | | `AgentDeserializationError` | `class extends Error` | Thrown by `deserialize` for unknown tools or bad snapshots | | `defineSkill` | `defineSkill(config: SkillConfig): Skill` | Bundle tools and instructions (`name`, `version`, `description`, `tools`, `instructions?`, `env?`, `dependencies?`) | | `validateSkill` | `validateSkill(skill: Skill): SkillValidationResult` | Check a skill | | `mergeSkillsIntoAgent` | `mergeSkillsIntoAgent(tools, instructions, skills): { tools; instructions }` | What `new Agent({ skills })` does | The instance getters `id`, `name`, `model`, `instructions`, `tools` and `config` read the configuration. See [Agents](/docs/core/agents). ## Tools | Export | Signature | Purpose | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `tool` | `tool(config: ToolConfig): Tool` | Create a tool from a Zod schema and `execute` | | `toolset` | `toolset(...tools: T): T` | Return several tools as a typed tuple | | `toolToSchema` | `toolToSchema(tool: Tool): ToolSchema` | JSON Schema sent to the LLM | | `ToolRegistry` | `new ToolRegistry()` — `register`, `registerMany`, `get`, `has`, `getAll`, `getSchemas`, `getNames`, `clear` | Tools by name | | `agentAsTool` | `agentAsTool(cogitator, agent, options: AgentAsToolOptions): Tool<{ task: string }, AgentToolResult>` | [Delegate to another agent](/docs/tools/agent-as-tool) | | `builtinTools` | `Tool[]` | The 26 [built-in tools](/docs/tools/built-in) | | `calculator`, `datetime`, `uuid`, `randomNumber`, `randomString`, `hash`, `base64Encode`, `base64Decode`, `sleep`, `jsonParse`, `jsonStringify`, `regexMatch`, `regexReplace`, `fileRead`, `fileWrite`, `fileList`, `fileExists`, `fileDelete`, `httpRequest`, `exec`, `webSearch`, `webScrape`, `sqlQuery`, `vectorSearch`, `sendEmail`, `githubApi` | `Tool` | Individual built-in tools | | `createAnalyzeImageTool`, `createGenerateImageTool` | `(config: AnalyzeImageConfig) => Tool`, `(config?: GenerateImageConfig) => Tool` | [Image tools](/docs/core/vision-and-audio) | | `createTranscribeAudioTool`, `createGenerateSpeechTool` | `(config?) => Tool` | [Audio tools](/docs/core/vision-and-audio) | | `createHttpRequestTool`, `createWebScrapeTool` | `(options?) => Tool` | `http_request` and `web_scrape` with your options: `allowPrivateNetwork`, your own `fetch`, and for scraping a User-Agent and robots.txt check | | `fetchPublic`, `createPublicFetch`, `assertPublicUrl`, `assertPublicHost`, `isPrivateAddress`, `createGuardedLookup`, `PrivateNetworkError` | network guard | A `fetch` that reaches only public hosts, checking redirects and the address a host resolves to when it connects | | `createMemoryTools` | `createMemoryTools(config: MemoryToolsConfig)` | `remember` / `recall` / `forget` over a knowledge graph | | `createSchedulerTools` | `createSchedulerTools(config: SchedulerToolsConfig)` | `schedule_task` / `list_tasks` / `cancel_task` | | `createCapabilitiesTool` | `createCapabilitiesTool(capabilitiesDoc: string): Tool` | `lookup_capabilities` | | `createDeviceTools` | `createDeviceTools(): Tool[]` | Clipboard, system info, screenshot | | `createSelfTools` | `createSelfTools(opts: { toolsDir: string; onToolsChanged?: () => void }): Tool[]` | Let an agent write its own tools | | `loadCustomTools` | `loadCustomTools(toolsDir: string): Promise` | Load tools written by `createSelfTools` | ### Tool Caching | Export | Signature | Purpose | | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `withCache` | `withCache(tool: Tool, config: WithCacheOptions): CachedTool` | [Cache tool results](/docs/tools/tool-caching) | | `createToolCacheStorage` | `createToolCacheStorage(type: 'memory' \| 'redis', options?: { maxSize?; redisClient?; keyPrefix?; onEvict? }): ToolCacheStorage` | A storage instance | | `InMemoryToolCacheStorage` | `new InMemoryToolCacheStorage(maxSize = 1000, options?: { onEvict? })` | LRU storage in a `Map` | | `RedisToolCacheStorage` | `new RedisToolCacheStorage(config: { client: RedisClientLike; keyPrefix?; maxSize?; onEvict? })` | Redis storage | | `generateCacheKey`, `paramsToQueryString`, `cosineSimilarity`, `parseDuration` | functions | Cache key and matching helpers | ## LLM Backends | Export | Signature | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `OllamaBackend` | `new OllamaBackend(config: OllamaConfig)` | `ollama/…` models | | `OpenAIBackend` | `new OpenAIBackend(config: OpenAIConfig)` | `openai/…` (Responses API on api.openai.com) | | `AnthropicBackend` | `new AnthropicBackend(config: AnthropicConfig)` | `anthropic/…` | | `GoogleBackend` | `new GoogleBackend(config: GoogleConfig)` | `google/…` (Gemini) | | `AzureOpenAIBackend` | `new AzureOpenAIBackend(config: AzureOpenAIConfig)` | `azure/…` | | `BedrockBackend` | `new BedrockBackend(config: BedrockConfig)` | `bedrock/…` (Converse API) | | `BaseLLMBackend`, `OpenAICompatibleBackend` | abstract classes | Bases for your own backends | | `createLLMBackend` | `createLLMBackend(provider: LLMProvider, config: CogitatorConfig['llm']): LLMBackend` | A built-in backend from `llm` config | | `parseModel` | `parseModel(modelString: string): { provider: LLMProvider \| null; model: string }` | Split `provider/model` | | `DEFAULT_OPENAI_MODEL`, `isOpenAIReasoningModel` | constant, `(model: string) => boolean` | OpenAI helpers | | `registerLLMBackend` | `registerLLMBackend(plugin: LLMPlugin): void` | Register a backend plugin under a provider name | | `defineBackend` | `defineBackend(options: { metadata; provider; create; validateConfig? }): LLMPlugin` | Build a plugin | | `unregisterLLMBackend`, `hasLLMPlugin`, `listLLMPlugins`, `createLLMBackendFromPlugin`, `llmPluginRegistry` | functions / registry | Manage plugins | | `withLLMRetry` | `withLLMRetry(backend: LLMBackend, config: LLMRetryConfig \| false \| undefined): LLMBackend` | The retry policy runs use (`llm.retry`) | | `RetryingBackend`, `DEFAULT_LLM_RETRY` | `new RetryingBackend(inner, config?)`, constant | Retry wrapper and its defaults (2 retries, 1 s base, 30 s cap, 60 s max `Retry-After`) | | `withDebug`, `LLMDebugWrapper` | `withDebug(backend: LLMBackend, options?: LLMDebugOptions): LLMBackend` | Log requests and responses | | `withPiiMasking`, `PiiMaskingBackend` | `withPiiMasking(backend: LLMBackend, config: PiiConfig \| undefined): LLMBackend` | Mask personal data before it reaches the provider | | `PiiMasker`, `PiiVault`, `PII_TYPES` | `new PiiMasker(config?)`, `new PiiVault()` | PII detection and placeholder restore | | `LLMError`, `createLLMError`, `wrapSDKError`, `llmUnavailable`, `llmInvalidResponse`, `llmTimeout`, `llmConfigError`, `llmNotImplemented`, `providerErrorIn`, `retryAfterFromHeaders` | error helpers | Errors backends throw (`CogitatorError` subclasses) | Backends are normally created by the runtime from `llm.providers`; pass instances of your own through `llm.backends`. See [LLM Backends](/docs/core/llm-backends). ## Errors | Export | Signature | Purpose | | -------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | | `CogitatorError` | `new CogitatorError(options: CogitatorErrorOptions)` | Base error with `code`, `statusCode`, `retryable` | | `ErrorCode` | enum | All error codes ([list](/docs/api-reference/types#errors)) | | `ERROR_STATUS_CODES` | `Record` | HTTP status per code | | `isRetryableError` | `isRetryableError(error: unknown): boolean` | Whether an error is worth retrying | | `getRetryDelay` | `getRetryDelay(error: unknown, defaultDelay = 1000): number` | `retryAfter` of a `CogitatorError`, else the default | ## Resilience and Logging | Export | Signature | Purpose | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | `withRetry` | `withRetry(fn: () => Promise, options?: RetryOptions): Promise` | Retry a function | | `retryable` | `retryable(fn, options?): (...args) => Promise` | Wrap a function with retries | | `CircuitBreaker` | `new CircuitBreaker(options?: CircuitBreakerOptions)` — `execute`, `getState`, `getStats`, `open`, `close`, `reset` | Circuit breaker | | `CircuitBreakerRegistry` | `new CircuitBreakerRegistry(defaultOptions?)` — `get`, `getAllStats`, `resetAll` | Breakers by name | | `withFallback` | `withFallback(config: FallbackConfig): Promise` | Try alternatives in order | | `withGracefulDegradation` | `withGracefulDegradation(fn, options): Promise` | Return a fallback value on failure | | `createLLMFallbackExecutor` | `createLLMFallbackExecutor(config: LLMFallbackConfig, breakers: CircuitBreakerRegistry)` | Provider/model fallback chain with breakers | | `Logger`, `createLogger`, `getLogger`, `setLogger` | `new Logger(options?: LoggerOptions, context?: LogContext)` | Structured logging used by the runtime | | `createLoggerFromConfig` | `createLoggerFromConfig(config: LoggingConfig): Logger` | The logger `new Cogitator({ logging })` installs process-wide | | `fetchImageAsBase64`, `fetchAudioAsBuffer`, `audioInputToBuffer`, `isValidAudioFormat`, `getAudioMimeType` | functions | Media input helpers | ## Observability | Export | Signature | Purpose | | -------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- | | `LangfuseExporter`, `createLangfuseExporter` | `new LangfuseExporter(config: LangfuseConfig)` | Send traces to Langfuse; exports only with `enabled: true` | | `OTLPExporter`, `createOTLPExporter` | `new OTLPExporter(config: OTLPExporterConfig)` | Send spans over OTLP; exports only with `enabled: true` | See [Observability](/docs/deployment/observability). ## Advanced Subsystems | Area | Main exports | Entry point | Guide | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Reflection | `ReflectionEngine`, `InMemoryInsightStore` | `new ReflectionEngine(options)` — `reflectOnToolCall`, `reflectOnError`, `reflectOnRun`, `getRelevantInsights`, `getSummary` | [Reflection](/docs/advanced/reflection) | | Tree of Thoughts | `ThoughtTreeExecutor`, `BranchGenerator`, `BranchEvaluator`, `DEFAULT_TOT_CONFIG` | `new ThoughtTreeExecutor(cogitator, config?)` — `explore(agent, goal, options?): Promise` | [Reasoning](/docs/advanced/reasoning) | | Learning | `AgentOptimizer`, `InMemoryTraceStore`, `PostgresTraceStore`, `MetricEvaluator`, `DemoSelector`, `InstructionOptimizer`, `createSuccessMetric`, `createExactMatchMetric`, `createContainsMetric` | `new AgentOptimizer(options)` — `run`, `compile`, `bootstrapDemos`, `captureTrace` | [Learning](/docs/advanced/learning) | | Prompt optimization | `PromptLogger`, `wrapWithPromptLogger`, `ABTestingFramework`, `PromptMonitor`, `RollbackManager`, `AutoOptimizer` | `wrapWithPromptLogger(backend, store, config?)` | [Prompt Versions](/docs/advanced/prompt-versions) | | Time travel | `TimeTravel`, `InMemoryCheckpointStore`, `ExecutionReplayer`, `ExecutionForker`, `TraceComparator` | `new TimeTravel(cogitator, options?)` — `checkpoint`, `replay`, `fork`, `compare` | [Time Travel](/docs/advanced/time-travel) | | Constitutional AI | `ConstitutionalAI`, `InputFilter`, `OutputFilter`, `ToolGuard`, `CritiqueReviser`, `DEFAULT_CONSTITUTION`, `DEFAULT_PRINCIPLES`, `createConstitution`, `extendConstitution`, … | `new ConstitutionalAI(options)` — `filterInput`, `filterOutput`, `guardTool`, `critiqueAndRevise` | [Constitutional AI](/docs/advanced/constitutional-ai) | | Cost routing | `CostAwareRouter`, `TaskAnalyzer`, `ModelSelector`, `CostTracker`, `BudgetEnforcer`, `TokenEstimator`, `CostEstimator` | `new CostAwareRouter(options?)` — `recommendModel(input)`, `checkBudget`, `getCostSummary` | [Cost Routing](/docs/advanced/cost-routing) | | Causal reasoning | `CausalReasoner`, `CausalGraphBuilder`, `CausalInferenceEngine`, `CounterfactualReasoner`, `dSeparation`, `findBackdoorAdjustment`, `evaluateCounterfactual`, … | `new CausalReasoner(options)` | [Causal Reasoning](/docs/advanced/causal-reasoning) | | Prompt-injection defence | `PromptInjectionDetector`, `LocalInjectionClassifier`, `LLMInjectionClassifier`, `INJECTION_PATTERNS`, `detectEncodingThreats`, `detectUnicodeThreats`, `matchPatterns` | `new PromptInjectionDetector(options?)` — `analyze(input)` | [Security](/docs/advanced/security) | | Context management | `ContextManager`, `TruncateStrategy`, `SlidingWindowStrategy`, `SummarizeStrategy`, `HybridStrategy` | `new ContextManager(config, deps?)` — `checkState`, `compress` | [Context Management](/docs/advanced/context-management) | The configuration and result types of these subsystems (`ToTConfig`, `GuardrailConfig`, `CostRoutingConfig`, `CausalGraph`, …) and their defaults (`DEFAULT_GUARDRAIL_CONFIG`, `DEFAULT_COST_ROUTING_CONFIG`, `DEFAULT_INJECTION_CONFIG`, `DEFAULT_CAUSAL_CONFIG`, …) are re-exported from `@cogitator-ai/types`.