# Where to Find Maka's Agent Catalog and Built-In Agent Definitions

> Locate Maka's agent catalog and built-in agent definitions within the runtime package at packages/runtime/src/agent-catalog.ts. Discover exported definitions and helper functions easily.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Maka's complete agent catalog and built-in agent definitions live in [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts)**, which exports the `BUILTIN_AGENT_DEFINITIONS` array and helper functions like `listBuiltinAgentDefinitions()` and `requireBuiltinAgentDefinitionByProfile()`.

The **agent catalog** is the single source of truth for all built-in agents in the Apache Maka framework. Whether you need to introspect available agents, spawn sub-agents programmatically, or understand the capabilities of the `Implementation` agent versus `Local Read`, the definitions are centralized in one runtime module. This article maps exactly where to find these definitions and how to use them.

## The Core File: [`agent-catalog.ts`](https://github.com/apache/maka/blob/main/agent-catalog.ts)

All built-in agent definitions reside in [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts). This module declares three canonical agent types and exposes them through a clean programmatic API.

### Built-In Agent Definitions

According to the Apache Maka source code, the file defines these symbol exports:

| Symbol | Purpose | Line Range |
|--------|---------|------------|
| `BUILTIN_AGENT_DEFINITIONS` | Array containing all three `AgentDefinition` objects | L22-L26 |
| `LOCAL_READ_AGENT_DEFINITION` | Read-only agent (no write tools) | L37-L60 |
| `WEB_RESEARCH_AGENT_DEFINITION` | WebSearch-only agent for research tasks | L61-L84 |
| `IMPLEMENTATION_AGENT_DEFINITION` | Full toolset agent with worktree workspace and patch write-back | L86-L120 |
| Helper functions (`listBuiltinAgentDefinitions`, `getBuiltinAgentDefinition`, `requireBuiltinAgentDefinition`) | Runtime API for catalog access | L122-L158 |

The `IMPLEMENTATION_AGENT_DEFINITION` represents Maka's most capable agent, configured with an isolated context, worktree workspace, and `patch` as its default write-back mechanism. The `LOCAL_READ_AGENT_DEFINITION` provides a safer, read-only alternative for scenarios requiring minimal side effects.

## How the Runtime Consumes the Catalog

The sub-agent tooling layer imports directly from this catalog. In [`packages/runtime/src/subagent-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/subagent-tools.ts), lines 26-35 show the dependency chain:

```typescript
import {
  BUILTIN_AGENT_DEFINITIONS,
  agentProfilesForDefinitions,
  buildToolsForAgentDefinition,
  requireAgentDefinitionByProfile,
  type AgentDefinition,
} from './agent-catalog.js';

```

This import pattern demonstrates how Maka's **agent catalog** propagates through the runtime: the catalog module provides definitions, and [`subagent-tools.ts`](https://github.com/apache/maka/blob/main/subagent-tools.ts) transforms them into invocable tool implementations like `agent_spawn`, `agent_list`, and `agent_output`.

## Programmatic Access to Agent Definitions

### List All Built-In Agents

Use `listBuiltinAgentDefinitions()` to enumerate available agents at runtime:

```typescript
import { listBuiltinAgentDefinitions } from '@maka/runtime/agent-catalog';

const agents = listBuiltinAgentDefinitions();
console.log(agents.map(a => `${a.name} (${a.profile})`));

```

**Output:**

```

Local Read (local_read)
Web Research (web_research)
Implementation (implementation)

```

### Retrieve a Specific Agent by Profile

For type-safe access with error throwing, use `requireBuiltinAgentDefinitionByProfile()`:

```typescript
import { requireBuiltinAgentDefinitionByProfile } from '@maka/runtime/agent-catalog';

const implDef = requireBuiltinAgentDefinitionByProfile('implementation');
console.log(implDef.contract);

```

**Output:**

```json
{
  "capability": "implementation",
  "invocation": "foreground",
  "context": "isolated",
  "workspace": "worktree",
  "defaultWriteBack": "patch",
  "supportedWriteBack": ["patch"]
}

```

The `contract` property reveals critical runtime behavior: the `implementation` agent runs in **foreground** invocation with **isolated** context and **worktree** workspace semantics.

### Access the Raw Definition Array

For direct manipulation or custom tooling, import `BUILTIN_AGENT_DEFINITIONS`:

```typescript
import { BUILTIN_AGENT_DEFINITIONS } from '@maka/runtime/agent-catalog';

function printAgentTools() {
  for (const def of BUILTIN_AGENT_DEFINITIONS) {
    console.log(`${def.name}: ${def.tools.join(', ')}`);
  }
}
printAgentTools();

```

**Output:**

```

Local Read: Read, Glob, Grep
Web Research: WebSearch
Implementation: Read, Glob, Grep, Write, Edit, apply_patch, Bash, WriteStdin, StopBackgroundTask

```

This reveals the **capability gradient** across Maka's built-in agents: from 3 read-only tools (`Local Read`) to 9 tools including `apply_patch` and `Bash` (`Implementation`).

## Key Files for Agent Catalog Reference

| File | Role | Direct Link |
|------|------|-------------|
| [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts) | Canonical definitions and catalog API | [View source](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts) |
| [`packages/runtime/src/subagent-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/subagent-tools.ts) | Catalog consumer—builds spawn/list/output tools | [View source](https://github.com/apache/maka/blob/main/packages/runtime/src/subagent-tools.ts) |
| [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) | Runtime plumbing for tool registration | [View source](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) |
| [`packages/runtime/src/__tests__/configured-subagent-catalog.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/configured-subagent-catalog.test.ts) | Test verification of catalog behavior | [View source](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/configured-subagent-catalog.test.ts) |

## Summary

- **Agent catalog location**: [`packages/runtime/src/agent-catalog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-catalog.ts) contains all built-in agent definitions in Apache Maka.
- **Primary export**: `BUILTIN_AGENT_DEFINITIONS` array holds `AgentDefinition` objects for `Local Read`, `Web Research`, and `Implementation`.
- **Runtime access**: Use `listBuiltinAgentDefinitions()`, `getBuiltinAgentDefinition()`, or `requireBuiltinAgentDefinitionByProfile()` for programmatic access.
- **Downstream consumption**: [`subagent-tools.ts`](https://github.com/apache/maka/blob/main/subagent-tools.ts) imports these definitions to construct the `agent_spawn`, `agent_list`, and `agent_output` tools.
- **Capability inspection**: Each definition includes `tools`, `contract`, and metadata fields describing invocation mode, workspace type, and write-back support.

## Frequently Asked Questions

### What is the difference between `getBuiltinAgentDefinition` and `requireBuiltinAgentDefinitionByProfile`?

`getBuiltinAgentDefinition` returns `undefined` when an agent profile is not found, making it suitable for conditional checks. `requireBuiltinAgentDefinitionByProfile` throws an error on missing profiles, enforcing runtime contracts. Both functions resolve against the same `BUILTIN_AGENT_DEFINITIONS` array in [`agent-catalog.ts`](https://github.com/apache/maka/blob/main/agent-catalog.ts).

### Can I extend Maka with custom agents through the agent catalog?

The built-in catalog is immutable at runtime—the `BUILTIN_AGENT_DEFINITIONS` array is frozen to the three canonical agents. Custom agents require separate registration through Maka's agent configuration system, not modification of the core catalog module.

### Why does the `Implementation` agent use `patch` as its default write-back?

The `IMPLEMENTATION_AGENT_DEFINITION` specifies `defaultWriteBack: "patch"` and `supportedWriteBack: ["patch"]` in its contract (lines 86-120 of [`agent-catalog.ts`](https://github.com/apache/maka/blob/main/agent-catalog.ts)). This design isolates changes to discrete patch files in the worktree workspace, enabling atomic application and review before modifying the primary workspace.

### How do I verify which tools a built-in agent supports?

Import `BUILTIN_AGENT_DEFINITIONS` and inspect the `tools` property of each `AgentDefinition`. The array contains string identifiers like `"Read"`, `"WebSearch"`, or `"apply_patch"` that map to tool implementations in the runtime.