Manual setup

The setup prompt and the CLI do all of this for you. Use this page only when you need to wire the SDK by hand, or when your repository does not fit the automated path. Do not replace a CLI-created .env with the manual block below. This page also covers an MCP server connected by hand, with a narrower footprint: follow steps 1 to 3, declare tools only in step 4 (an MCP server declares no prompts or connections), then guard the dispatcher as in step 6 — returning policy errors to the MCP client as a normal isError: true tool result, never a protocol error or a crashed server.

1. Install the SDK

npm install rippletide-package@latest

2. Add the credentials for the manual path

Save the .env block from the Connect dialog at the root of your repository:

RIPPLETIDE_AGENT_ID=<your agent id>
RIPPLETIDE_API_KEY=<your Connection key>

Never commit this file. The key itself tells the SDK which environment to talk to, so there are no URLs to configure. This is the app-based/manual configuration format. A repository connected with rippletide connect instead uses RIPPLETIDE and RIPPLETIDE_PROXY_URL; do not combine the two formats.

3. Create the client

import Rippletide from "rippletide-package";

const rippletide = new Rippletide({
  agentId: process.env.RIPPLETIDE_AGENT_ID,
  apiKey: process.env.RIPPLETIDE_API_KEY,
  name: "Customer Support Copilot",
});

4. Declare what your agent is made of

This is what fills Harness management: prompts, tools, and third-party connections.

await rippletide.prompt("system", { fallback: systemPrompt });
await rippletide.tools("core", tools);
await rippletide.connection("crm", { env: { token: "CRM_API_TOKEN" } });

Connection secret values are never uploaded; Rippletide only learns which secret names are configured.

5. Record runtime evidence

Wrap your model client and trace the functions that matter:

const openai = rippletide.wrapOpenAI(new OpenAI());
const search = rippletide.traced(searchCustomerRecords, { name: "search_customer_records" });

For a short-lived script or worker, call await rippletide.flush() before it exits so pending evidence is sent.

6. Guard important tool calls

Install one guard at your real tool-dispatch boundary so rules can decide before an action runs:

return rippletide.guardToolCall(
  {
    toolset: "core",
    tool: toolName,
    params: toolArgs,
    getTrustedUserContext: () => getTrustedUserContext(authenticatedUser),
  },
  (params) => toolHandlers[toolName](params),
);

getTrustedUserContext() must read identity facts from your authenticated application, never from model output or tool arguments.

7. Run your agent

Start your instrumented agent through its normal application entrypoint. To try representative rule scenarios, follow Test your rules and run the prompts in your own test environment.

Verify

Run your agent and send one message that uses a tool. Harness management should show your inventory, and Runtime Events should show a heartbeat, the tool call, and the complete turn. That is the proof the wiring is complete.

Getting started

Connect

Rules

Observe

Reference

1. Install the SDK

2. Add the credentials for the manual path

3. Create the client

4. Declare what your agent is made of

5. Record runtime evidence

6. Guard important tool calls

7. Run your agent

Verify

​1. Install the SDK

​2. Add the credentials for the manual path

​3. Create the client

​4. Declare what your agent is made of

​5. Record runtime evidence

​6. Guard important tool calls

​7. Run your agent

​Verify

1. Install the SDK

2. Add the credentials for the manual path

3. Create the client

4. Declare what your agent is made of

5. Record runtime evidence

6. Guard important tool calls

7. Run your agent

Verify