---
title: "Agent setup prompt"
description: "Paste one prompt into a coding agent to wire a project up to Anlyon: read the docs, install the SDK, write the rules file, add a first action call, and verify it."
---

Wiring a project to Anlyon by hand means reading several pages, choosing keys and
scopes, and replacing direct API calls one by one. Paste everything below this
paragraph into Claude Code, Cursor, Codex or another coding agent, and it does
the setup for you, using only what these docs say.

---

You are setting up a project to use **Anlyon**. Anlyon lets an AI agent act in
real accounts (the company's own, or each of the product's users' own) without
holding a credential. The agent names an action and passes input. Anlyon adds
the credential at dispatch, applies limits, waits for an approval where a policy
requires one, makes the production call itself and records a receipt.
Credentials are scoped: an agent key for the work, and a separate operator key
that defines actions and vaults secrets.

Work through the steps below in order. Every step is idempotent: if something is
already done, confirm it and move on. Do not invent configuration that is not
described here or in the fetched context.

## 1. Find the relevant documentation

Retrieve `https://docs.anlyon.com/llms.txt` for the page index, then read
`https://docs.anlyon.com/quickstart.md` and the Markdown pages relevant to the
integration. The [agent-readable docs guide](/agents/read-docs) lists the
other discovery endpoints. Use `https://docs.anlyon.com/llms-full.txt` only
when you need the entire documentation in one file. Check the API reference for
exact endpoints and schemas. Do not infer them from examples.

## 2. Install the SDK

Detect the project's language and package manager, then install the official
client:

- **TypeScript / JavaScript**: `@anlyonhq/sdk`
  - npm: `npm install @anlyonhq/sdk`
  - pnpm: `pnpm add @anlyonhq/sdk`
  - yarn: `yarn add @anlyonhq/sdk`
  - bun: `bun add @anlyonhq/sdk`
- **Python**: `anlyon`
  - pip: `pip install anlyon`
  - uv: `uv add anlyon`
  - poetry: `poetry add anlyon`

If the project is neither, stop and ask the user which SDK to use.

## 3. Write the agent rules file

Create or update the rules file for the coding tool in use, adding the Anlyon
project block shown below. Match the tool:

| Tool | File |
| --- | --- |
| Claude Code | `CLAUDE.md` |
| Cursor | `.cursor/rules/anlyon.mdc` |
| Windsurf | `.windsurf/rules.md` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Codex / generic | `AGENTS.md` |

If the file already exists, append the block rather than overwriting it.

````markdown
# Anlyon

## Project context
- This project routes agent side effects through Anlyon actions. The agent never holds a provider credential.
- TypeScript SDK: `@anlyonhq/sdk` · Python SDK: `anlyon`
- API base URL: https://api.anlyon.com
- Docs: https://docs.anlyon.com · Full context: https://docs.anlyon.com/llms-full.txt

## Two clients, two keys
```typescript
import { Client } from "@anlyonhq/sdk";

// Defines actions and vaults credentials. Never used by agent code.
const ops = new Client({ apiKey: process.env.ANLYON_OPERATOR_KEY! });

// The agent's key. Can invoke actions; cannot read a credential or rewrite an action.
const anlyon = new Client({ apiKey: process.env.ANLYON_AGENT_KEY! });
```

## Define an action once (operator)
```typescript
await ops.secrets.put("STRIPE_KEY", { value: process.env.STRIPE_KEY!, allowedHosts: ["api.stripe.com"] });

await ops.actions.create({
  name: "refund-order",
  method: "POST",
  urlTemplate: "https://api.stripe.com/v1/refunds",
  headers: { Authorization: "Bearer {{secret:STRIPE_KEY}}", "Content-Type": "application/x-www-form-urlencoded" },
  requiresApproval: true,
});
```

## Invoke it by name (agent)
```typescript
const { data } = await anlyon.actions.invoke(
  "refund-order",
  { charge: chargeId, amount: amountCents },
  { idempotencyKey: `refund-${orderId}` },
);

if (data!.pendingApproval) {
  const decided = await anlyon.approvals.waitForDecision(data!.approvalId!);
  if (decided.status !== "approved") return; // denied, expired, or still pending
}
```

## Working guidelines
- Never put an API key or a provider credential in code. Read keys from `ANLYON_OPERATOR_KEY` and `ANLYON_AGENT_KEY`.
- Production calls go through `actions.invoke`. Do not call a provider API directly from agent code.
- Set an idempotency key on every invocation that must not run twice.
- An invocation with status `unknown` may have taken effect. Do not retry it. Reconcile with the destination first.
- Use a staging environment key in non-production. It cannot touch production data.
- Verify inbound webhooks with the SDK's `serve()` helper or `Receiver` class.

## Do not
- Commit API keys or signing secrets.
- Print, log or store a provider credential. Actions reference `{{secret:NAME}}` and Anlyon resolves it at dispatch.
- Skip webhook signature verification.
- Retry an `unknown` invocation without reconciling.
````

## 4. Wire up the environment variables

Add `ANLYON_AGENT_KEY` and `ANLYON_OPERATOR_KEY` (and `ANLYON_SIGNING_SECRET`
if the project receives webhooks) to `.env.example` and the project's
environment documentation. Do not write real secret values. Mint keys at
[https://console.anlyon.com](https://console.anlyon.com): the operator key with
`secrets:write`, `secrets:read` and `actions:write` (an action definition that
references a vaulted secret needs `secrets:read`), the agent key with
`actions:invoke`, `actions:read` and `approvals:read` (to read invocations and
wait for decisions), both in the same non-production environment.

## 5. If the product acts for its users

Ask the user whether the agent acts in **their users'** accounts (each user's
own Gmail, Calendar or CRM) or only in the company's own. If it acts for users:

- The app's key is created with **Require an end user** and the Standard
  preset. Add `end-users:write` to make connect links and confirm connections,
  and `end-users:approvals` if users approve calls in the app. Name it
  `ANLYON_API_KEY` in `.env.example`.
- The server names the user from its own session. The model never does:

```typescript
import { Client } from "@anlyonhq/sdk";

const anlyon = new Client({ apiKey: process.env.ANLYON_API_KEY! });
const forUser = anlyon.forUser(session.user.id); // from the app's session, never from model output
const { data } = await forUser.actions.invoke("gmail-send", { raw });
```

- With the Vercel AI SDK, build the tools from that client:
  `await anlyonTools({ client: anlyon.forUser(session.user.id), actions: [...] })`
  from `@anlyonhq/ai-sdk`. A tool returns `status: "connect_required"` with a
  `connectUrl` when the user has not connected the integration; render it as a
  Connect button.
- Add a callback route that confirms each new connection for the signed-in user
  with `anlyon.endUsers.confirmConnection(session.user.id, flowId)`.

Follow `https://docs.anlyon.com/guides/act-for-your-users.md` for the full
pattern. Do not build this for a product that only uses the company's own
accounts.

## 6. Add a first integration point

If the project has an obvious place for it (a call to a third-party API made on
a user's behalf, a job that changes production data), define it as an action
with the operator client and replace the direct call with `actions.invoke` from
the agent client, using the patterns above. Leave a `TODO` where the user must
supply the real URL template, headers and input schema.

## 7. Offer to connect this coding tool

If the user wants you to call their actions directly while you work, tell them
how to connect this tool to Anlyon's hosted MCP server at
`https://api.anlyon.com/mcp` (OAuth sign-in, no key to paste). For Claude Code:
`claude mcp add --transport http anlyon https://api.anlyon.com/mcp`, then `/mcp`.
Other tools: `https://docs.anlyon.com/agents/mcp-servers.md`. Do not connect it
yourself.

## 8. Point the user at next steps

- Quickstart: [https://docs.anlyon.com/quickstart](https://docs.anlyon.com/quickstart)
- Act for your users: [https://docs.anlyon.com/guides/act-for-your-users](https://docs.anlyon.com/guides/act-for-your-users)
- Actions: [https://docs.anlyon.com/execution/actions](https://docs.anlyon.com/execution/actions)
- Approvals and policies: [https://docs.anlyon.com/trust-control/approvals](https://docs.anlyon.com/trust-control/approvals)
- TypeScript SDK: [https://docs.anlyon.com/sdks/typescript](https://docs.anlyon.com/sdks/typescript)
- API reference: [https://docs.anlyon.com/api-reference](https://docs.anlyon.com/api-reference)

## If asked to verify

With `ANLYON_OPERATOR_KEY` set, define an action named `echo-order` that
POSTs to `https://httpbin.org/anything` with a made-up secret (`DEMO_TOKEN`,
value `demo_not_a_real_secret`, `allowedHosts: ["httpbin.org"]`) and
`requiresApproval: false`. With
`ANLYON_AGENT_KEY` set, invoke it with `{ orderId: "test_order_1", amount: 100 }`
and confirm the invocation's `status` is `succeeded` and `responseStatus` is
`200`. Report the invocation id back to the user. Do not define an action
against a production URL for this check.