# What Are Agent Native Software Principles in Craft Agents?

> Discover Agent Native software principles for Craft Agents. Empower AI with natural language control, zero-code customization, and autonomous orchestration. Learn more.

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

---

**Agent Native software principles treat AI agents as the primary users of applications, enabling natural language control, zero-code customization, and autonomous orchestration through typed tool contracts.**

Craft Agents, the open-source framework hosted at `craft-ai-agents/craft-agents-oss`, is architected around **Agent Native** design philosophy. Unlike traditional applications built for human clicks and form inputs, this software treats the AI agent as the primary user. According to the [`README.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/README.md) (lines 61-63), the core idea is that you "describe what you want, and it figures out how," allowing the agent to drive the entire product from data ingestion to UI interaction.

## Natural Language as the Primary Interface

Agent Native design replaces structured API calls with **natural-language-driven control**. The system expects the agent to understand plain English instructions, translate them into execution steps, and invoke the appropriate tools without human intervention.

### Zero-Code Customization via Prompts

Customization requires no code editor or configuration files. Instead, Craft Agents uses **prompt-driven skill definition**, where skills are JSON prompt files stored per workspace. These define reusable behaviors that the agent can invoke conversationally. As documented in [`apps/electron/resources/docs/skills.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/skills.md), users simply describe desired behaviors in natural language, and the agent executes them autonomously.

### Unified Source Integration

Adding data sources follows the same conversational flow. Whether connecting to MCP servers, REST APIs, or local files, the process is handled through the chat interface. The [`apps/electron/resources/docs/sources.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/sources.md) documentation confirms that sources are added via natural language commands (e.g., "Add Linear as a source"), allowing the agent to fetch data uniformly across disparate systems.

## Safety and Autonomous Execution

Because agents operate with minimal human oversight, Agent Native architectures require robust safety mechanisms and transparent state management.

### Permission-Based Execution Modes

Craft Agents implements **permission-mode safety** through three distinct levels defined in [`apps/electron/resources/docs/permissions.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/permissions.md): `safe`, `ask`, and `allow-all`. These govern potentially destructive operations, allowing the agent to act autonomously while preserving user control. The implementation resides in [`apps/electron/src/permissions.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/src/permissions.ts).

### Dynamic Workflow Management

The system maintains a **dynamic workflow and status system** where sessions follow mutable states (Todo → In Progress → Done). The agent manipulates these states programmatically to organize work without human intervention, as noted in the README's "Dynamic Status System" section.

### Transparent Fallback and Recovery

When native binaries (e.g., Claude SDK) are missing, the runtime automatically falls back and recovers without user intervention. This **transparent fallback** mechanism, implemented in [`agent/spawn-helpers.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/agent/spawn-helpers.ts), ensures the agent's workflow remains uninterrupted.

## Agent-First Extensibility

Extending the system requires no traditional plugin architecture. Instead, capabilities expose **typed tool contracts** that the LLM can discover and invoke as part of its planning phase.

### Typed Tool Contracts

New capabilities are added as tools with formal contracts. For instance, the search tool contract defined in [`packages/pi-agent-server/src/tools/search/SEARCH_PAYLOAD_CONTRACT.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/pi-agent-server/src/tools/search/SEARCH_PAYLOAD_CONTRACT.md) exposes a typed interface that the LLM calls during execution. This **agent-first extensibility** allows the system to grow without requiring UI changes or manual configuration.

### Headless Architecture

The **headless / thin-client mode** separates the UI from the agent engine. As documented in the README's "Remote Server (Headless)" section, the desktop UI can run as a thin client while the heavyweight agent engine executes on a remote server ([`packages/server/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server/src/index.ts)). This architecture makes the system fully separable and agent-centric.

## Native Content Rendering

Agent Native applications render content **natively** without external browsers. Diagrams, tables, PDFs, and other previews are handled directly within the application surface, allowing the agent to embed and manipulate rich content. This is documented in [`apps/electron/resources/docs/mermaid.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/mermaid.md) and [`apps/electron/resources/docs/data-tables.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/data-tables.md).

## Implementation in Code

### Adding Sources Through Conversation

```typescript
// In a chat session, the user types:
await chat.sendMessage("Add Linear as a source");

// The LLM decides to call the internal `addSource` tool:
await addSource({
  type: "mcp",
  provider: "linear",
  credentials: { apiKey: "••••••••" }   // collected interactively by the agent
});

```

The `addSource` tool implementation resides in [`packages/server-core/src/tools/addSource.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server-core/src/tools/addSource.ts), callable directly by the LLM through its documented contract.

### Defining Reusable Skills

```json
{
  "name": "quick-bug-report",
  "prompt": "When a user mentions a bug, ask for steps to reproduce, environment details, and severity, then create a GitHub issue."
}

```

The agent invokes this skill with:

```typescript
await chat.sendMessage("@quick-bug-report");

```

### Managing Permission Modes

```typescript
// Cycle permission mode (safe → ask → allow-all)
await setPermissionMode("allow-all");

```

### Running Headless Mode

```bash
CRAFT_SERVER_URL=wss://my-server:9100 CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run electron:start

```

## Summary

- **Agent Native** principles position the AI agent as the primary software user, not the human operator.
- **Natural language** serves as the sole interface for controlling the application, configuring sources, and defining skills.
- **Permission modes** (`safe`, `ask`, `allow-all`) provide safety guardrails for autonomous agent actions.
- **Typed tool contracts** enable extensibility without code changes, exposing capabilities the LLM can discover and invoke.
- **Headless architecture** separates the UI from the agent engine, supporting thin-client deployments.
- **Native rendering** allows agents to manipulate rich content directly without external browser dependencies.

## Frequently Asked Questions

### What is the difference between Agent Native and traditional API-first design?

Traditional API-first design requires developers to write structured calls against documented endpoints. Agent Native software, as implemented in Craft Agents, accepts unstructured natural language instructions and relies on the LLM to map intent to tool calls using contracts like those in `packages/pi-agent-server/src/tools/`.

### How does Craft Agents handle potentially dangerous operations autonomously?

The system employs three permission modes defined in [`apps/electron/resources/docs/permissions.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/permissions.md): `safe` blocks risky actions, `ask` prompts for confirmation, and `allow-all` grants full autonomy. This spectrum allows users to balance automation with oversight.

### Can Craft Agents run without the desktop UI?

Yes. The **headless / thin-client mode** documented in the README allows the Electron UI to run locally while connecting to a remote agent engine. Set `CRAFT_SERVER_URL` to point to the server instance ([`packages/server/src/index.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server/src/index.ts)) and run with a generated token.

### How do I add new capabilities without writing code?

You define **skills**—JSON prompt files stored in the workspace—that the agent can invoke. As documented in [`apps/electron/resources/docs/skills.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/apps/electron/resources/docs/skills.md), these prompts describe behaviors the LLM executes, requiring no compiled code or traditional plugin installation.