---
title: "Agent setup"
description: "A one-shot prompt that lets a coding agent wire a project up to Anlyon: fetch full context, install the SDK, write the rules file, and verify."
---

You are setting up a project to use **Anlyon**, governed execution for AI
agents. The agent names an action and passes input. Anlyon holds the
credential, evaluates policy, waits for a human where one is required, makes
the production call itself and records the outcome. 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](/agent-setup/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. 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.

## 6. Point the user at next steps

- Quickstart: [https://docs.anlyon.com/quickstart](https://docs.anlyon.com/quickstart)
- 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/guides/typescript-sdk](https://docs.anlyon.com/guides/typescript-sdk)
- 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.