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.

CogCore 0.3 uses a composition-first API. Most applications can create ChatAgent and WorkerAgent instances directly, then configure them with constructor options, tools, and hooks. Class inheritance remains available for advanced reusable agent types, but it is not required for normal application integration.

Quick Start

Install:

npm install cog-core

Create a local CogCore runtime, instantiate a chat agent, and add the context and tools supplied by your application. Only chat is required. Optional and application-defined roles let specialized agents use different models:

import {
	ChatAgent,
	OpenRouterProvider,
	WorkerAgent,
	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' },
			worker: { provider: 'openrouter', model: 'openai/gpt-5.4-mini' },
			code: { 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.onInitialContext(async ({ instruction, stopSignal, setToolState }) => {
	setToolState({ forUser: 'Loading workspace context...', path: ['workspace'] })
	const workspace = await loadWorkspaceSummary({ instruction, signal: stopSignal })
	return { context: 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 },
		}
	},
})

onInitialContext(...) runs once, before the agent's first instruction. Use it for initial workspace state, selected content, or other lazily loaded context. Pass changing per-turn context to sendUserMessage(...) or sendInstruction(...), or expose it through a tool.

For a focused internal task, instantiate WorkerAgent directly and configure its structured return:

const worker = new WorkerAgent({
	cog,
	systemPrompt: 'Create a concise outline, then call return.',
})

worker.onReturn({
	parameters: z.object({
		title: z.string(),
		sections: z.array(z.string()),
	}).strict(),
	callback: (outline) => ({
		accepted: outline.sections.length <= 8,
		forAI: outline,
	}),
})

const { response } = await worker.sendInstruction('Outline the release notes.')

Inside a tool callback, create workers with the provided subAgent(...) helper so they inherit the parent session, assets, runtime, cancellation, progress, and usage tracking.

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.

For a larger open-source example, see Cog SVG Editor. It demonstrates a host app exposing a semantic SVG API to CogCore so the agent edits through validated drawing operations rather than raw SVG/XML.

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.
• SkillAgent for loading and distilling reusable skill tips from successful runs.

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.
• worker for general delegated agent tasks.
• code for code generation, API-aware automation, and implementation-heavy work.
• text for lighter text operations such as retrieval, summarization, and skill distillation.

chat is the only required role; all other roles are optional. Built-in agents resolve ordered fallbacks, so CodeAgent uses code, then worker, then chat, while a normal WorkerAgent uses worker, then chat. CogCore also accepts application-defined role names:

const cog = createCogCore({
	llm: {
		roles: {
			chat: { provider: 'openrouter', model: 'anthropic/claude-sonnet-4.6' },
			reviewer: { provider: 'openrouter', model: 'openai/gpt-5.4-mini' },
		},
	},
})

const reviewer = new WorkerAgent({
	cog,
	llm: cog.resolveLLM(['reviewer', 'worker', 'chat']),
})

resolveLLM(...) is the single role-resolution API for both CogCore agents and application-defined agents. It accepts one role or an ordered fallback list and returns the configured LLM.

Agents

ChatAgent is the usual root agent for an application chat experience. WorkerAgent instances are smaller roles used for focused internal tasks. Built-in workers cover common needs, and application teams can configure workers directly or add reusable agent subclasses for product-specific workflows.

Agents can mix model roles: the root chat uses chat, delegated workers prefer worker, code automation prefers code, and supporting summarization or recall prefers text. Missing optional roles fall back toward chat.

Public composition APIs include:

• Constructor options for prompts, persistence, model/runtime selection, media, search, budgets, and debugging.
• addTool(...) for application capabilities.
• onInitialContext(...) for one-time lazy context before the first instruction.
• onReturn(...) for typed WorkerAgent results and acceptance checks.
• onUpdate(...) and onStream(...) for UI integration.

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