What Types of Agents Can Be Developed for Apache Maka: A Complete Guide

Apache Maka supports diverse agent types—from coding assistants and web-search bots to computer-use controllers and custom domain-specific harnesses—through its pluggable subject and executor interfaces.

Apache Maka is architected as a local-first, agent-centric workspace where each agent operates as a self-contained harness driving a specific model, toolset, and policy loop. According to the Apache Maka source code, the runtime exposes pluggable interfaces that enable developers to construct specialized agents without modifying the core runtime, making the framework highly extensible for domain-specific AI workflows.

Built-In Agent Types in Apache Maka

The repository includes several reference implementations that demonstrate different agent capabilities. These built-in agents serve as templates for configuring model connections, permission policies, and context management strategies.

Core Maka Agent

The default harness runs a model while enforcing context-budget constraints and pruning stale tool results. In the source code, this is implemented as maka_agent:MakaAgent and serves as the baseline for evaluation benchmarks such as the DeepSeek comparison reports.

OpenCode Agent

A "pure-mode" agent that relies on automatic permission handling and the "max" model variant. Referenced as opencode_agent:MakaOpenCodeAgent in benchmark configurations, this agent demonstrates permissive policy configurations suitable for open-ended coding tasks.

Kimi Code Agent

A coding-focused agent that ships with a large pre-built instruction set but notably does not apply Maka's context-budget policy, allowing for longer conversational contexts. The implementation kimi_code_agent:MakaKimiCodeAgent appears in the Kimi Code versus Maka comparison documentation.

Model-Specific Agents (Codex, Claude Code, Reasonix)

Apache Maka includes agents tailored to specific model providers:

• Codex Agent (codex_agent:MakaCodexAgent): Runs with full-tool surface permissions including container-full-access for comprehensive sandboxed execution.
• Claude Code Agent (claude_code_agent:MakaClaudeCodeAgent): Configured with a bypassPermissions policy for the Anthropic Claude model.
• Reasonix Agent (reasonix_agent:MakaReasonixAgent): Optimized for streaming JSON output with auto-permissions handling.

Specialized Agent Categories

Beyond the built-in model-specific implementations, Apache Maka supports distinct agent categories that extend functionality into specific operational domains.

Computer-Use Agents

These agents control the host operating system via a sandboxed "computer-use" backend, handling mouse and keyboard events, file I/O, and screen interactions. The implementation resides in packages/computer-use/src/ with interface contracts documented in docs/computer-use-foundation-contract.md. These agents enable automation of graphical user interfaces and system-level operations.

Web-Search Agents

Agents that expose web-search capabilities as tools, with inheritance scoped explicitly to child agents. The architecture document docs/web-search-provider-capability.md outlines how these agents access search providers while maintaining strict permission boundaries. Tool visibility is controlled through the agent profile's tools array configuration.

Custom Domain-Specific Agents

Developers can create entirely new agent harnesses by defining custom subjects (how the agent is invoked) and executors (how trials run). As documented in packages/eval/README.md, new agents require only a profile JSON file and registration via the @maka/eval runner, without requiring changes to the core runtime.

How Apache Maka Defines an Agent

An agent in Apache Maka is fundamentally defined by a profile that specifies three critical components: the model connection, the tool surface, and the permission policy. The runtime consumes this profile to instantiate a session and execute the agent loop.

The Agent Loop and Event Flow

According to packages/runtime/src/ai-sdk-backend.ts, the agent loop processes model output, executes tool calls, performs permission checks, and persists results. The runtime creates an append-only log in runtime.sqlite, making every turn reproducible and auditable. The event flow follows: model inference → tool calls → permission validation → tool execution → log entry → updated model prompt.

Subject and Executor Interfaces

The pluggable architecture relies on subject and executor interfaces defined in packages/eval/src/runner.ts. The subject determines how the agent is invoked, while the executor defines how individual trials run. This separation allows developers to swap agent implementations without affecting the evaluation framework or runtime core.

Building a Custom Apache Maka Agent

Creating a custom agent requires defining a profile, registering it with the evaluation harness, and executing tasks through the CLI. The following examples demonstrate the complete workflow using the @maka/eval package.

First, create a profile file named my-agent.provider-usage.json:

{
  "profile": "my-agent",
  "model": {
    "type": "openai",
    "modelId": "gpt-4o-mini",
    "apiKeyEnv": "OPENAI_API_KEY"
  },
  "tools": ["web-search", "filesystem", "shell"],
  "permissions": {
    "allowShell": false,
    "allowFilesystem": true,
    "allowNetwork": true
  },
  "deadlinePolicy": {
    "turnTimeoutSec": 900,
    "gracePeriodSec": 30
  },
  "contextBudget": {
    "maxTokens": 2048,
    "pruneStale": true
  }
}

This profile follows the schema referenced in packages/eval/src/runner.ts, specifying model connection details, exposed tools, and execution boundaries.

Next, register the profile with the evaluation harness:

npx --yes --package muka-agent@nightly muka eval register-profile \
  --profile ./my-agent.provider-usage.json

The CLI commands are documented in packages/cli/README.md.

Execute a task using the newly registered agent:

npm run cli:dev -- run \
  --profile my-agent \
  "Write a short summary of the repository and list its key components."

The runtime loads the profile, instantiates the subject and executor, dynamically surfaces the declared tools, and logs each RuntimeEvent to runtime.sqlite.

To access the persistent execution log programmatically:

import { openDatabase } from '@maka/storage';

async function printLog() {
  const db = await openDatabase('runtime.sqlite');
  const rows = await db.all('SELECT * FROM events ORDER BY timestamp');
  console.table(rows);
}
printLog();

The packages/storage module implements the SQLite schema used by all agents for event persistence.

Key Source Files for Agent Development

Understanding the Apache Maka agent architecture requires familiarity with specific source files that define the runtime behavior and extension points:

• packages/runtime/src/ai-sdk-backend.ts: Implements the core agent loop that processes model output, tool calls, and permission checks.
• packages/eval/src/runner.ts: Defines the subject and executor plugin points that enable custom agent harnesses.
• packages/cli/README.md: Documents CLI commands for registering profiles and running agents from the terminal.
• docs/eval/terminal-bench-2.1-deepseek-v4-flash-maka-vs-opencode.md: Provides concrete benchmark comparisons of built-in agent performance.
• packages/computer-use/src/: Contains implementations for computer-use agents that interact with the host OS.
• docs/web-search-provider-capability.md: Outlines the web-search tool integration available to agents.

Summary

• Apache Maka supports modular agent development through pluggable subject and executor interfaces, allowing custom harnesses without core runtime modifications.
• Built-in agent types include Core Maka, OpenCode, Kimi Code, Codex, Claude Code, and Reasonix agents, each optimized for specific models and permission policies.
• Specialized categories such as computer-use and web-search agents extend functionality into GUI automation and information retrieval domains.
• Agent behavior is controlled through JSON profiles that specify model connections, tool surfaces, permission policies, deadline constraints, and context budgets.
• All agent executions are persisted to SQLite (runtime.sqlite), ensuring reproducibility and auditability of every interaction turn.

Frequently Asked Questions

What is the primary difference between the Core Maka Agent and the Kimi Code Agent?

The Core Maka Agent enforces strict context-budget policies and prunes stale tool results to maintain performance, while the Kimi Code Agent ships with a large pre-built instruction set and does not apply Maka's context-budget constraints, allowing for extended conversational contexts without pruning.

How do I add custom tools to an Apache Maka agent?

Custom tools are exposed by modifying the tools array in the agent's profile JSON. The runtime dynamically surfaces these tools to the model based on the profile configuration, and tool implementations are resolved through the executor interface defined in packages/eval/src/runner.ts.

Can Apache Maka agents run entirely offline with local models?

Yes, the agent profile supports local model connections through the model configuration object. By specifying a local model type and endpoint rather than cloud API keys, agents can operate in air-gapped environments while maintaining full functionality for tool execution and permission management.

Where are agent execution logs stored in Apache Maka?

All agent execution logs are stored in an append-only SQLite database named runtime.sqlite in the working directory. The @maka/storage package provides the schema and access layer for querying these logs, which record every model inference, tool call, and permission check for complete audit trails.

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