> ## Documentation Index > Fetch the complete documentation index at: https://docs.antigen.sh/llms.txt > Use this file to discover all available pages before exploring further. # Guides > Plan authorized assessments, preserve Run evidence, and turn findings into next actions. Read this after choosing the SDK, CLI, HTTP API, or Platform. Every path creates the same durable Run: one assessment record holding its approved scope, progress, findings, and lifecycle. This page covers the decisions each path leaves to you. ## Choose an integration path Pick the path that matches where your team already owns credentials, persistence, and review. | Path | Best for | What your team still owns | | --------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------- | | [TypeScript SDK](/sdk/typescript) | Typed application integrations. | Key handling, Run-ID storage, event checkpoints, finding review. | | [CLI](/cli) | Interactive members, and scripted CI through `--json`. | Session or key, Run-ID capture, evidence, lifecycle decisions. | | [HTTP API](/http-api) | Direct service integrations. | Request construction, timeouts, persistence, event handling, recovery. | | Platform | Teams using the visual workflow. | Organization choice, evidence review, remediation follow-up. | These are parallel paths, not shortcuts to one another. Use the SDK or HTTP API for application-owned records and unattended work, and the CLI when a member is operating the assessment directly. Whichever you choose, the approved target, the durable Run ID, and the review record stay the same. ## Plan an authorized assessment Start from organization permission and approved targets. Define the business purpose, systems in scope, model, and Guardrails before creating a Run, and record that intent with the assessment so a reviewer can later distinguish authorized work from a similar-looking target. Create one Run for one coherent objective. A Run can cover several approved targets, but combining unrelated objectives makes evidence, assignment, and remediation harder to review. Broader scope reduces coordination overhead; narrower scope makes each finding's next action clearer. | Input | Decision to record | | --------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Organization | Which organization authorizes the work and reviews its result. | | Approved target | The exact value returned for that organization. | | Model | The model selected for the assessment. | | Guardrails | Scope instruction passed to the model. Guardrails shape how the agent works; the approved target list is the enforced boundary. | | Review context | How events and findings reach a named owner and a next action. | If any of these changes materially, record the new decision before creating a new Run. Do not repurpose an in-progress assessment by sending broad guidance, and do not reuse a target from a different organization context. Decide where these will persist before you create anything: | Record | Why it matters | | ----------------------------------- | ---------------------------------------------------------------------------- | | Run ID | Reconnects reads, events, findings, and lifecycle actions to one assessment. | | Last event sequence | Resumes observation without treating earlier evidence as new. | | Assessment scope and review context | Gives findings an accountable review context. | | Finding remediation decision | Turns evidence into an assigned next action. | The SDK and HTTP examples write small files to make this boundary visible. Replace them with the persistence your application already uses, and never keep a Run ID only in process memory. ## Create, then confirm the record Save the Run ID before waiting for results. A create response can be interrupted after the service accepted it but before your caller records the answer, which leaves the caller unsure while the Run exists and runs normally. If your application already has an ID, read that Run instead of submitting another assessment. Then read the Run back to confirm its status and target list. The ID is opaque and grants nothing on its own; every request is still authorized in the caller's organization context. ## Observe progress without losing evidence Events are ordered observations of a durable Run. Process an event, store its `sequence`, then move the checkpoint: 1. Read the event and associate it with the saved Run ID. 2. Perform your evidence-handling step. 3. Persist that event's sequence only after the step succeeds. 4. On reconnect, request events strictly after the saved sequence. Saving the checkpoint first can silently skip unprocessed work. Never saving makes the same evidence look new after every interruption. This ordering also lets a later process tell unhandled evidence apart from evidence already reviewed. | Question | Read | | ---------------------------------------------------------- | --------- | | Is the assessment creating, running, stopped, or terminal? | The Run. | | What arrived after my last checkpoint? | Events. | | What durable remediation work should be reviewed? | Findings. | ## Review findings and direct the next action Findings carry severity, title, description, remediation, and available evidence. Review them in the assessment's authorized context: confirm the affected target, preserve supporting evidence, prioritize remediation, and record an assigned next action. Findings are evidence for a human risk decision, not the decision itself. A completed Run may contain no findings; record that outcome with its scope and completion status rather than treating absence as an integration failure. Keep the same review record for every finding: | Record | Why it belongs with the finding | | --------------------------------- | ------------------------------------------------------- | | Run ID and approved target | Preserves the assessment context. | | Finding identity and severity | Lets reviewers recognize the same durable result later. | | Available evidence | Supports an authorized technical review. | | Remediation | Gives the review its documented starting point. | | Assigned next action and decision | Makes follow-up accountable. | When an assessment needs direction, send guidance that stays inside its approved scope, and prefer a specific reviewable request over a broad change of purpose. If necessary work falls outside the approved target or Guardrails, stop and obtain authorization for a separate assessment. ## Pause, resume, and cancel deliberately | Intent | Operation | Result | | -------------------------------------- | --------- | --------------------------------------- | | Need a review before continuing | Stop | Resumable `stopped` state. | | Continue an approved paused assessment | Resume | Returns the Run to active work. | | End the assessment intentionally | Cancel | Terminal `cancelled` state. | | Assessment finishes on its own | No action | Terminal `completed` or `failed` state. | Each lifecycle action expresses a decision about the assessment. None of them is a way to repair a local timeout. Resuming does not re-evaluate target approval, so confirm the approved scope still applies first. If an action returns `INVALID_RUN_STATE`, another transition already occurred: read the Run and choose an action valid for the observed status rather than sending a second transition. ## Recover from an interruption One rule covers every failure on this page: **a local failure changes what your caller knows, not what the Run is doing.** A request deadline, an AbortSignal, a closed terminal, or a dropped event connection tells you nothing about the durable record. Read the saved Run before deciding anything. | Situation | Preserve | Next action | | ------------------------------- | --------------------------------------- | --------------------------------------------------------- | | Create response is ambiguous | Assessment context and any saved Run ID | Read the known Run before considering another create. | | Caller received a Run ID | The ID itself | Save it before waiting, streaming, or handing off. | | Create was rejected | Service code and request ID | Correct the credential, target, or request input. | | Target was rejected | The rejected target | Re-read the approved list and confirm organization scope. | | Event observation ended | Run ID and last processed sequence | Read status, then reconnect after that sequence. | | A local wait deadline expired | Run ID and event checkpoint | Reconnect later. Do not cancel unless that is the intent. | | A lifecycle action was rejected | Run ID, status, and request ID | Read the Run and choose an action valid for its status. | Keep the request ID whenever a service error provides one. It lets a support conversation identify the failing request without exposing credentials. ## Hand off an assessment When another operator or service takes over, provide the Run ID, the last processed event sequence, the approved scope, the latest observed status, and the current remediation decision. Do not hand off credentials. The receiving operator must use their own authorized session or application credential to read the durable record, which is also what keeps the audit trail meaningful. ## Related pages * [Examples](/examples) for complete application-owned programs. * [Concepts](/concepts) for Run lifecycle and finding terminology. * [Reliability and security](/reliability-security) for credential and retry expectations. * [Resources and troubleshooting](/resources) for concise recovery steps.