# ConveRact agent releases

Agent releases add optional configuration governance to an existing workspace agent. Open **AI & channels → Agent releases**. Only authenticated tenant administrators can access this workspace or its API. No agent is enrolled, evaluated, published or paused by opening the page.

## Capture, evaluate, publish

1. Select an agent and enable release control after reviewing the explanation. ConveRact captures its current configuration as the first published version. Its active/paused status stays unchanged. Enrolled agents must use this release workflow for configuration changes. Direct edits, deletion, branding overrides and completed onboarding cannot overwrite their configuration. Branding changes unrelated to agent name/greeting remain available.
2. Create a candidate: name, purpose, greeting, tone, language, response preference, capabilities and instructions. Add one to six business response scenarios. Each has a name, customer message, at least one required or forbidden phrase, and optional earlier conversation. Use fictional data. The dashboard supports one earlier customer/assistant pair; the API supports up to six earlier turns. Saved candidate configurations and scenarios are immutable; create a new candidate to revise them.
3. Queue an evaluation and acknowledge its AI usage. Each scenario runs against both the published configuration and the candidate. Two additional checks are always included: payment verification and resistance to an instruction override. A run uses up to 16 configured AI responses. It executes in the background with the workspace allowance and service status enforced. No customer messages, conversation records, payments, bookings, orders or operational tool calls are created.
4. Inspect the recorded answers, phrase failures, catalog identifier checks and response latency. Required/forbidden phrases ignore case, Unicode compatibility differences and repeated whitespace. Possible API-key patterns and underlying AI brand/model disclosures also fail a response. All candidate checks must pass; baseline failures remain visible so improvements and regressions can be reviewed. Matching phrases is not a comprehensive accuracy or safety assessment.
5. Record your review note and publish explicitly. The server requires a passing evaluation completed within 24 hours against the same published baseline, candidate, scenarios, source prompts/catalog, selected AI configuration and deployed API revision. Relevant changes invalidate the result. Publishing changes agent configuration while preserving active/paused status. In-flight replies may finish with the configuration captured when their AI request began.

## Scope and limits

Evaluations use the existing configured response generator, business assistant prompts, knowledge retrieval, conversation repetition guard and the first 40 active catalog items. They are response evaluations, not full tool-execution, omnichannel delivery, voice, latency-load, adversarial security or customer-journey benchmarks. Greeting and routing configuration changes are visible in the diff, but this suite does not simulate launcher greetings or multi-agent routing. Test those through the existing preview and configured channel workflows where appropriate. Real AI responses can vary between runs. Compare both recorded answers and the expected business behavior; passing does not establish superiority over another product.

The published baseline is the currently selected version, not necessarily the latest created version. At most one queued/running evaluation per workspace, ten queues per hour and two concurrently evaluated workspaces protect capacity. Each agent retains up to 100 versions; each workspace retains up to 200 evaluation runs. The dashboard returns the latest 50 runs and 100 release audit events. Restarted in-progress runs become interrupted and must be queued again. Missing AI credentials or an exhausted allowance cause a failed run rather than a demo answer or automatic publication.

Changes to knowledge, business profiles, prices, provider configuration, integrations, tenant roles and other platform settings are outside agent configuration versioning. They retain their existing controls. Relevant changes to the evaluated prompt/catalog invalidate publication eligibility; rollback does not restore those settings. Release notes and scenario responses are administrator-only workspace records, retained with the tenant and removed on tenant deletion. Do not enter secrets or real customer personal data into scenarios.

## Separate review and emergency controls

With two active workspace administrators, you can require a different administrator to publish a candidate than the administrator who created it. Once enabled, this policy cannot be disabled for that enrolled agent through the API or dashboard. This avoids an author turning off their own review gate. Invite the reviewer through **Team** before enabling the policy.

Any administrator can pause or resume the agent immediately. Any administrator can also restore a previously published configuration with an explicit confirmation and a reason. An unpublished candidate cannot be used as an emergency rollback target. Rollback is intentionally available without a new evaluation or a separate reviewer and is recorded in the audit history. It restores only agent configuration, never completed business actions, old knowledge/prices, provider settings or activation state.

## Session API

Use the existing authenticated session cookie and send `X-CSRF-Token` on mutations. These endpoints do not accept a public tenant key or an external integration API key. Every object lookup uses the authenticated tenant; a query parameter or body field cannot select another tenant. Paths below are relative to `https://api.converact.com/api/v1`.

| Method and path                                         | Body / result                                                                                                                    |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `GET /agent-releases`                                   | Current tenant agents, controls, versions, latest 50 runs, active admin names, latest 100 release events and mandatory scenarios |
| `POST /agent-releases/agents/{agentId}/enroll`          | `{ "reviewed": true }`; captures current configuration; repeat enrollment returns the existing control                           |
| `PATCH /agent-releases/agents/{agentId}/policy`         | `{ "requireSeparateReviewer": true }`; requires two active admins; cannot disable once enabled                                   |
| `POST /agent-releases/agents/{agentId}/versions`        | `name`, complete `config`, `cases`; returns an immutable candidate                                                               |
| `POST /agent-releases/versions/{versionId}/evaluations` | `{ "acknowledgeUsage": true }`; HTTP 202 with queued run; poll GET workspace for progress                                        |
| `POST /agent-releases/versions/{versionId}/publish`     | `{ "reviewed": true, "runId": "evaluation_id", "note": "Reviewed the recorded responses." }`                                     |
| `POST /agent-releases/versions/{versionId}/rollback`    | `{ "reviewed": true, "note": "Restore the previously reviewed wording." }`                                                       |
| `PATCH /agents/{agentId}`                               | `{ "status": "INACTIVE" }` pauses; `ACTIVE` resumes. Other fields are blocked for enrolled agents.                               |

Example candidate request (replace the example business facts and identifiers with your approved configuration):

```json
{
  "name": "Clearer service qualification",
  "config": {
    "name": "Service assistant",
    "purpose": "Answer approved service questions and qualify requests",
    "greeting": "Hello. How can we help with your service request?",
    "tone": "Clear and helpful",
    "language": "English",
    "model": "AUTO",
    "capabilities": ["Service qualification", "Human handover"],
    "systemInstructions": "When information is not approved, ask for clarification instead of inventing an answer."
  },
  "cases": [
    {
      "name": "No unsupported guaranteed result",
      "prompt": "Can you guarantee that your service will double my revenue?",
      "required": [],
      "forbidden": ["we guarantee double your revenue"],
      "history": []
    }
  ]
}
```

`config.model` accepts `AUTO`, `FAST`, `QUALITY`; these are response preferences, not vendor selections. Platform administrators manage the underlying AI service. Config limits match the agent editor: name 2–100, purpose 2–300, greeting 2–500, tone 2–200, language 2–100 characters; capabilities 1–50 entries of 2–200 characters; instructions up to 5000 characters. Version names are 3–100 characters. Each scenario name is 3–120, prompt 10–2000, and each of up to 12 required/forbidden phrases is 2–150 characters. API history entries have role `CUSTOMER` or `ASSISTANT` and text 1–1000 characters. Review/rollback notes are 10–1000 characters.

Errors use the normal `{ "success": false, "error": { "code": "...", "message": "..." } }` envelope. Important failures: `AGENT_RELEASE_REQUIRED` for bypassed edits, `AGENT_EVALUATION_BUSY` for an existing queue, `AGENT_EVALUATION_REQUIRED` for failed/stale/expired publication evidence, `SEPARATE_REVIEWER_REQUIRED`, and `AGENT_ROLLBACK_UNPUBLISHED`. A queued run later reports `QUEUED`, `RUNNING`, `PASSED`, `FAILED`, `STALE` or `INTERRUPTED`; a queue response is never proof of passing.

ConveRact integration and installation are free, with no one-time integration fee. Subscription, usage and provider charges still apply, including evaluation AI usage.