> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/design/verified-actions.md).

# Verified Actions Over the World Model

Why Concurrence treats a record read, a write, and a confirmation as separate checked steps, what each establishes, and how to verify an action yourself.

## The Problem

In a healthcare conversation, three easy assumptions are wrong. A phone number that matches a record doesn't prove who is speaking. A world-model observation doesn't change the scheduling system. An agent saying "you're booked" doesn't mean the booking happened. Each assumption, left unchecked, leads to a disclosure or a confirmation the organization can't stand behind.

## Our Design

Concurrence splits an action into steps that each produce their own evidence.

1. **Verify before reading.** A caller matched by phone number or a supplied `entity_id` starts unverified. Built-in record reads return `verification_required` until the caller's full name and date of birth match exactly one record through `world_confirm_patient_identity`. Repeated failures lock verification for the conversation. After verification, built-in reads return only the caller's own record or a household member's that names them as guardian or under a power of attorney.
2. **Scope every write.** Supported agent write tools receive a server-constructed write scope that limits the workspace and entity they can target, whatever identifier the model supplies.
3. **Declare what a write does.** An integration endpoint declares its writes, such as `booking`, `cancellation`, `reschedule`, or `message`. Only a declared write that succeeded backs a claim that the action is done.
4. **Gate a write on a person where needed.** In a text conversation, an integration with an approval policy, or an `approval_required` skill, parks the call until an authorized reviewer approves or rejects it. Approval is a separate record from the external result.
5. **Keep an unknown outcome unknown.** A write with no answer that settles it, such as a timeout, reports `"outcome": "unknown"`, and the platform doesn't send it again in that conversation.
6. **Confirm at the destination.** The endpoint's own result, or a read-back from the target system, is the evidence of what changed there.

The world model holds source-linked observations and derives read views from them. It does not deliver observations to external systems: an external change happens only through a tool the agent calls.

## What It Guarantees

* Built-in record reads on a caller-facing session return no record before verification and nothing outside the caller's own or household records after it.
* A write that got no settling answer isn't resent in the same conversation.
* In a text conversation, an approval-gated call doesn't run before an authorized decision.

## What It Doesn't Cover

* **Approval isn't completion.** An approved write can still fail or have an unknown outcome at the destination.
* **Integration reads aren't gated.** Patient reads through your own integration endpoints are not code-gated by caller verification. The agent is instructed not to share another person's details from any tool, which is model guidance.
* **Approval gates are text only.** Voice calls, simulations, voice notes, companion skills, and trigger actions don't offer approval-gated tools.
* **Projections lag.** A world-model write that was accepted may not be queryable yet.
* **No universal idempotency.** Use the operation's documented idempotency key or the destination's own protection where you need it.

## Verify It Yourself

1. In a test conversation, ask for an appointment before verifying, and confirm the tool call returned `verification_required`. Verify with the synthetic caller's name and date of birth, and confirm the same read returns the record.
2. Ask for another person's record after verifying, and confirm the read returns `not_caller_record`.
3. Run the integration endpoint's test operation against a synthetic appointment, read `outcome` and `wrote`, and read the target record back independently.
4. Request the same change in a conversation, then compare the tool call's result, the agent's statement, and the target record.
5. Follow [Verify an Integration Action](https://docs.concurrence.com/developer-guide/guides/verify-an-integration-action) for the full procedure, including a failure and an unresolved write.

See [Caller Verification](https://docs.concurrence.com/developer-guide/platform-api/conversations/voice-agent#caller-verification), [Endpoint Write Declarations](https://docs.concurrence.com/developer-guide/platform-api/integrations#endpoint-write-declarations), [Approval-Gated Integration Writes](https://docs.concurrence.com/developer-guide/platform-api/integrations/approval-gated-integration-writes), and [Runtime Safety](https://docs.concurrence.com/operations-and-safety/runtime-safety.md#write-safety).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/design/verified-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
