Skip to content

Agents

An agent is any AI-powered system that produces outputs for end users. Coalex treats agents as first-class entities with their own identity, health score, and configuration.

Declaring Agents

Use declare_agent() to pre-register your agent before traces arrive:

agent = coalex.declare_agent(
    agent_id="claims-bot",
    display_name="Claims Processing Bot",
    metadata={"team": "insurance", "version": "2.1.0"},
)

const agent = await declareAgent({
    agentId: "claims-bot",
    displayName: "Claims Processing Bot",
    metadata: { team: "insurance", version: "2.1.0" },
});

Declaring an agent is idempotent — calling it multiple times with the same agent_id updates the existing agent rather than creating a duplicate.

Agent Properties

Property Description
Agent ID Unique identifier (e.g., claims-bot). Used in coalex_context() and evaluate().
Display Name Human-readable name shown in the dashboard.
Lifecycle active, deprecated, or archived. Controls whether new traces are accepted.
Health Score Rolling reliability score (0.0 – 1.0) computed from evaluation outcomes.
Metadata Arbitrary key-value pairs for categorization (team, environment, version).

Agent Lifecycle

stateDiagram-v2
    [*] --> active : declare_agent()
    active --> deprecated : Dashboard action
    deprecated --> archived : Dashboard action
    archived --> active : Dashboard action
  • Active — Accepting traces and evaluations. Default state.
  • Deprecated — Still accepting traces, but flagged for replacement in the dashboard.
  • Archived — No longer accepting traces. Historical data is preserved.

Health Score

The health score is a rolling measure of agent reliability:

  • 1.0 — All recent outputs auto-approved or approved by reviewers
  • 0.5 — Mixed results — some corrections and rejections
  • 0.0 — All recent outputs rejected or corrected

The health score influences evaluation risk thresholds. A high-health agent gets more auto-approvals; a low-health agent gets more escalations.

Best Practices

  1. Declare agents at startup — Call declare_agent() once during application initialization, not per-request.
  2. Use meaningful agent IDs — Choose IDs that reflect the agent's function (e.g., claims-bot, not agent-1).
  3. Include metadata — Tag agents with team, environment, and version for dashboard filtering.
  4. Monitor health scores — Set up alerts when an agent's health score drops below a threshold.