# Request documents from your agents

A customer can ask for an NDA during a call, chat or SMS conversation. The agent can collect the required details, request the agreement and check its progress. Email agents, task agents and CRM or helpdesk reactions use the same document tools.

The requesting agent calls a tool. A reusable document agent supplies the template, required information, recipients and automation policy. Documents prepares the agreement in the background and manages review, email invitations and signatures. You configure the tools and policies; you do not need to script a conversation between two agents.

## Before you begin

Your workspace needs the **Documents & e-signature** module. The requesting agent's owner needs document permissions for the intended actions and access to the customer's CRM record. The document agent must allow the requesting channel and, if restricted, that specific source agent.

Customer conversations use their identified CRM contact. Save the customer's name and email before requesting the document. Invitations go by email, including when the request starts in voice or SMS; the tools do not return a signing link for the agent to paste into the conversation.

## Enable the workflow

1. Open **Agents → Agent Types → Document Agents** and choose or create your NDA document agent.
2. Under **Requests from other agents**, choose the permitted channels. Task agents and CRM/helpdesk reactions are the defaults; enable the conversational channels you want. Use **Limit to selected source agents** if only particular agents should use this template. A restriction also excludes reactions or connected assistants without a matching source agent.
3. Define **Information to collect**, then configure **Default Signer Roles** and **Signing field anchors**. Follow [the document-agent setup guide](agent-setup.md#let-another-agent-request-an-nda) for customer details, internal recipients and field placement.
4. Choose the automation policy. Human review is the default. Automatic sending needs an explicit policy that permits it, valid recipients and a prepared document with the required fields. Internal review and recipient order still apply.
5. Enable `document-templates`, `document-create`, `document-status` and `document-find-requests` on the requesting agent. Add `document-send` and `document-remind` only for workflows that need those actions and permit them.
6. Give the requesting agent instructions about when to offer the NDA and which business details to collect. The tools provide the available templates, missing inputs and current progress.

For a **Compute agent**, enable **Allow document requests** on its **Tools** tab and allow Compute requests on the document agent. The requester confirms document actions, and runs started from a customer conversation retain that customer's scope. A connected assistant using **MCP** needs a signed-in connection with the appropriate Documents scopes and user permissions; an API key alone does not supply the execution owner.

## What each tool does

| Tool | Use it to | What to expect |
|---|---|---|
| `document-templates` | Find document agents available to this caller; optionally search by name. | Available templates, required inputs and delivery policy. Use this before creating a request. |
| `document-create` | Request preparation using a `templateId` and collected `variables`. | Missing-input guidance or a durable `requestId`. Keep that ID: preparation is asynchronous. Internal callers may select a permitted `contactId`; conversations use their current customer. |
| `document-status` | Read progress using a `requestId` or `documentId`. | Preparation, review, current version, recipient response and separate invitation/completed-copy delivery states. |
| `document-find-requests` | Find recent requests for the customer, optionally filtered by `templateId`. | Accessible requests to resume, including requests started in another channel. Internal callers may specify a permitted `contactId`. |
| `document-send` | Send a prepared document when its policy allows agent sending. | Requires `documentId` and the current `expectedVersion`. It cannot bypass required human review or incomplete recipients and fields. |
| `document-remind` | Request a reminder for active recipients under the document's agent-send policy. | Requires `documentId` and the current `expectedVersion`. Automated reminders must be enabled, and reminder limits and recipient stages still apply. |

Enabling a tool does not grant access to every document. Channel restrictions, source-agent restrictions, owner permissions and customer scope also apply. Permissions are checked again when queued preparation runs. A customer-facing agent sees that customer's recipient progress without other recipients' email addresses or internal document links.

## Example: an NDA during a customer conversation

1. The customer asks for an NDA. The agent uses `document-find-requests` to check for an existing request before starting another agreement.
2. If a new agreement is needed, the agent uses `document-templates` to find the permitted NDA template and required information, such as a project name. It collects missing information and ensures the customer's name and email are saved in CRM.
3. The agent calls `document-create` with the chosen template and inputs. If the result is `needs_input`, it collects or corrects the listed values. If preparation is queued, it can say, “I've requested preparation of your NDA.”
4. The agent keeps the request ID and uses `document-status` to check progress. The conversation can continue while preparation runs. Human-review policy leaves the agreement for the document owner; permitted automatic sending proceeds only after preparation passes its checks.
5. The agent reports the returned recipient state. An invitation sent to an internal reviewer does not mean the customer's invitation has been sent.
6. If the customer later follows up in another permitted channel, that agent identifies the same CRM contact, finds the existing request and checks its status.

```mermaid
flowchart TD
    A[Customer asks for an NDA] --> B[Find an existing request]
    B -->|Found| C[Check progress]
    B -->|New agreement needed| D[Choose template and collect inputs]
    D --> E[Request background preparation]
    E --> F[Review and sending policy]
    F --> G[Recipient stages and email invitations]
    G --> C
```

Use a stable `requestKey` for the same business transaction. Repeating that key with the same template, customer and inputs reuses the request; changing the inputs under that key is refused. Without a key, matching inputs for the same template and customer reuse the request across channels. A different key deliberately starts another agreement. Checking existing requests first helps avoid duplicates when a customer follows up with different wording.

## Describe progress accurately

| Result | What it means |
|---|---|
| Queued or preparing | Preparation is waiting or running. No invitation is confirmed. |
| Ready with a draft or pending review | Preparation finished, but the owner still needs to review the document. |
| Invitation `not_sent` | The customer has no recorded invitation yet; an earlier recipient stage may still be active. |
| Invitation `provider_accepted` | The email provider accepted the invitation. This is not proof of delivery. |
| Invitation delivered | Delivery is recorded. The recipient may still need to review or sign. |
| Recipient signed | That recipient's signature is recorded. Check the overall document state before calling the whole agreement complete. |

Invitation delivery and completed-copy delivery are separate. A queued reminder is also not proof that its email arrived. Use the latest status rather than promising a preparation time or claiming a signature from an email event.

## Track requests and resolve problems

Open **Agents → Reports & Logs → Documents → Agent requests** to see queued, preparing, failed and prepared requests. Open the resulting document to review its content and recipient activity.

- **The template is missing:** check the document agent's allowed channels and source agents, the requesting agent's tools, and its owner's permissions.
- **The agent needs more information:** collect the fields returned by the tool. For a customer conversation, confirm that the current CRM contact has a saved name and email.
- **The document is waiting for review:** the owner reviews it in Documents. Unresolved signing anchors or incomplete recipients require correction; enabling `document-send` does not override review policy.
- **Preparation failed:** an owner with document edit permission can correct the cause and select **Retry preparation** in **Agent requests**. A customer-facing agent cannot retry failed preparation itself.
- **The version changed:** check status again and review the current document before sending or reminding with its current version.
- **A reminder is refused:** check the document's automation policy, saved reminder settings, limit and active recipient stage.

Continue with [document-agent setup](agent-setup.md), [recipient progress and delivery troubleshooting](tracking.md), or [manual document creation and sending](signing-flow.md).