What Are Agent Native Software Principles in Craft Agents?

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 (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, 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 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: 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.

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, 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 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). 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 and apps/electron/resources/docs/data-tables.md.

Implementation in Code

Adding Sources Through Conversation

// 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, callable directly by the LLM through its documented contract.

Defining Reusable Skills

{
  "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:

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

Managing Permission Modes

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

Running Headless Mode

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: 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) 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, these prompts describe behaviors the LLM executes, requiring no compiled code or traditional plugin installation.

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