Quickstart

1. Sign in at the app

Create an account.

app.canopyhq.dev

2. Add an inference option

Connect and configure an Openrouter key and model.

app.canopyhq.dev/inference

3. Install the SDK

bun/npm/pnpm add @canopyhq/sdk zod

4. Declare a tool

This is the schema and metadata that will be presented for the tenant to consent to; separate from the execution definition.

import * as z from "zod";
import { Canopy, appdoc, bind, declare, propose, type Bindings } from "@canopyhq/sdk";

const tools = {
  refund: declare({
    description: "refund a payment",
    input: z.object({ amount: z.int(), customer: z.string() }),
    output: z.object({ refunded: z.int() }),
  }),
};

5. Derive the document

Combine tool metadata and application-wide metadata into an Application Document which will be presented to tenant for consent.

const document = appdoc({ name: "payhq", description: "moves money" }, tools);

6. Propose and Consent

Propose the composed Application Document, then store the retrieved key upon consent.

const proposal = await propose(document);
console.log("consent at", proposal.consentUrl);

const { key } = await proposal.granted();

refund a paymentrefund

No restrictions

7. Bind and open

Define executors for tools and open a session.

const refunds = (ledger: Ledger): Bindings<typeof tools> => bind(tools, {
  refund: async ({ amount, customer }) => ({ refunded: await ledger.refund(customer, amount) }),
});

const canopy = new Canopy({ key });
const session = await canopy.open({
  principal: "user:aiden",
  instructions: "Help customers with their payments.",
  tools: refunds(ledger),
});

8. Send one message

Await a single turn and close the session.

const turn = await session.send("refund c-9 five dollars");
console.log(turn.reply, turn.finish);
await session.close();

9. Read the tail

Read the first twenty events of the session.

for await (const record of session.records({ from: 0, to: 20 })) {
  console.log(record);
}

Session 7c1e…a9f2

Every record the session landed, in order. This is the audit trail.

#	time	producer	kind
2	10:03:12	user:sam	message“refund invoice 4471, it was billed twice”	“refund invoice 4471, it was billed twice”
3	10:03:12	harness	inference.requestedturn #2 · round 1	turn #2 · round 1
5	10:03:13	inference	inference.completedsealedcalls refund · 1,204 prompt tokens	calls refund · 1,204 prompt tokens
7	10:03:13	authorizer	invoke.allowedrefund · released to its executor	refund · released to its executor
9	10:03:14	executor	invoke.completedsealedrefund · result sealed · digest c02d7e19…	refund · result sealed · digest c02d7e19…
11	10:03:16	inference	inference.completedstop · “Refunded invoice 4471 (re_3k9).” · 1,388 prompt tokens	stop · “Refunded invoice 4471 (re_3k9).” · 1,388 prompt tokens
12	10:03:16	harness	turn.endedturn #2 · completed	turn #2 · completed