How Recembo works

The model

You build inside a company (an isolated workspace). A company owns one or more agents. Each agent has:

• Knowledge — organised into domains. Each domain holds source-backed facts, a summary, examples, and uploaded documents, published under version control.
• Guards — a policy of what the agent must never do (diagnose, promise an outcome), optional capabilities you can switch on, and escalations that hand off to a person.
• Voice — persona, perspective, warmth, length, and communication behaviours that compile into drafting instructions.
• An API key — minted in the agent’s Connect view; your application authenticates with it.

You configure all of this in this console; your application consumes it through the agent and policy endpoints below.

The agent endpoint

Base URL https://api.recembo.com. Authenticate every request with your agent key in the x-api-key header. The core call is POST /v1/orchestrate: send the user’s question, get back everything you need to draft a governed answer.

curl https://api.recembo.com/v1/orchestrate \
  -H "x-api-key: $RECEMBO_AGENT_KEY" -H "content-type: application/json" \
  -d '{"query": "who qualifies for the program?", "conversation_id": "optional-thread-id"}'

What you get back

Other agent reads: GET /v1/index (list the agent’s domains), GET /v1/domains/{slug}/summary, and POST /v1/search (retrieve cited chunks directly).

How a response is orchestrated

Each call to orchestrate runs this flow, server-side, and stores no query text:

1. Scrub. For healthcare agents the query is screened for personal data and rejected if any is detected — only a one-way hash is ever retained.
2. Match. The question is routed to domains by its glossary terms, registered keywords, and knowledge matches — plus the warm set carried across a conversation — so specialist context is pulled only when relevant.
3. Compose policy. The matched domains’ policies merge with the always-on locked platform guards, and the hand-off + safety contacts resolve live from the agent config.
4. Compile the surface. Persona, guardrails, output instructions, and voice compile into explicit drafting instructions.
5. Flag intent. If the question itself warrants a hand-off, the escalation object is set (see Alerting).
6. Return + audit. You receive knowledge + citations + surface + policy + escalation; a de-identified audit row records the served request for your performance metrics.

You then draft with your own model using the returned surface and knowledge — the answer text never leaves your environment.

The policy endpoint

After your model drafts a reply, check what it does against the agent’s guards. You get a decision (allow / escalate / block), the reasons, and an escalation object. Two ways to run it:

Locally (recommended, no extra call)

Orchestrate already returned the full policy, so the SDK’s action_escalation helper evaluates the reply in your environment — no second round-trip, nothing about the reply leaves your plane.

from recembo_client import action_escalation
escalation = action_escalation(pkg["policy"], actions=["service_request"])

Hosted — POST /v1/policy-check

curl https://api.recembo.com/v1/policy-check \
  -H "x-api-key: $RECEMBO_AGENT_KEY" -H "content-type: application/json" \
  -d '{"domain": "guide-eligibility", "has_citation": true, "actions": ["service_request"]}'

Either way needs the actions your reply took (for example service_request). Your model declares them — use action_schema(policy) to drop a ready-made, enum-constrained field into your existing structured-output generation, so one call returns the reply and its actions. No key list to hand-maintain.

Quality flags (not a hand-off)

If a domain asks every answer to cite a source and your reply cited none, the response carries quality_flags: ["missing_citation"] — but decision stays allow and escalation.triggered is false. The answer still goes out; it’s a signal for monitoring replies your knowledge didn’t specifically cover, not an alert and not a hand-off. Read quality_flags on the /v1/policy-check response, or compute it locally with quality_flags(pkg["policy"], has_citation=…).

Wiring it up

1. Mint an agent key in the agent’s Connect view; store it server-side.
2. On each user turn, call /v1/orchestrate. If escalation.triggered, raise an alert immediately.
3. Draft with your model, using surface as the system prompt and knowledge as grounding. Optionally include action_schema(policy) so the model also returns its actions.
4. Evaluate the draft with action_escalation (local) or /v1/policy-check. Raise or confirm the alert.
5. Optionally POST /v1/signals with de-identified outcomes (thumbs-down, escalation, no-results) to power the performance dashboard.

Alerting

Recembo tells you, in real time and with no personal data, when a conversation needs a human. The same escalation object appears on both endpoints:

{
  "triggered": true,
  "source": "intent",          // "intent" (orchestrate) | "action" (policy-check / local)
  "kind": "handoff",           // "handoff" -> your hand-off contact | "safety" -> dedicated safety contact
  "route": "the care team",    // WHO to notify, resolved live from your agent config
  "reasons": ["denied_action:caregiver_distress"],
  "context": { "domain": "…", "agent_id": "…", "query_hash": "…", "ref": "ticket-42" }
}

• Two signals. Intent fires from the user’s question at orchestrate (needs no classification); action fires from what the agent commits to, at policy-check. Most teams wire both and de-duplicate on context.
• Every agent, configurable. Hand-offs like requested_human apply to all agents, not just healthcare; builders toggle the hand-off ones per agent, while safety escalations are always on.
• Reconcile with a ref. Pass an opaque ref (your conversation / ticket id) on the request; it’s echoed back in context.refso you can tie the alert to the right conversation — no personal data needed.
• Route by kind.

  safety

  to your urgent/clinical channel,

  handoff

  to your normal queue; notify route.
• Build your own alert. Branch on escalation.triggered and forward the payload to Slack, email, or a ticket. It’s de-identified, so it’s safe to log.
• See them in the console. Fired hand-offs show on the agent’s Performance → Recent hand-offs report with their ref for cross-reference.