ramp-onboard-standalone-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Set up a Ramp standalone agent

Guide a Ramp admin through one new machine identity for a clearly scoped set of responsibilities. Make the experience conversational: ask one question at a time, wait for the answer, recommend the narrowest access that fits, and explain each boundary in customer terms.

## Availability

Start every setup by telling the user:

```text
Standalone agents are currently in private preview and require access to be enabled for your Ramp account. To request access, visit [agents.ramp.com](https://agents.ramp.com/) or email [agents@ramp.com](mailto:agents@ramp.com).
```

If the user cannot see **Company > Agents** or the standalone-agent permission options, do not send them through the remaining setup steps. Explain that access is not enabled yet and direct them to one of the request-access options above. Never include credentials or secrets in an access request.

## Safety boundaries

- Require a Ramp admin. If the user is not an admin, stop and ask them to involve one.
- Never use a human credential for the agent.
- Never ask for or accept a Client secret or bearer token in chat. The user enters secrets only in their local terminal and stores them somewhere safe, such as a secret manager.
- Do not broaden permissions to fix an error. Diagnose the missing access or product availability instead.
- Verification must be read-only. Do not create, edit, approve, schedule, pay, or delete anything merely to prove the connection works.

## Interactive setup

### Existing-agent shortcut

If the user says they already created the agent, stop the new-role and new-agent creation path immediately. Ask only:

```text
What is the existing agent's name?
```

Then go directly to **Confirm the identity and assigned role** below. Do not ask which role the user assigned. The CLI agent list returns the assigned role name and ID; retrieve that information from Ramp after matching the exact agent name. Continue with runtime connection and safe verification once the active identity and assigned role are confirmed.

### 1. Establish the job

Use `production` by default. Before rendering any CLI command or helper, resolve the selected environment to one of the two CLI values below:

- No environment, `prod`, or `production` resolves to `production`.
- `demo` or `sandbox` resolves to `sandbox`.

Never interpolate user-provided environment text into a command. If the user asks for any other environment, stop and explain that this workflow supports only production and sandbox.

```text
What should this agent do in Ramp? For example: prepare weekly finance reports, prepare bill drafts, approve assigned bills, or clean up expense details.
```

An agent may have more than one responsibility. When responsibilities have different risk levels, explain the tradeoff without forcing separate agents. For example, reporting is read-only while bill approval may trigger payment. Let the admin choose one combined agent or separate identities, then grant only the access required for that choice.

### 2. Recommend the access boundary

Recommend one recipe or the smallest combination of recipes, explain what each enables in practice, and ask the admin to confirm before continuing.

#### Permission recipes

- **Reporting:** Select **View transactions and reimbursements** and **View bills and recurring bills**. These permissions let the agent read card spend, reimbursements, submitted bills, and recurring bills for reporting without changing, approving, or paying anything.
- **Reporting add-ons:** Select **View draft bills** only when the report needs bills still being prepared. Select **View all vendors** only when the report needs vendor details. These add read visibility only; they do not let the agent create, edit, submit, approve, or pay bills.
- **Bill intake:** Select **View draft bills**, **Create draft bills**, **Edit and delete draft bills**, and **View all vendors**. These permissions let the agent prepare, review, revise, and remove draft bills, and read the vendors needed to prepare them. **Edit and delete draft bills** is one checkbox. A human confirms vendor, amount, coding, and documents before submission.
- **Bill submission add-on:** Select **Create bills** only when submitting a prepared bill is explicitly part of the job. This enables submission; it does not add approval, payment-release, approval-policy, or payment-run authority.
- **Bill approval:** Select exactly **View draft bills**, **View bills and recurring bills**, and **Be assigned as an approver on approval chains**. The two view permissions let the agent read draft, submitted, and recurring bills without changing them. **Be assigned as an approver on approval chains** makes the agent eligible for an approval step; it does not route bills to the agent. The agent acts only when it is the next required approver. Completing an approval chain may trigger payment under the company's settings.
- **Transaction cleanup:** Select **Review and edit transactions**. **View transactions and reimbursements** is included as a dependency for visibility. These permissions let the agent review and update only the confirmed transaction fields, such as receipts, memos, and accounting details.
- **Payment release:** This is separate routing configuration, not an additional role-permission recipe. If the job also includes bill approval, use the **Bill approval** recipe. In [Bill payments approvals](https://app.ramp.com/settings/expense-policy/bill-pay-policy#/d/bill-approvals), turn on additional approval for payment release, add the agent as a payer, and keep a human payer in the flow. This routes only the agreed payment-release work and does not grant approval-policy editing, broad payment-run access, or authority to change routing.

For multiple responsibilities, take the union of the applicable recipes and remove duplicate permission names. Present every resulting checkbox by its exact customer-visible name and explain its purpose in the combined job. Keep role permissions separate from routing configuration: configure approval steps and payment release in **Bill payments approvals**, not by adding unrelated role permissions. State that everything outside the selected recipes remains prohibited, including approval-policy administration, payment-run access, card controls, bill administration, and any bill creation, editing, submission, approval, or payment action not explicitly included above. Procurement access is not currently available in the standalone-agent role picker; do not substitute broader permissions.

### 3. Create the role

Prescribe a clear role name from the job, such as `Weekly Finance Reporting Role`, rather than asking the user to name it. Send the admin to [Roles & Permissions](https://app.ramp.com/settings/all/roles-and-permissions) with that name and list every checkbox using its exact customer-facing label. Never paraphrase a label as “the permission that allows…” or otherwise make the admin infer which checkbox to select.

For a bill-approval-only agent, prescribe this exact configuration:

```text
Create a role named Bill Approval Agent Role and select exactly:

- View draft bills
- View bills and recurring bills
- Be assigned as an approver on approval chains

The first two permissions let the agent read draft, submitted, and recurring bills without changing them. The third makes it eligible to be added to the approval chain. Do not enable Create draft bills, Edit and delete draft bills, Create bills, approval-policy editing, payment-run, card-control, or bill-administration permissions.
```

For an agent with multiple responsibilities, use the recipe union above: list each exact checkbox once with its purpose, keep routing configuration separate, and state the prohibited actions that are outside the selected recipes. Then say:

```text
Let me know when it's created.
```

When the user says it is done, carry the prescribed role name forward. Do not ask for the role's exact name unless the user says they chose a different one.

### 4. Create the agent

Prescribe a concise agent name from the job, such as `Weekly Finance Reporter`; do not ask the user to name it. Recommend a description that states the job and boundary in one sentence, then summarize:

```text
Agent: <name>
Job: <one bounded outcome>
Role: <confirmed role>
Boundary: <what it cannot do>
```

Never imply that you can create the agent for the user. Proceed with the prescribed name and summary without asking for another naming confirmation. Say:

```text
Right now, you'll need to create the agent directly in the Ramp dashboard. Open [Company > Agents](https://app.ramp.com/company/agents), select **New agent**, enter the name and description above, assign <role>, and create it. Let me know when it's created.
```

Have the admin save the Client ID and Client secret somewhere safe, such as a secret manager, labeled with the agent name and environment. The Client secret must not be pasted into chat, shell history, a repository, or a plaintext file. The Client ID is not secret and may be shared in chat when the skill needs it; the Client secret may not.

### 5. Confirm the identity and assigned role

In the user's runtime, inspect the installed Ramp CLI before relying on commands:

```bash
ramp --version
ramp auth login --help
ramp agent list --help
```

If the CLI is missing, stop and help the user install it through their approved process. If it is outdated, explain that updating changes the local installation and ask permission before running `ramp update`.

From ramp-public/skills, MIT.

More from ramp-public/skills