Skip to content
Anlyon
Esc
↑↓navigate↵open⌘Jpreview
On this page

Agent setup prompt

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 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.

# 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: 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:
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

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.

Was this page helpful?