Private betaThe Capx developer platform is available to private beta participants. Join the waitlist for access.

Guides

Configuring Agents

Agents are the workforce of your company. Each agent has a role, an adapter that connects it to a language model, a budget, a heartbeat schedule, and persistent memory. This guide covers how to configure every aspect of an agent in your company.yaml file.

Agent overview

When you create a company on Capx Casa, your AI cofounder assembles an agent roster: a set of specialized agents that together can execute your company's playbooks. Each agent is defined in the agents section of your company.yaml file.

Agents are not general-purpose. Each one has a role that shapes its system prompt, its available tools, and its default behavior. You can use built-in roles or define custom ones. The roster is yours to configure: add agents, remove them, change their models, or adjust their budgets at any time.

RolesFive built-in roles, plus fully custom roles with your own prompt and tools.AdaptersConnect each agent to Claude, OpenAI, or any HTTP endpoint.BudgetsHard credit caps per day, per month, and per task.HeartbeatsCron-scheduled check-ins where agents review and act on pending work.MemoryPersistent knowledge that survives across cycles and playbook runs.LifecycleStates from spawn to killed, and the CLI commands to manage them.

Agent roles

Capx ships five built-in roles. Each role comes with a tuned system prompt, a curated toolset, and sensible defaults for model selection and budget. You can override any of these defaults in your company.yaml.

Role	Default model	Purpose	Typical tools
strategist	claude-sonnet-4	High-level planning, prioritization, delegation	create_task, run_playbook, send_message, evaluate
engineer	claude-sonnet-4	Code generation, infrastructure, deployments	write_code, run_command, deploy, create_pr
marketer	claude-sonnet-4	Content creation, campaigns, audience research	generate_copy, search_web, send_email, schedule_post
support	claude-haiku-4	Customer communication, ticket handling, FAQ	send_email, search_docs, create_ticket, resolve_ticket
designer	claude-sonnet-4	Visual assets, UI mockups, brand guidelines	generate_image, create_mockup, review_design
custom	(must specify)	Any role you define. Requires a system_prompt.	(must specify)

Tip

The strategist role is what your AI cofounder uses by default. It has the broadest tool access and is the only role that can invoke other playbooks autonomously.

Defining custom roles

If the built-in roles do not cover your needs, define a custom agent with an explicit system_prompt and tools list. Custom roles have no inherited defaults: you control everything.

Custom role definition

yaml

agents:
  analyst:
    role: custom
    system_prompt: |
      You are a data analyst for this company. You analyze metrics,
      generate reports, and surface actionable insights. You are precise
      and always cite your data sources.
    adapter:
      provider: claude
      model: claude-sonnet-4
    tools:
      - query_database
      - generate_chart
      - send_message
      - create_task
    budget:
      daily: 500
      monthly: 8000

Adapter configuration

The adapter connects an agent to a language model. Capx supports three adapter types out of the box: claude, openai, and http. Every agent must have exactly one adapter.

agents:
  strategist:
    role: strategist
    adapter:
      provider: claude
      model: claude-sonnet-4     # or claude-opus-4, claude-haiku-4
      max_tokens: 4096
      temperature: 0.7

The HTTP adapter lets you connect any model or inference endpoint that accepts a standard chat-completion-style request. The request and response format follows the OpenAI-compatible convention by default, but you can override the body template if your endpoint uses a different schema.

Budget settings

Every agent has a credit budget that limits how much it can spend. Credits are deducted for LLM inference, tool execution, and storage. When an agent exhausts its budget, it pauses and notifies the founder.

Budget fields

dailyinteger

Maximum credits the agent can spend per calendar day (UTC). Default: 1000.

monthlyinteger

Maximum credits the agent can spend per calendar month. Default: 20000.

per_taskinteger

Maximum credits for a single task execution. Default: 200.

alert_thresholdfloat

Fraction of budget at which the founder is alerted. Default: 0.8.

Budget configuration

yaml

agents:
  marketer:
    role: marketer
    adapter:
      provider: claude
      model: claude-sonnet-4
    budget:
      daily: 800
      monthly: 15000
      per_task: 150
      alert_threshold: 0.75

Warning

Budget limits are hard caps. An agent cannot exceed them even if a playbook step requires it. If a step would exceed the remaining budget, the step is paused and the founder is notified via the approval queue.

Heartbeat scheduling

The heartbeat is a periodic check-in where the agent reviews its pending tasks, evaluates its priorities, and decides whether to act. Think of it as the agent waking up, looking at its to-do list, and working through it. The heartbeat schedule is defined with standard cron syntax.

Heartbeat fields

cronstring

The check-in schedule, in standard cron syntax. Aliases like @hourly and @daily are supported.

max_actionsinteger

Maximum number of pending items the agent evaluates per heartbeat cycle. Items can be tasks, queued playbook steps, or internal events.

priority_sortstring

How pending items are ordered: urgency (default), created_at, or cost (cheapest first).

Cron expression	Meaning
/15 * * *	Every 15 minutes
0 * * * *	Every hour on the hour
0 9 * * 1-5	Weekdays at 09:00 UTC
0 9,17 * * *	Twice daily at 09:00 and 17:00 UTC
@hourly	Alias for 0 * * * *
@daily	Alias for 0 0 * * *

Heartbeat configuration

yaml

agents:
  support:
    role: support
    adapter:
      provider: claude
      model: claude-haiku-4
    heartbeat:
      cron: "*/30 * * * *"      # Every 30 minutes
      max_actions: 5             # Max actions per heartbeat cycle
      priority_sort: urgency     # Sort pending tasks by urgency

Note

Heartbeats cost credits. A more frequent heartbeat means higher baseline costs even when the agent has nothing to do. Start with hourly heartbeats and increase frequency only for agents that need to react quickly (like support).

Persistent memory

Each agent has persistent memory that survives across heartbeat cycles and playbook runs. Memory lets agents accumulate knowledge, such as customer preferences, past decisions, and domain expertise, rather than starting from scratch every time.

Memory fields

enabledboolean

Whether the agent retains memory across sessions. Default: true.

max_entriesinteger

Maximum number of memory entries stored. Default: 1000.

ttlstring

How long a memory entry persists before automatic expiry. Default: 90d.

strategystring

Retrieval strategy: relevance (semantic), recency, or hybrid. Default: relevance.

Memory configuration

yaml

agents:
  strategist:
    role: strategist
    adapter:
      provider: claude
      model: claude-sonnet-4
    memory:
      enabled: true
      max_entries: 2000
      ttl: 180d
      strategy: hybrid

When an agent starts a task, the runtime retrieves the most relevant memory entries and includes them in the agent's context window. The hybrid strategy combines semantic similarity with recency, weighting recent memories slightly higher.

Agent lifecycle

Every agent passes through a well-defined set of states. Understanding the lifecycle helps you debug issues and manage your roster effectively.

State	Description	Transitions to
spawn	Agent is being initialized. Adapter is validated, memory is loaded, tools are registered.	active
active	Agent is running. It responds to heartbeats and executes playbook steps.	paused, killed
paused	Agent is suspended. Heartbeats stop. Tasks queue but are not executed. Budget or manual action.	active, killed
killed	Agent is permanently stopped. Memory is preserved but the agent takes no further actions.	(terminal)

Managing agent lifecycle via CLI

bash

# Check agent status
capx agent status --company my-company

# Pause a specific agent
capx agent pause marketer --company my-company

# Resume a paused agent
capx agent resume marketer --company my-company

# Kill an agent permanently
capx agent kill designer --company my-company --confirm

# Spawn a new agent
capx agent spawn --company my-company --config agents/analyst.yaml

Warning

Killing an agent is irreversible. The agent's memory is preserved and can be exported, but the agent itself cannot be restarted. If you want to temporarily stop an agent, use pause instead.

Full company.yaml example

The following shows a complete agent roster for a content-focused company with four agents. Each agent has a distinct role, model, budget, heartbeat schedule, and memory configuration.

company.yaml (agents section)

yaml

company:
  name: my-content-company
  plan: starter

agents:
  cofounder:
    role: strategist
    adapter:
      provider: claude
      model: claude-sonnet-4
    budget:
      daily: 1500
      monthly: 30000
      per_task: 300
      alert_threshold: 0.8
    heartbeat:
      cron: "0 */2 * * *"       # Every 2 hours
      max_actions: 10
      priority_sort: urgency
    memory:
      enabled: true
      max_entries: 3000
      ttl: 365d
      strategy: hybrid

  writer:
    role: marketer
    adapter:
      provider: claude
      model: claude-sonnet-4
    budget:
      daily: 800
      monthly: 15000
      per_task: 200
    heartbeat:
      cron: "0 9,13,17 * * 1-5"  # 3x/day on weekdays
      max_actions: 5
    memory:
      enabled: true
      max_entries: 1000
      ttl: 90d
      strategy: relevance

  developer:
    role: engineer
    adapter:
      provider: claude
      model: claude-sonnet-4
    budget:
      daily: 1000
      monthly: 20000
      per_task: 250
    heartbeat:
      cron: "*/30 * * * *"       # Every 30 minutes
      max_actions: 8
    memory:
      enabled: true
      max_entries: 2000
      ttl: 180d
      strategy: hybrid

  helper:
    role: support
    adapter:
      provider: claude
      model: claude-haiku-4
    budget:
      daily: 400
      monthly: 8000
      per_task: 50
    heartbeat:
      cron: "*/15 * * * *"       # Every 15 minutes
      max_actions: 10
      priority_sort: urgency
    memory:
      enabled: true
      max_entries: 500
      ttl: 60d
      strategy: recency

Best practices

Start with fewer agents and add more as your company's workload grows. A company with two agents (strategist + one specialist) can handle a surprising amount of work. Each additional agent adds heartbeat cost, so only add agents when you have distinct workstreams that justify the overhead.
Match model size to the task. Use claude-haiku-4 or gpt-4.1-mini for high-volume, low-complexity work like support tickets and data classification. Reserve claude-sonnet-4 or claude-opus-4 for strategic decisions and complex content generation. This single optimization can cut your monthly costs by 40-60%.

Tip

You can change an agent's model at any time without restarting it. The new model takes effect on the next heartbeat cycle. This makes it easy to experiment: try a cheaper model, check the rubric pass rate in the activity feed, and switch back if quality drops.

Next steps

Agent AdaptersConnect Claude, GPT, HTTP endpoints, or custom models.Cost ControlBudgets, alerts, and per-agent spend tracking.Governance & ApprovalsApproval queues, spend caps, and kill switches.Agents APIManage agents, budgets, and schedules programmatically.

PreviousWriting Playbooks NextAgent Adapters