Understanding the Role of the CraftAgent Class in Craft Agents

The CraftAgent class serves as the central SDK façade that provides a unified, model-agnostic API for interacting with AI backends while managing sessions, tool permissions, and event normalization.

The CraftAgent class (now primarily exported as ClaudeAgent with a backward-compatible alias) represents the primary developer interface in the Craft Agents open-source ecosystem. Located in the craft-ai-agents/craft-agents-oss repository, this class abstracts away the complexity of underlying AI providers like Anthropic Claude and Pi, offering a consistent entry point for building AI-driven applications.

Core Responsibilities of the CraftAgent Class

Unified API Entry Point

The CraftAgent class provides a single, stable constructor (new CraftAgent()) that applications can use regardless of which underlying AI model is actually running. This design eliminates the need for developers to manage provider-specific initialization logic, allowing code written against the Craft Agents SDK to remain portable across different model backends.

Backend Abstraction and Provider Detection

At runtime, the class delegates to concrete backends through the abstraction layer defined in packages/shared/src/agent/backend/index.ts. The detectProvider() function identifies the available AI provider (Anthropic Claude or Pi), while createBackend() instantiates the appropriate implementation. This architecture keeps the rest of the codebase agnostic of model-specific SDKs, with the concrete logic residing in packages/shared/src/agent/claude-agent.ts and corresponding Pi implementations.

Session Management and Tool Orchestration

The class manages chat sessions and coordinates tool usage through functionality exported from packages/shared/src/agent/session-scoped-tools.ts. It handles streaming responses, spawning processes, and calling external services within the context of a managed session. The invoke(), invokeStream(), and invokeSpawn() methods provide different interfaces for executing agent operations depending on whether you need synchronous results, streaming tokens, or subprocess execution.

Permission-Mode Enforcement

Security boundaries are enforced through integration with the global mode manager (packages/shared/src/agent/mode-manager.ts). Before executing tool calls, the CraftAgent consults the current permission mode (e.g., SAFE or UNSAFE) to automatically filter allowed operations. This ensures that potentially dangerous actions require explicit opt-in through the permission system.

Event Normalization and Telemetry

The class transforms backend-specific events into a common CraftAgentEvent shape through adapters like packages/shared/src/agent/backend/pi/event-adapter.ts. This normalization ensures that downstream consumers receive a consistent event structure regardless of whether the underlying provider is Claude or Pi, simplifying logging, monitoring, and event handling across the application.

Implementation Architecture

The CraftAgent class extends the abstract BaseAgent class defined in packages/shared/src/agent/base-agent.ts, which establishes the common interface that all backend implementations must fulfill. The actual export structure in packages/shared/src/agent/index.ts provides backward compatibility through aliasing:

export * from './claude-agent.ts';
export { ClaudeAgent as CraftAgent };
export type { ClaudeAgentConfig as CraftAgentConfig };

This dual-export strategy allows existing codebases to continue importing CraftAgent while new development can adopt the more explicit ClaudeAgent naming convention.

Practical Code Examples

Basic Initialization with Backward Compatibility

import { CraftAgent } from '@craft-agent/shared/agent';

const agent = new CraftAgent({
  model: 'claude-3-5-sonnet-20240620',
  temperature: 0.2,
});

await agent.invoke({
  prompt: 'Explain the role of the Craft Agent class in one sentence.',
});

Modern ClaudeAgent Syntax with Streaming

import { ClaudeAgent } from '@craft-agent/shared/agent';

const claude = new ClaudeAgent({ model: 'claude-3-opus-20240229' });
const stream = await claude.invokeStream({ prompt: 'List three key responsibilities.' });

for await (const chunk of stream) {
  console.log(chunk);
}

Spawning Shell Tools

await agent.invokeSpawn({
  prompt: 'List all files in the current directory.',
  workingDirectory: process.cwd(),
});

Runtime Provider Switching

import { detectProvider, createBackend } from '@craft-agent/shared/agent/backend';

const provider = await detectProvider();
const backend = await createBackend(provider, { model: 'default' });
const dynamicAgent = new (backend.agentClass)({});

Summary

• The CraftAgent class acts as the primary SDK façade, abstracting provider-specific implementations behind a unified interface.
• It handles backend detection through detectProvider() and createBackend() functions, supporting both Claude and Pi models.
• Session management and tool orchestration are core capabilities, with specialized methods for streaming, spawning, and standard invocation.
• Permission modes (SAFE/UNSAFE) are automatically enforced through integration with the mode manager before tool execution.
• Event normalization ensures consistent CraftAgentEvent structures across different backend providers via adapter patterns.
• The class maintains backward compatibility through aliasing while encouraging migration to the explicit ClaudeAgent export.

Frequently Asked Questions

Is CraftAgent the same as ClaudeAgent?

Yes, they are functionally identical. According to the source code in packages/shared/src/agent/index.ts, ClaudeAgent is the primary implementation while CraftAgent is maintained as a backward-compatible alias. New code should import ClaudeAgent for clarity, but existing implementations using CraftAgent continue to function without modification.

How does CraftAgent handle different AI providers?

The class delegates to provider-specific implementations through the backend abstraction layer in packages/shared/src/agent/backend/index.ts. At runtime, detectProvider() identifies the available AI service, and createBackend() instantiates the appropriate concrete class. This allows the same CraftAgent API to work with Anthropic Claude, Pi, or future providers without code changes.

What permission modes does CraftAgent support?

The class integrates with the mode manager (packages/shared/src/agent/mode-manager.ts) to support permission modes including SAFE and UNSAFE. These modes act as gatekeepers for tool execution, with SAFE mode restricting potentially dangerous operations like file system modifications or network requests, while UNSAFE mode allows broader tool access for specific use cases.

How does CraftAgent normalize events from different backends?

Through adapter modules like packages/shared/src/agent/backend/pi/event-adapter.ts, the class transforms provider-specific event structures into the standardized CraftAgentEvent type. This ensures that regardless of whether the underlying backend is Claude or Pi, downstream consumers receive events in a consistent format with uniform property names and payload structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}