# Understanding the Role of the CraftAgent Class in Craft Agents

> Discover the core functionality of the CraftAgent class. It acts as an SDK façade, offering a unified API for AI backends, managing sessions, permissions, and events.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: documentation
- Published: 2026-07-04

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/agent/index.ts) provides backward compatibility through aliasing:

```typescript
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

```typescript
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

```typescript
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

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

```

### Runtime Provider Switching

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.