Documentation

Tenant OwnerReviewerOperator

Product knowledge base, playbooks, and embedded guidance for every persona.

Create a Custom Agent

Custom agents let your workspace extend CoffeeBreak with specialized capabilities: domain-specific rules, internal tooling, unique workflows, or organization-specific expertise.

This guide explains what CoffeeBreak expects from a custom agent and how to make it “routeable” and safe within a workspace.

What a custom agent is

A custom agent is a component that:

  • Accepts a task request plus contextual inputs (code, docs, hints, prior feedback)
  • Produces a proposed result (and optionally metadata)
  • Reports a confidence score
  • Behaves safely under workspace rules (including human review requirements)

Agents can be internal-only (private to your org) or distributed (marketplace-style), but the contract is the same.

Design goals

A good custom agent should be:

  • Predictable: stable inputs/outputs with minimal surprises
  • Composable: works well with orchestrators, retries, and refinements
  • Idempotent: safe to retry without duplicating side effects
  • Transparent: provides metadata and warnings when assumptions are made
  • Policy-aware: respects workspace rules and HITL constraints

Inputs your agent should handle

At minimum, assume you may receive:

  • A task description and task type
  • Context payloads (source code, documents, structured data)
  • Capability hints (skills/domains expected for the task)
  • Prior outputs and reviewer feedback (for refinement loops)
  • Workspace settings that influence behavior (confidence thresholds, reviewer rules)

Your agent should treat missing or partial context as normal and degrade gracefully.

Outputs your agent must produce

Your agent must return:

  • Result: the proposed output for the task (code changes, docs, analysis, etc.)
  • Confidence score: a numeric indicator of how reliable the result is

Optionally return:

  • Warnings: risks, uncertain assumptions, or incomplete context
  • Findings: structured notes that help reviewers
  • Suggested next steps: follow-on tasks or validation actions

Confidence scoring expectations

Confidence should represent: “How likely is this output to be correct and acceptable?”

Guidelines:

  • If the task requires guessing or missing key context, lower confidence
  • If the output was validated (tests, compilation, deterministic checks), raise confidence
  • If the agent is uncertain about side effects, security, or data correctness, lower confidence

CoffeeBreak can use this score to decide whether to route directly, retry, or pause for review.

Idempotence and side effects

Assume your agent may be retried.

  • Prefer read-only operations unless explicitly allowed.
  • If you must call external systems, guard with:
    • deterministic request IDs
    • “check-first” reads
    • safe replays
  • Avoid “fire-and-forget” actions on retries.

If the agent can’t be idempotent for a specific capability, it should clearly warn and lower confidence.

Making your agent routeable

CoffeeBreak routes tasks based on agent metadata (name, capabilities, supported task types, etc.).

You’ll need to provide metadata that answers:

  • What kinds of tasks does this agent handle?
  • What inputs does it require or prefer?
  • What constraints does it have?
  • Any workspace policies it depends on?

See: Agent Metadata Spec

Testing your agent

At minimum, validate:

  • It can run with minimal context (and returns useful warnings)
  • It produces stable outputs for identical inputs
  • It returns confidence consistently (same conditions → similar confidence)
  • It behaves safely under retries
  • It respects “review required” scenarios (no bypass)

Common pitfalls

  • Returning high confidence with missing context
  • Producing outputs that depend on hidden state without declaring it
  • Performing non-idempotent side effects in the main execution path
  • Not surfacing warnings when assumptions are made