Agent

An agent package defines an autonomous or semi-autonomous AI agent. Agents typically bind to multiple tools, carry a system prompt, and declare model preferences. Use this type when your package orchestrates a workflow rather than providing a single capability.

Manifest

An agent package sets "type": "agent" in apkg.json and can include an optional agent object:

{
  "name": "@acme/research-agent",
  "version": "0.8.0",
  "type": "agent",
  "description": "Autonomous research agent",
  "license": "MIT",
  "agent": {
    "tools": [
      { "name": "web-search", "package": "@acme/web-search", "required": true },
      { "name": "formatter", "package": "@acme/fmt", "required": false }
    ],
    "systemPrompt": "prompts/system.md",
    "modelPreference": ["claude-sonnet-4-6"]
  }
}

Agent-specific fields

Field	Type	Description
tools	object[]	Tools the agent depends on — each with name, package, and required
systemPrompt	string	Inline system prompt text, or a file path (e.g. prompts/system.md)
modelPreference	string[]	Ordered list of preferred model IDs

Tool object

Field	Type	Default	Description
name	string	—	Display name for the tool
package	string	—	Scoped package name
required	boolean	true	Whether the tool is required

System prompt resolution

The systemPrompt field can be:

• Inline text: "You are a research assistant." — used as-is.
• A file path: "prompts/system.md" — the file is read from the package directory at setup time.

Tool setup

When you install an agent package, apkg configures your AI coding tools similarly to skill packages, with additional agent-specific content. For Claude Code, definition files are copied into:

.claude/agents/@<scope>/<name>/

If no definition files are found, a summary is generated that includes the resolved system prompt, tool bindings with required/optional status, and preferred models.

See Tool Setup Explained for the generic mechanism, and Agents — Tool Integration for how each tool maps system prompts, tool bindings, and model preferences.

Example

Create an agent package:

mkdir my-agent && cd my-agent
apkg init
# Choose type: agent

Add a system prompt file:

mkdir prompts

prompts/system.md

You are a research assistant. Search the web for relevant information,
synthesize findings, and present a structured summary.

Add a definition file for Claude Code:

---
name: research-agent
description: Searches the web and synthesizes findings
tools: WebSearch, Read, Write
---

You are a research agent. Use web search to find information,
then synthesize and summarize your findings.

Publish it:

apkg publish