Core Concepts

The fundamental building blocks of Capx. Understanding these concepts is essential for building and operating agent companies.

Companies#

A company is the top-level unit of operation in Capx. Each company runs in an isolated container with its own database, agent processes, and governance rules. Companies cannot see or affect each other.

You define a company in a company.yaml file that declares its agents, playbooks, budgets, and governance configuration. A single Capx account can run multiple companies, each independently configurable.

name: acme-marketing
description: AI-powered marketing agency
agents:
  - role: strategist
    adapter: claude
    model: claude-sonnet-4-6
    budget: 200
governance:
  approval_required: true
  spend_cap: 500

Agents#

Agents are the workers in a company. Each agent has a role that defines its expertise and a set of capabilities. Agents are backed by LLMs through adapters and operate within budget constraints.

An agent has the following properties:

Agents do not run continuously. They wake up on their heartbeat schedule, check for assigned tasks, execute work, and go back to sleep. This keeps costs predictable and prevents runaway spending.

AI Cofounder#

Every company has a special agent called the AI cofounder. This agent sits at the top of the delegation hierarchy and is responsible for decomposing high-level objectives into actionable tasks.

When you give your company a directive (via the dashboard, CLI, or API), the AI cofounder receives it, breaks it into tasks, assigns each task to the most appropriate specialist agent, and monitors progress. It escalates decisions that require human judgment to the approval queue.

Tasks#

Tasks are units of work assigned to agents. A task has a description, an assigned agent, a status, and a cost. Tasks can be created by the AI cofounder (via delegation), by playbooks, or manually through the API.

pending → in_progress → completed
                     ↘ blocked (dependency)
                     ↘ escalated (needs approval)

Playbooks#

Playbooks are typed workflow pipelines defined in YAML. They specify what agents do, what tools they use, and how their output is evaluated. Playbooks are the core primitive for repeatable business operations.

A playbook consists of:

• A name and version
• A trigger (scheduled, manual, webhook)
• Typed inputs and outputs
• A sequence of steps, each specifying an agent, a tool, optional input data, and an optional quality rubric

playbook: content-pipeline
version: 2
trigger: scheduled
schedule: "0 9 * * MON"
inputs:
  topic: { type: string, required: true }
steps:
  - name: research
    agent: strategist
    tool: web-research
    with: { query: ${inputs.topic} }
    rubric: { relevance: 0.8 }
  - name: draft
    agent: marketer
    tool: content-write
    input: ${steps.research.output}
    rubric: { quality: 0.8 }
  - name: review
    agent: strategist
    approval: required

Governance#

Governance is the control layer that makes agents safe and predictable. It consists of four mechanisms:

• Approval queue: Agents propose recommendations. Humans review and approve before execution. You can set auto-approve thresholds for low-cost, low-risk actions.
• Spend caps: Hard limits on how much each agent and each company can spend. When a cap is hit, the agent pauses immediately. No surprise charges.
• Kill switches: Instant shutdown of any agent, playbook, or company. State is preserved so you can resume later. Mid-run side effects are rolled back where possible.
• Execution policy: Rules about what tools agents can use, how many agents can run concurrently, and maximum task duration.

Heartbeats#

Heartbeats are cron-based schedules that control when agents wake up. An agent with a heartbeat of */15 * * * * wakes every 15 minutes, checks for assigned tasks, executes any pending work, and goes back to sleep.

Heartbeats are the primary mechanism for cost control. Agents that wake less frequently cost less. You can configure different heartbeats per agent based on urgency: support agents might wake every 15 minutes, while a strategist wakes once per day.

Adapters#

Adapters connect LLMs to the Capx runtime. Capx is model-agnostic: you can use Claude, GPT, or any HTTP endpoint as an agent backend. Different agents in the same company can use different adapters.

# Anthropic Claude
adapter: claude
model: claude-sonnet-4-6

For details on configuring each adapter type, see the Agent Adapters guide.

Next steps#