GLYPH Agents

Provider-agnostic Agent SDK for the GLYPH platform. This package defines how agents observe context, recall scoped memory, plan goals, request approval, delegate workflows, observe results, reflect, and reach a terminal outcome.

Agents never invoke connectors directly. All execution crosses an injected WorkflowDelegator boundary and uses @glyph-platform/workflows definitions/results. @glyph-platform/core is the shared platform-contract dependency. Provider adapters, application behavior, UI, and workflow execution do not belong here.

Canonical lifecycle

created → initialized → observing → planning
                                   ├─→ waiting_approval
                                   └─→ executing_workflow
                                         ↓
                                   observing_result
                                         ↓
                                     reflecting
                                         ↓
                            completed | failed | cancelled

The lifecycle manager rejects skipped transitions and all transitions from terminal states.

SDK modules

• runtime: agent factory, registry, lifecycle orchestration, workflow delegation
• lifecycle: canonical states and deterministic transition manager
• planning: goal decomposition, validated plans, stable task DAG layers
• memory: run/agent/profile scopes, store interface, context resolution
• reasoning: observations, confidence, decisions, and reflection interfaces
• tools: tools propose workflows; they cannot execute connectors
• permissions: typed allow/approval/deny decisions
• events: strongly typed lifecycle event publishing
• types: public agent, goal, plan, task, context, and observation contracts

Runtime composition

import {
  AgentFactory,
  AgentRegistry,
  AgentRuntime,
  ContextResolver,
  DefaultDecisionPolicy,
  EventPublisher,
  GoalPlanner,
  InMemoryAgentMemory,
  LifecycleManager,
  ObservationCollector,
  PlanApprovalPermissionPolicy,
  PlanBuilder,
} from "@glyph-platform/agents";

const registry = new AgentRegistry();
const factory = new AgentFactory();
const lifecycle = new LifecycleManager();
const memory = new InMemoryAgentMemory();
const context = new ContextResolver(memory);
const observations = new ObservationCollector([]);
const events = new EventPublisher();

const planner = new GoalPlanner(
  {
    async decompose(goal) {
      return {
        tasks: taskDecomposer(goal), // returns tasks with WorkflowDefinition values
        rationale: `Plan for ${goal.id}`,
        confidence: 0.8,
      };
    },
  },
  new PlanBuilder(),
);

Inject a WorkflowDelegator, Reflector, PermissionPolicy, and DecisionPolicy when creating AgentRuntime. The delegator may wrap WorkflowEngine; the agent package never imports or constructs connector executors.

Tools

A Tool accepts a typed ToolInvocation and returns a ToolProposal containing a provider-neutral WorkflowDefinition. A tool is a planning abstraction, not an execution escape hatch. The runtime still applies permission policy and delegates the proposed workflow through glyph-workflows.

Memory

AgentMemory is an injected interface. The included in-memory adapter supports:

• run: current execution only
• agent: reusable by one agent definition
• profile: reusable within one profile

Callers own persistence, retention, sensitivity, and deletion policy.

Development

npm ci
npm run typecheck
npm test
npm run test:coverage
npm run build