Custom agents. Your pipeline, our rails.

Overview

A ReAct loop on top of the same primitives you already use.

• Steps as first-class — classify, extract, validate, fraud, qa and any tool you register.
• Per-step model tier — pick budget, balanced or premium; defaults come from the model's recommended_for_steps metadata.
• Tenant guards — cap cost per run, mask PII before tool calls, block external HTTP. Configurable per tenant.
• Audit trail — every run emits a structured trace: prompts, tool inputs, outputs, retries and the final decision.

Concepts

• Pipeline — a versioned, named composition of steps and edges; lives in template_agent_config.
• Step — a typed unit of work with declared inputs, outputs and an optional tool binding.
• Tool — a callable (built-in or your own HTTPS endpoint) the agent can invoke during a step.
• Run — one execution of a pipeline against one document; persisted as an agent_run row.
• Guard — a tenant-level policy enforced before, during and after every step.

Defining a pipeline

{
  "name":    "vendor-invoice-strict",
  "version": "1.0.0",
  "steps": [
    { "id": "detect",   "type": "classify", "tier": "budget" },
    { "id": "parse",    "type": "extract",  "tier": "balanced",
      "params": { "template": "{{detect.label}}" } },
    { "id": "check",    "type": "validate", "params": { "rule_set": "invoice-strict@stable" } },
    { "id": "risk",     "type": "fraud",    "tier": "premium" },
    { "id": "notify",   "type": "tool",
      "tool": "http_post",
      "when": "check.verdict == 'fail' || risk.score >= 70",
      "params": { "url": "https://hooks.example.com/finance" } }
  ]
}

Tools

• Built-in — http_get, http_post, kv_get, kv_set, now, currency_convert.
• Tenant tools — register an HTTPS endpoint with a JSON schema; the agent gets a typed function it can call with retries and timeouts.
• Permissions — every tool declares the data classes it may receive (raw_text, pii, financial); the runtime drops calls that violate the tenant guard.

Running an agent

curl -X POST https://api.cogneris.ai/v1/agents/run \
  -H "Authorization: Bearer $COGNERIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": "vendor-invoice-strict@1.0.0",
    "source":   { "url": "https://files.example.com/2026-04/inv-9912.pdf" },
    "options":  { "max_cost_usd": 0.50, "dry_run": false }
  }'

Response & trace

{
  "data": {
    "run_id":   "run_01J9PZQ2…",
    "status":   "completed",
    "verdict":  "escalated",
    "steps": [
      { "id": "detect", "status": "pass", "latency_ms": 820  },
      { "id": "parse",  "status": "pass", "latency_ms": 2410 },
      { "id": "check",  "status": "fail", "detail": "totals_reconcile" },
      { "id": "risk",   "status": "pass", "detail": "score=42" },
      { "id": "notify", "status": "pass", "detail": "tool=http_post · 204" }
    ],
    "cost_usd": 0.18
  },
  "meta": {
    "pipeline":  "vendor-invoice-strict@1.0.0",
    "audit_url": "https://app.cogneris.ai/audit/run_01J9PZQ2"
  },
  "has_errors": false
}

Tenant guards

Guards are policies the runtime enforces before, during and after every step. They live in tenant_agent_guards and require the tenant.admin role to update.

• Max cost per run — hard ceiling on the dollar spend across model + tool calls; checked against the billing plan's max-cost-cap.
• Allowed data classes — restrict which fields can be passed to tenant tools.
• Egress allowlist — for http_* tools, only listed hostnames are reachable.
• Dry-run only — force every run to dry-run mode while you certify a new pipeline.

Dry-run & retention

• Dry-run — set options.dry_run=true; tools are stubbed, results aren't persisted to downstream systems, and the run is tagged shadow in the audit trail.
• Retention — dry-run rows expire after 30 days by default (configurable per tenant). An hourly sweep clears any past expires_at.

Errors