@morphixai/agent-framework

Construction-injected agent instances over pi-agent-core. One conversation = one instance. Everything an agent touches — context, sandbox, capabilities, LLM, history — is injected at construction; nothing is ambient, nothing is global.

v2 is a ground-up rewrite. The v1 API (createAgentFramework / defineAgent / LangGraph runner) was removed entirely — see Versioning below.

Install

npm install @morphixai/agent-framework

Companions (installed as dependencies): @morphixai/agent-core (RunContext + tool-middleware onion) · @morphixai/agent-bus (parent↔child messaging) · @morphixai/agent-workspace (Sandbox hierarchy). LLM access via pi-ai.

Quick start

import { createInstance, ToolV2 } from '@morphixai/agent-framework';
import { VirtualSandbox } from '@morphixai/agent-workspace';
import { z } from 'zod';

class WriteFileTool extends ToolV2 {
  static toolName = 'write_file';
  static description = 'Write a file into the sandbox.';
  static requires = ['userId', 'appId'];               // RunContext keys gate
  static inputSchema = z.object({ path: z.string(), content: z.string() });
  async handler(ctx, { path, content }) {
    await ctx.sandbox.files.write(path, content);
    return { ok: true };
  }
}

class DashboardAgent {
  static id = 'dashboard';
  static scope = 'app' as const;      // declaration only: which binding the host supplies
  static prompt = 'You build dashboards.';
  static tools = [WriteFileTool];
  static skills = [JiraSkill];        // skills CARRY tools (see below)
  static canSpawn = [MediaAgent];     // spawn whitelist
}

const inst = createInstance(DashboardAgent, {
  context: { userId, appId, conversationId },  // frozen RunContext; lineage auto-derived
  sandbox: new VirtualSandbox(),               // or your LogicalSandbox subclass
  capabilities: { observations, connections }, // DI slot for tool handlers
  llm: { model },                              // pi-ai model (streamFn override for tests)
  history: persistedMessages,                  // rehydration = message replay
});

const r = await inst.prompt('add a weather card');
// r.status: 'completed' | 'interrupted' | 'error' | 'aborted'
// r.messages: the transcript — persist it; it IS the resumable state

Core features

• HITL (human-in-the-loop) — a tool calls ctx.requestUserInput(payload); the run ends interrupted with the payload attached. Resume by constructing the instance from the persisted transcript and calling inst.prompt(answer).
• Parent ↔ child, both directions — inst.spawn(ChildDef, opts) creates a child instance (own sandbox/context, derived lineage). The child asks up via ctx.bus.askParent(question); the parent answers deterministically with inst.onAsk(async (childRunId, question) => answer). Steering and inbox notes (bus.deliver) are injected before the next turn.
• Skills carry tools — a skill is { id, description, prompt, tools }. Descriptions are listed in the system prompt; when the agent calls the built-in load_skill, the skill's knowledge enters the conversation and its tools become callable the same run.
• Tool-middleware onion — (ctx, args, next) middleware composes at three levels (global → agent → tool): rewrite args, deny before the handler runs, emit side effects after, or wrap for timing/retry.
• Rehydration contract — no checkpointer. Persist r.messages; a new createInstance(def, { ..., history }) continues the conversation exactly.
• Testing — pi-ai createFauxCore (scripted LLM) + VirtualSandbox give a fully deterministic closed loop with zero external dependencies.
• Request-time context providers — hosts may inject temporary asynchronous context (for example a Memory recall) before provider requests. Contributions are not appended to the canonical transcript, and provider failures are observable without silently changing identity or storage scope.

Persistence is intentionally optional and lives in companion packages: @morphixai/agent-memory defines scope-bound Memory ports and @morphixai/agent-session defines canonical transcript persistence. Local JSON and JSONL adapters are explicit Node-only conveniences; production hosts can implement the same protocols with their own storage backends.

Exports

• createInstance, AgentInstance, InstanceOptions, RunResult, InstanceEvent
• ToolV2 / ToolV2Class, ToolCtxV2, AgentDefV2, SkillDefV2 / SkillDefClass
• Re-exported primitives: RunContext, Lineage, ToolMiddleware (from agent-core)

Versioning

• ≥ 1.0.0 — framework v2 (this API). The whole quartet (agent-core / agent-bus / agent-workspace / agent-framework) ships as a 1.x stable line; cross-package compatibility is guaranteed within it.
• 0.x — the legacy LangGraph-based v1. No migration path is provided; v2 is a rewrite. Pin <1.0.0 if you still depend on v1 shapes.

License

MIT © MorphixAI