@agentic-patterns/core

Core primitives for building compositional agents. This package provides the atom-to-organism hierarchy: frozen data models, protocol interfaces, molecules (toolbox/manual/capability), section-based prompt rendering, and builders for roles and agents.

Installation

bun add @agentic-patterns/core zod

API Overview

Atoms (`src/atoms/`)

Frozen, immutable data models validated by Zod schemas. Every atom implements toPrompt() returning markdown for LLM consumption.

Atom	Purpose
`Persona`	Agent identity: name, role, identity statement, tone
`Mission`	Objective + output schema + constraints
`Judgment`	Decision heuristic: when/guidelines/examples
`Responsibility`	Named duty with guidelines
`Background`	Company/team/project context
`Awareness`	Knowledge domains with confidence levels
`Methodology`	Process approach description
`State`	Runtime state: phase, progress, context
`Tone`	Communication style guidelines
`Example`	Few-shot example: situation/action/result
`Recovery`	Error recovery strategies
`Agency`	Multi-agent topology definition
`Roster`	Agent deployment roster

import { Persona, Mission, Judgment } from "@agentic-patterns/core";

const persona = new Persona({
  identity: "a data analyst who analyzes datasets with precision",
  tone: "professional",
});

console.log(persona.toPrompt());
// You are a data analyst who analyzes datasets with precision.
// Communication style: professional

Base Classes

AgenticModel<T> -- base class for all atoms. Wraps a Zod schema, freezes parsed data, provides .data accessor and .toPrompt().
ProtocolModel<T> -- base for protocol data models with toPrompt() support.

Protocols (`src/protocols/`)

Vendor-agnostic async interfaces for external systems. Each protocol defines Zod schemas for its data types and an interface for CRUD operations.

Protocol	Operations
`TaskProtocol`	list, get, create, update, addComment, getComments
`ProjectProtocol`	list, get, create, update, listMembers
`TagProtocol`	list, get, create, update, delete
`UserProtocol`	list, get, getTeams, whoAmI
`SprintProtocol`	list, get, create, update
`CommentProtocol`	list, get, create, update, delete, addReaction
`DocumentProtocol`	list, get, create, update, delete
`EnvironmentProtocol`	list, get, create, update, delete

Shared enums: Priority, StatusCategory, IssueType, RelationType, WorkPhase, ProjectStatus, SprintStatus, DocType, TagGroup, UserType, UserRole, etc.

Molecules (`src/molecules/`)

Composable building blocks that combine atoms into functional units.

Molecule	Purpose
`ToolSchema`	Tool definition with Zod parameter schema; converts to OpenAI/Claude/Vercel formats
`Toolbox`	Named collection of tools with `toPrompt()`
`Manual`	Instructional content (text, scoped, simple variants)
`ManualToolbox`	Manual that also provides tools
`Playbook`	Abstract class for named plays with Zod schemas and error-envelope semantics
`Capability`	Toolbox + Manual + optional Playbook describing what an agent can do

import { z } from "zod";
import { ToolSchema, Toolbox, Manual, Capability } from "@agentic-patterns/core";

const searchTool = ToolSchema.fromZod(
  "search_docs",
  "Search documentation",
  z.object({ query: z.string(), limit: z.number().optional() }),
);

const toolbox = new Toolbox("docs", [searchTool]);
const manual = new Manual("docs-manual", [
  { title: "Search", content: "Use search_docs to find relevant documentation." },
]);
const capability = new Capability("documentation", toolbox, manual);

Playbook

Playbooks define named "plays" with Zod-validated parameters and error-envelope semantics. Errors in PlayDefinition.execute are caught and returned as { error: message }.

import { z } from "zod";
import { Playbook, type PlayDefinition } from "@agentic-patterns/core";

class AnalysisPlaybook extends Playbook {
  readonly name = "analysis";
  readonly description = "Data analysis plays";
  readonly plays: Record<string, PlayDefinition> = {
    summarize: {
      description: "Summarize a dataset",
      parameters: z.object({ data: z.string() }),
      execute: async (args) => ({ summary: `Analyzed: ${args.data}` }),
    },
  };
}

// Integrate into a Capability
const capability = new Capability("analysis", toolbox, manual, new AnalysisPlaybook());
capability.getTools(); // includes both toolbox tools and playbook play schemas

Definitions module provides Zod schemas for workflow configuration: WorkflowStep, RuleDefinition, TemplateDefinition, EscalationTrigger, StateDefinition, PriorityDefinition, IssueTypeDefinition, HealthSignal.

Rendering (`src/rendering/`)

Section-based prompt composition. The PromptRenderer assembles sections into a complete system prompt.

Section	Content
`IdentitySection`	Persona, tone, recovery
`BoundariesSection`	Responsibilities
`CapabilitiesSection`	Capabilities with tools and manuals
`ContextSection`	Background, awareness
`MissionSection`	Objective, constraints, output schema
`MethodologySection`	Judgments, process guidelines
`StateSection`	Current state, phase, progress

import {
  PromptRenderer,
  IdentitySection,
  BoundariesSection,
  CapabilitiesSection,
  ContextSection,
  MissionSection,
  MethodologySection,
} from "@agentic-patterns/core";

const renderer = new PromptRenderer(
  new IdentitySection(persona, responsibilities),
  new BoundariesSection(judgments),
  new CapabilitiesSection(capabilities),
  new ContextSection(background, awareness),
  new MissionSection(mission),
  new MethodologySection(judgments),
);

const systemPrompt = renderer.renderInitial();

Organisms (`src/organisms/`)

High-level builders that compose atoms and molecules into complete agent definitions.

RoleBuilder -- fluent API for reusable agent templates:

import { RoleBuilder } from "@agentic-patterns/core";

const role = new RoleBuilder("analyst")
  .withPersona(persona)
  .withJudgment(judgment)
  .withResponsibility(responsibility)
  .withCapability(capability)
  .withDefaultModel("claude-sonnet-4-20250514")
  .build();

AgentBuilder -- instantiate a role with runtime context:

import { AgentBuilder } from "@agentic-patterns/core";

const agent = new AgentBuilder(role)
  .withBackground(background)
  .withAwareness(awareness)
  .withMission(mission)
  .withModel("claude-sonnet-4-20250514")
  .build();

// Prompt rendering
const systemPrompt = agent.getSystemPrompt();
const initialPrompt = agent.renderInitialPrompt();

The Agent class provides:

getSystemPrompt() -- full system prompt via PromptRenderer
renderInitialPrompt() -- system + context + mission for first message
renderContinuationPrompt(state) -- state + mission + methodology for follow-ups
getTools() -- all ToolSchema instances from capabilities
getModel() -- model string from agent or role default