Agents

An agent is a named persona living inside an APC project. It has a name, a description, an optional model override, a language preference, and an optional set of skills. Its canonical definition is a single Markdown file at .apc/agents/<slug>.md.

The agent definition file

---
name: reviewer
model: inherit
description: Reviews PRs and pushes back on hand-wavy diffs.
role: Code reviewer
language: es
tools: read,write,run
skills: code-review,git
color: indigo
emoji: 🔍
vibe: Concrete feedback, no hand-waving.
---

name and description are required. Use model: inherit unless the project truly requires a specific model — this lets each runtime (Codex, Claude Code, Cursor, APX) apply its own configured default.

• Directory.apc/

  • Directoryagents/

    • reviewer.md agent definition

Agent runtime data is local and uncommitted:

~/.apx/projects/<project_id>/agents/reviewer/memory.md

Note

AGENTS.md at the repo root is auto-generated by apx agent add and apx agent remove. Do not edit it by hand — your changes will be overwritten on the next apx agent write. Its purpose is discovery: tools like Codex, Claude Code, and other APC-aware runtimes read it to learn which agents exist in a project.

Required and optional fields

Field	Required	Purpose
name	Yes	Stable agent slug used in commands and file name
model	Yes	Use inherit unless the project truly requires a specific model
description	Yes	Semantic activation trigger and responsibility summary
role	No	Human-readable job title shown in prompts and listings
language	No	Response language preference (e.g. es, en)
tools	No	Comma-separated tool grants
skills	No	APC skills the agent commonly uses
is_background	No	Whether compatible runtimes may run the agent asynchronously
color, emoji, vibe	No	UI and personality hints for runtimes that support them

APC should not tie one vendor’s model as the default. Use inherit and let each runtime (Codex, Claude Code, Cursor, APX) apply its configured default. A specific provider:model-id is only appropriate when it is an explicit part of the project contract.

Commands

List agents

apx agent list                       # agents in the current directory's project
apx agent list --project my-app      # agents in a named project

apx

$ apx agent list
  orchestrator   super-agent (Roby)   inherit
frontend       UI engineer          inherit
backend        API engineer         inherit
researcher     web researcher       openai:gpt-4o
sofia          backend reviewer     ollama:llama3.2:3b

apx agent list — slug, role, model for every agent in the project

Add an agent

apx agent add reviewer \
  --description "Reviews PRs and pushes back on hand-wavy diffs." \
  --role "Code reviewer" \
  --model inherit \
  --language es \
  --tools read,write,run \
  --skills code-review,git

This writes .apc/agents/reviewer.md and regenerates AGENTS.md.

Inspect an agent

apx agent get reviewer              # full definition + memory excerpt
apx agent show reviewer             # alias

Import from the vault

The vault is a global library of reusable agent templates kept in ~/.apx/agents/. APX ships bundled defaults (a cody code assistant, a doc writer, and so on); you can add your own.

apx agent vault list                 # see bundled defaults + your overrides
apx agent import cody                # register the vault template in this project
apx agent import cody --copy         # copy the .md into .apc/agents/ for local edits
apx agent import cody --force        # overwrite an existing local definition

Vault management:

apx agent vault add <slug>           # create a new template in ~/.apx/agents/
apx agent vault rm <slug>            # hide a bundled default (tombstone)
apx agent vault restore <slug>       # un-hide a tombstoned bundled default

Per-agent model override

The recommended value is model: inherit — the agent uses whichever model the runtime has configured as its default. Set a specific provider:model-id only when the project contract explicitly requires it:

---
name: reviewer
model: inherit
---

---
name: cheap-summarizer
model: ollama:llama3.2:3b
---

Any provider:model-id string that your configured engines support works here — for example openai:gpt-4o or ollama:llama3.2:3b.

Caution

Make sure the provider you specify has an API key configured in ~/.apx/config.json. An agent with model: openai:gpt-4o will fail on first call if engines.openai.api_key is empty.

How the system prompt is built

When you call apx exec <slug> or an agent runs inside a routine, APX composes the system prompt in this order:

1. Identity block — You are <slug> + project name
2. Description from AGENTS.md
3. Role and Language fields
4. Invocation channel — engine | telegram | routine | runtime
5. Memory from ~/.apx/projects/<project_id>/agents/<slug>/memory.md (if it exists)
6. Skills declared in the agent’s skills: field
7. The apx meta-skill
8. Fixed action-discipline footer

Agents vs. the super-agent

Aspect	Super-agent (APX itself)	Project agent
Has tools?	Yes — full tool registry	No — text-in / text-out only
Execution loop	Multi-iteration tool loop	Single LLM call
System prompt	super-agent-base.md + channel template + identity	Built per-agent as above
Configured via	super_agent.* in config	.apc/agents/<slug>.md

When in doubt: the super-agent is APX itself; project agents are specialized personas you define.

Next

• Memory — curating durable facts for an agent.
• Sessions — how agent invocations are tracked.
• Agent vault — deep dive on the bundled templates.