Agent Overview

Agent is one of Elftia's core capabilities. It elevates AI beyond passively answering questions, giving it the ability to proactively execute tasks — reading and writing files, running commands, searching the web, calling external tools, and even coordinating multiple sub-Agents working in parallel.

What Is an Agent

In traditional chat, AI can only produce text. In Agent mode, AI can:

1. Analyze the task — understand your request and formulate an execution plan
2. Call tools — read files, edit code, run commands
3. Iterate — check results, correct errors, continue execution
4. Return results — provide a final response once the task is complete

This "think → act → observe → think again" cycle is called the Agent Loop.

User message → Engine dispatch → LLM thinks → Tool call → Observe result → Continue loop or return reply
                                      ↑                                           ↓
                                      └───────────────────────────────────────────┘

Multi-Engine Architecture

Elftia supports multiple Agent engines, each suited to different scenarios:

Engine Type	ID	Description	Best For
TinyElf	tinyelf	Elftia's built-in lightweight Agent engine	Daily coding, file operations, automation tasks
Claude SDK	claude-sdk	Based on Anthropic's official Agent SDK	Scenarios requiring Claude's native toolchain
CLI Runner	cli	External command-line tools (Claude Code, Codex)	Using external CLI Agents
Chat	chat	Pure chat engine (no tool calls)	Simple Q&A, translation, writing
STChat	st-chat	Single-turn conversation engine	Fast single-turn tasks
API	api	Lightweight API calls	Non-chat scenarios like media generation

TinyElf Engine

TinyElf is Elftia's default Agent engine, with the following characteristics:

• In-process execution — no need to spawn subprocesses or proxy servers; starts quickly
• Multi-LLM support — adapts to any LLM provider via TinyElfLLMAdapter
• Built-in toolchain — file read/write, shell commands, web search, MCP tools
• Sub-Agent collaboration — supports foreground and background sub-Agents running in parallel
• Skill system — can load reusable SKILL.md skill instructions
• Security controls — three-layer security (firewall + guardian Agent + permission confirmation)

Claude SDK Engine

Based on @anthropic-ai/claude-agent-sdk, suited for scenarios requiring Claude's native capabilities:

• Uses Claude's official preset system prompts and tools
• Supports non-Anthropic providers (via built-in proxy server for format conversion)
• Multi-API Key load balancing

CLI Runner Engine

Manages external CLI tool processes via ProcessSupervisor:

• Supports Claude Code CLI and Codex CLI
• PTY terminal mode and standard subprocess mode
• Automatic timeout handling and output parsing

Core Capabilities

Tool Calls

Agents can use a variety of tools to complete tasks:

Tool Category	Tools	Description
File system	Read, Write, Edit, ListDir, Glob, Grep	Read, write, and search project files
Shell	Bash	Execute terminal commands
Web	WebSearch, WebFetch	Search and fetch web content
Sub-Agent	spawn_agent	Launch sub-Agents to handle subtasks
Session management	SessionsSpawn, SessionsList, SessionsSend	Cross-session collaboration
Skills	list_skills, read_skill	View and read skill content
MCP	mcp__* (dynamically loaded)	External MCP server tools
Control	Notify, SessionsYield	Notifications and flow control

Sub-Agent Collaboration

Agents can launch sub-Agents to handle subtasks in parallel:

• Foreground sub-Agent — blocks and waits for the result, returns it directly to the parent Agent
• Background sub-Agent — runs asynchronously in the background; results are injected into the parent loop when complete
• Agent config inheritance — sub-Agents can inherit the parent Agent's MCP tools and skills
• Security inheritance — sub-Agents inherit the parent Agent's security settings and permission mode

Skill System

Skills are reusable instruction sets that exist as SKILL.md files:

• Project skills — placed in .claude/skills/, shared within the project
• Personal skills — placed in ~/.claude/skills/, available globally
• Community skills — search and install via SkillHub

Agent Gallery

Elftia comes with a variety of pre-configured Agents covering different scenarios:

• Programming assistant, code review, test writing
• Documentation writing, translation and proofreading
• Research analysis, data processing
• Task automation, workflow orchestration

Agents Page: Flat Single-Layer Model

Version 0.1.7 completed a two-step merge — there is no longer a "Persona / Avatar / Agent three-layer structure." All agents are managed in a single grid on the Agents page (/agents).

One agent = one independent conversation target

Page layout:

• Left category bar: 13 categories (Featured, My, Work, Coding, Creative, Research, Writing, Life, Education, Entertainment, Social, Automation, Tools)
• Top search: match by agent name / description / tags
• Right grid: cards for all built-in + user-defined agents

Built-in agents

• Clawia — general-purpose Agent, the main conversation entry point
• Cocoia — dedicated to scheduled tasks
• Canvas — visual prototyping
• ClaudeCode — code development
• Design Studio — design workbench
• Artia — creative assistant
• Dynamically loaded datia-class packages: Deep Research, Visual Layout, Novel Writer, etc.

The underlying media generation agents (Chat / Image / Video / Music) remain in the system and are invoked through their dedicated panel entry points; they are not individually exposed on the Agents page.

Data Migration Notes

Underlying data migration is performed automatically on upgrade:

• v82 (0.1.7, step one): reverts to flat agent model; Canvas / ClaudeCode previously under Codia are split into independent top-level agents
• v87 (0.1.7, step two): merges the underlying Persona and Agent tables into a single agent table, simplifying the data model

Historical sessions are fully preserved: sessions that previously belonged under Codia are now independently listed under the agent they used; no historical messages are lost. If rollback is needed, the support team can restore using snapshot files under <userData>/migrations/.

Quick Start

Using a Built-in Agent

1. Open the Agent panel (Agent icon in the sidebar)
2. Browse the Agent gallery and select a suitable Agent
3. Start a conversation — the Agent will automatically call the tools it needs

Creating a Custom Agent

1. Click "Create Agent" in the Agent panel
2. Set the name, description, and system prompt
3. Choose available tools and permission mode
4. Save and start using it

For detailed steps, see Creating Custom Agents.

FAQ

Problem	Cause	Solution
Agent cannot execute tools	Engine type is chat (no tool support)	Switch to the tinyelf or claude-sdk engine
Tool execution requires frequent confirmation	Permission mode is default	Set to acceptEdits or bypassPermissions
Agent loop stops too quickly	maxIterations is set too low	Increase the max iterations count (default: 40)
MCP tools not appearing	No MCP server associated	Add an MCP server in the Agent configuration
Sub-Agent execution fails	Sub-Agent config file is invalid	Check the format of .claude/agents/*.md

Related Links

• Built-in Agents — Browse and use preset Agents
• Creating Custom Agents — Write your own Agent configuration
• Tool Permissions & Security — Permission modes and security settings
• Skill System — Using and creating skills