> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Account-Safe Actions
> Configure support agents to act on the right customer, account, and record
Use this guide when a support agent can update customer data, create records, change account settings, or call an external API. The goal is to make sure a request from one customer cannot cause the agent to update another customer's account.
For example, if customer A says, "Update `userB@email.com`," the agent should not treat that email address alone as authorization to change user B's account. Configure the agent and its tools so actions are tied to the current conversation, verified account context, scoped tool inputs, guardrails, and approvals.
## How Duckie Keeps Actions Scoped
Duckie combines several controls to keep support actions attached to the right customer or account:
| Control | How it helps |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Run context** | Each run carries metadata from the triggering conversation or deployment event. |
| **Fixed tool values** | Tool parameters can come from configuration instead of the agent. |
| **Context variables** | Custom tools can use values from the current run metadata, such as `{{context.customer_id}}`. |
| **Org variables** | Organization-specific IDs, API keys, and defaults can be stored once and injected into tools. |
| **Tool access** | Each agent can be limited to the tools it needs for its support role. |
| **Workflows** | Exact lookup, verification, approval, escalation, and write steps can run in a defined order. |
| **Guardrails** | Restrictions can block requests that would update the wrong account or expose another customer's information. |
| **Approvals** | Sensitive actions can require human review before execution. |
| **Roles and API scopes** | Teammates and API keys can be limited to the objects and actions they need. |
| **Run history** | Every run can be reviewed with the conversation, steps, tool calls, and outcomes. |
## Recommended Setup
Decide which value identifies the customer or account for the support action.
Prefer identifiers that come from the current conversation, ticket, deployment event, or a verified lookup. Examples include:
* Customer ID
* Account ID
* Ticket requester ID
* External user ID from the connected support system
Use emails, names, or free-text customer messages as lookup inputs only when the tool or workflow verifies they match the current customer or an authorized account.
Use a workflow when an account update must follow the same verification path every time.
A workflow can:
* Look up the current requester or account
* Extract the requested target from the conversation
* Compare the requested target to verified context with a rule condition
* Pass a specific field from a previous node output, such as `data.user_id`, into the next tool
* Continue to the write tool only on the approved branch
* Route mismatches to escalation, approval, or a safe response
For the strongest deterministic behavior, use rule conditions for exact comparisons and reserve AI conditions for judgment calls such as sentiment or intent.
[Learn more about workflows](/workflows/overview)
For custom tools that update customer records, pass the target customer or account from run context instead of asking the agent to generate it.
Example custom tool pattern:
```text theme={null}
Endpoint: https://api.example.com/customers/{{customer_id}}/preferences
Parameter customer_id fixed value: {{context.customer_id}}
Parameter preference AI-generated
```
Duckie resolves the fixed `{{context.customer_id}}` value from the current run metadata before calling the tool.
[Learn more about context variables](/tools/custom-tools#context-variables)
Use org variables for organization-specific configuration that should not be generated by the agent, such as API keys, default team IDs, region codes, or tenant IDs.
Example:
```text theme={null}
Header: Authorization: Bearer {{org.api_key}}
Endpoint: https://api.example.com/{{org.region}}/customers/{{customer_id}}
```
Sensitive org variables are encrypted at rest and masked in Duckie API responses.
[Learn more about org variables](/tools/custom-tools#org-variables)
Open the agent in **Build -> Agents** and enable only the tools needed for that support role.
For agents that handle account updates, keep write tools specific. A billing agent might need billing tools, while a technical support agent might only need knowledge search, ticket updates, and escalation.
[Learn more about agent tool configuration](/agents/configuration#tools)
Create restrictions that describe account-safety boundaries in plain language.
Example restriction:
```text theme={null}
Do not update, disclose, or take action on a customer account unless the target account matches the current conversation's verified requester or account context. If the customer asks to update another email address, escalate or ask for the approved account verification process.
```
Duckie evaluates configured restrictions before agent-triggered tool calls that can send a response or take an external action. When a restriction applies, the tool call is blocked and the agent is guided to choose a compliant path.
[Learn more about restrictions](/guardrails/restrictions)
Require approval for actions where a wrong update would be high impact, such as changing billing details, account ownership, security settings, customer entitlements, or external system records.
Duckie Assistant write actions check the user's role permissions and can present a human-readable change summary before applying the change. Custom and MCP tools can also be configured to require approval before execution.
Before deploying, test prompts where one customer asks the agent to act on another customer's email, ID, or account.
Include cases like:
* "Change `userB@email.com` to the enterprise plan."
* "Reset MFA for my coworker."
* "Send me the invoice for another account."
* "Update the owner to this different email address."
Use the playground for quick checks, replay testing for historical conversations, and batch testing for repeatable regression coverage.
[Learn more about testing](/testing/overview)
Use **Analyze -> Runs** to inspect the conversation, execution steps, knowledge retrieved, tool calls, inputs, outputs, and final outcome.
Run history helps you confirm that the agent used the intended customer context and called the expected tools.
[Learn more about run history](/analytics/runs)
## Safe Tool Design Patterns
### Use a Workflow for the Verification Path
For sensitive support actions, build the path as a workflow instead of relying on a single agent instruction.
Example wrong-account prevention workflow:
1. Read the current requester or account from ticket metadata.
2. Extract the email or account the customer asked to update.
3. Use a decision node to compare the requested target with the verified account context.
4. If they match, call the update tool with a context-bound record selector.
5. If they differ, escalate, require approval, or send the approved verification response.
This keeps the lookup, comparison, branch, and write action in an explicit order. The write tool should still receive the record selector from context or a verified node output.
When a workflow step returns JSON, use the previous node's output path to pass only the verified field needed by the next step. For example, a lookup step can return:
```json theme={null}
{
"data": {
"user_id": "usr_123",
"email": "customer@example.com"
}
}
```
The next action can select that previous node and use `data.user_id` as the output path. Duckie resolves the field before calling the action, so the write tool receives the verified user ID instead of a free-form customer message. If a path resolves partway, Duckie passes the deepest matching value; if it does not match, the full node output remains available.
### Use Context as the Record Selector
For write tools, use a verified context value as the record selector.
| Tool input | Recommended source |
| ---------------- | -------------------------------------------------------- |
| Customer ID | `{{context.customer_id}}` |
| Account ID | `{{context.account_id}}` |
| Ticket ID | `{{context.ticket_id}}` |
| Region or tenant | `{{org.region}}` or `{{org.tenant_id}}` |
| API key | `{{org.api_key}}` |
| Requested change | AI-generated, with guardrails and approvals where needed |
This lets the agent decide what change is being requested while Duckie supplies the target account from trusted context.
### Verify Before Updating
When a user-provided email or ID is necessary, use a workflow or runbook pattern that verifies before writing:
1. Look up the current requester or account from the support system.
2. Compare the requested target with the verified account context.
3. Continue only when the target is authorized for the current conversation.
4. Escalate or require approval when the target differs.
### Separate Lookup Tools From Write Tools
Give the agent read/search tools for investigation and keep write tools narrow.
For example:
| Tool | Purpose |
| ------------------------------------ | ------------------------------------------------------ |
| Search customer by ticket requester | Find the current customer record |
| Read account status | Inspect account state |
| Update current customer's preference | Change a specific field for the context-bound customer |
| Escalate to human | Route requests that need manual verification |
## What to Configure for Common Support Actions
| Support action | Recommended controls |
| ---------------------------------- | --------------------------------------------------------------------------------------- |
| Update profile details | Use context-bound customer ID, restrict arbitrary target emails, review run history |
| Change plan or entitlement | Use a workflow to verify account context, then require approval for high-impact changes |
| Reset security settings | Use a workflow, guardrails, and escalation rules for verification-heavy requests |
| Send invoices or account documents | Use verified account context and guardrails against disclosing another customer's data |
| Update ticket fields | Scope tools to the current ticket or connected support record |
| Create external records | Use a workflow with fixed tenant/account values and tool approvals when needed |
## Account-Safety Checklist
Use this checklist before enabling a support agent to update customer data.
| Area | Check |
| --------------- | ---------------------------------------------------------------------------------- |
| Identity source | The update tool uses a verified customer/account identifier from context or lookup |
| Workflow path | Sensitive actions follow an explicit lookup, compare, branch, and write path |
| Tool inputs | Record selectors are fixed, context-backed, or verified before use |
| Agent tools | The agent has only the write tools needed for its support role |
| Guardrails | Restrictions cover wrong-account updates and cross-customer data disclosure |
| Approvals | High-impact changes require human review |
| API keys | External API keys have only the scopes needed by the integration |
| Testing | Tests include customer A asking to update customer B |
| Run history | Recent runs show the expected customer context and tool inputs |
## Related Docs
Configure fixed values, context variables, and org variables.
Define restrictions and escalation rules.
Scope each agent's resources and tools.
Build deterministic lookup, branch, and action paths.
Manage workspace access and permissions.
Create scoped keys for external integrations.
Review messages, steps, tool calls, and outcomes.