CogCore

An API-native TypeScript runtime for building agents around your application APIs.

Bring your application APIs. Shape focused agents. Run verified one-off API automation.

Tutorial

CogCore, short for cognition + core, helps TypeScript applications add AI agents without turning the whole product into an agent framework. Your app keeps its data, UI, permissions, product APIs, and release workflow. CogCore provides the runtime layer for model roles, tools, worker agents, API-aware automation, streaming, persistence, and validation.

Here, API-native means native to your application's own API surface: the functions, schemas, and product rules that agents are allowed to use.

Quick Start

Install:

npm install cog-core

Create a CogCore runtime, then create a chat agent and add tools from your app. Different roles can use different models, so user chat, execution, and lightweight text work can each optimize for the job:

import { ChatAgent, OpenRouterProvider, createCogCore } from 'cog-core'
import { z } from 'zod'

const cog = createCogCore({
	llm: {
		provider: new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY }),
		roles: {
			chat: { provider: 'openrouter', model: 'anthropic/claude-sonnet-4.6' },
			execute: { provider: 'openrouter', model: 'openai/gpt-5.4-mini' },
			text: { provider: 'openrouter', model: 'openai/gpt-5.4-mini' },
		},
	},
})

const agent = new ChatAgent({
	cog,
	namespace: 'workspace-assistant',
	systemPrompt: 'You help users work with the current workspace.',
})

agent.addTool({
	name: 'search_docs',
	description: 'Search workspace documents.',
	parameters: z.object({
		query: z.string().min(1),
	}),
	callback: async ({ query }) => {
		const matches = await searchWorkspaceDocs(query)
		return {
			forUser: `Found ${matches.length} documents.`,
			forAI: { matches },
		}
	},
})

For a complete walkthrough with the built-in Chatbox, custom chat UI integration, worker agents, API-aware code execution, and custom tools, see the developer tutorial.

For a backend-free package smoke test, see the minimal demo. It uses a tiny fake provider, so it does not require provider credentials.

Overall Structure

CogCore is usually used as a small runtime inside a larger application:

Your application
  - UI, routing, data, auth, permissions
  - application APIs and product rules

CogCore runtime
  - ChatAgent for the user-facing conversation
  - focused worker agents for delegated tasks
  - tools that connect agents to approved app capabilities
  - optional API specs for code-based automation

The default agent shape is:

ChatAgent
  -> WorkerAgent roles
  -> CodeAgent
       -> ApiAgent

Common built-in worker roles include:

• CodeAgent for API-aware one-off automation.
• ApiAgent for answering questions about a configured API entry point.
• ResearchAgent for web-backed research.
• MediaAgent for host-backed asset generation and retrieval.
• RecallAgent for finding relevant prior chat context.
• DistillAgent for turning successful runs into reusable skill tips.

You can also create your own worker agents for product-specific jobs, such as a SlideAgent, ReportAgent, DataCleanupAgent, or any other focused role that makes sense for your application.

Why CogCore

• Built for application APIs. CogCore is strongest when your product already has meaningful APIs, schemas, and rules that agents can safely use. Instead of asking the model to guess how the app works, you expose the exact API surface it is allowed to reason over.
• Focused agents instead of one giant thread. Work can be delegated to smaller roles with clearer responsibilities, separate prompts, separate model choices, and review points that match the task.
• Hybrid LLM roles. User chat can use a high-quality planning model, execution can use a stronger code or multimodal model, and text utilities can use a fast low-cost model. This keeps quality, latency, and cost tunable per role.
• Verified one-off automation. Agents can take read/write actions by producing temporary code for a task. That makes batch processing efficient, flexible across product workflows, and adaptable to whatever API specs your application provides, while the host app still decides what data and writes are allowed.
• Host control by default. CogCore is a runtime library, not an application framework. It does not replace your UI, database, permission model, or API implementation, so you can use the built-in Chatbox, build a custom chat UI, choose built-in agents, and add application-specific agents with custom review, verify, and validate gates.
• Skill learning from successful runs. Good outcomes can be distilled into short reusable tips, so similar future tasks can reach a reviewed result faster.

Concepts

Runtime

createCogCore(...) creates the local runtime context shared by agents. It stores the LLM provider, role models, optional embedding and media configuration, and optional API spec loaders. It does not contain your UI, database, permission model, or application API implementation.

Model Roles

CogCore separates LLM usage into role names so one product can use a hybrid model setup:

• chat for user-facing conversation, intent understanding, planning, and top-level coordination.
• execute for delegated worker tasks, code generation, multimodal reasoning, and verified action.
• text for lighter text operations such as retrieval, summarization, and skill distillation.

You can use the same model for every role at first, but CogCore is designed to specialize later as cost, latency, and quality requirements become clearer.

Agents

ChatAgent is the usual root agent for an application chat experience. Worker agents are smaller roles used for focused internal tasks. Built-in workers cover common needs, and application teams can add their own agents for product-specific workflows.

Agents can mix model roles: the root chat can reason with the chat model, delegated workers can run with execute, and supporting summarization or recall can use text. This lets one agent system balance rich conversation with reliable action and cheap background processing.

Tools

Tools are the bridge from agents to your application. A tool has a name, description, schema, and callback. The callback decides what the agent may do, how host permissions are enforced, and what information returns to the user and to the model.

API Specs

For code-based automation, CogCore can use generated API specs from *.api.ts entry points. These specs help agents understand the application APIs they are allowed to call, including the types, functions, and product rules your app chooses to expose.

Sandbox

CodeAgent runs generated JavaScript in a browser-friendly sandbox. The host application still provides the data, permission boundary, write policy, and validation flow, so one-off automation can be powerful without making the model the owner of the product state.

Skill Learning

When a worker result is accepted, CogCore can distill the run into short skill tips. Those tips can be recalled on similar future tasks to reduce repeated mistakes while keeping review and validation in place.

How It Differs

| Approach | Common fit | CogCore difference | | --- | --- | --- | | General chatbot SDK | Add a chat box around model calls | Adds runtime roles, worker delegation, tools, persistence, and validation around your app APIs. | | Agent framework | Build an agent-centered application | Stays a runtime library inside your existing TypeScript app, with host-owned UI, permissions, APIs, and release flow. | | Workflow automation | Repeat known steps | Supports verified one-off code actions that can adapt to API specs, batch across data, and still pass through host review. | | Tool-calling only | Call approved functions from chat | Combines tools with worker agents, API exploration, sandboxed code execution, and skill learning. |

License

MIT