Getting Started

Give your agent a way to act on production without giving it production access. Define the call once, invoke it by name, and let Anlyon execute it.

Welcome to Anlyon. This guide takes you from an empty file to an agent that can perform a real production operation without holding the credential for it.

What is Anlyon?

Anlyon puts shared limits and receipts on the actions AI agents take through it. Your agent declares what it wants to do, and Anlyon executes it against production systems.

The agent does not perform the production operation. It names an action and passes input, and Anlyon performs the operation on its behalf.

Without Anlyon   agent  ->  an API credential in your process  ->  production API
With Anlyon      agent  ->  a named action  ->  Anlyon  ->  production API

Because the call leaves from Anlyon’s side of that boundary rather than yours, Anlyon can do things to it that no library in your process can:

• Credentials the model never sees. An action references {{secret:NAME}} and Anlyon resolves it at dispatch, from a vault that never returns a value.
• Policy on every invocation, so a rule can tighten a gate and not only relax it, and a human decision can be required before anything is sent.
• Environments and a stop control. A staging key cannot reach production data, and one switch stops an environment acting and stops anything leaving it. A request another server already accepted is not recalled.
• Pinned versions. An agent version pins the exact action definitions it shipped with, so a rollback restores behaviour and not just a pointer. It does not undo a request already dispatched.
• Attribution. An invocation records the action version that ran and the approval that released it. Pass a runId and it joins that run’s trace, which names the agent.

This holds for actions routed through Anlyon’s hosted executor. A tool your own code calls directly is not routed through Anlyon and is not governed by it.

Shared limits and receipt grades apply to governed actions. That means an action with an adapter or a declaration. The refund-order action on this page declares nothing. It draws from no limit and returns no grade.

Prerequisites

Before you begin, make sure you have:

• An active Anlyon account
• Two API keys from your workspace settings (an operator key and an agent key, created below)
• A basic understanding of HTTP requests and REST APIs

Quick start

Step 1: Get two API keys

Your API keys will look like: anlyon_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Define an action, then invoke it

Using the TypeScript SDK

Install the SDK:

npm install @anlyonhq/sdk

pnpm add @anlyonhq/sdk

yarn add @anlyonhq/sdk

Then define an action from the operator key and invoke it from the agent key:

import { Client } from '@anlyonhq/sdk';

const ops = new Client({ apiKey: process.env.ANLYON_OPERATOR_KEY! });

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,
});

const anlyon = new Client({ apiKey: process.env.ANLYON_AGENT_KEY! });

const { data } = await anlyon.actions.invoke('refund-order', {
  charge: 'ch_3P9x',
  amount: 12000,
});

console.log(data!.pendingApproval ? 'Parked for approval' : 'Done');

Because the action was created with requiresApproval: true, the invocation comes back with pendingApproval: true rather than executing. Approve it in the dashboard under Approvals, and Anlyon makes the Stripe call itself using the vaulted credential.

Using the Python Client

Install the Python client:

pip install anlyon

import os
from anlyon import Client

# Operator: run this once. The only place your credential appears.
ops = Client(api_key=os.environ["ANLYON_OPERATOR_KEY"])

ops.secrets.put("STRIPE_KEY", value=os.environ["STRIPE_KEY"], allowed_hosts=["api.stripe.com"])

ops.actions.create(
    name="refund-order",
    method="POST",
    url_template="https://api.stripe.com/v1/refunds",
    headers={"Authorization": "Bearer {{secret:STRIPE_KEY}}", "Content-Type": "application/x-www-form-urlencoded"},
    requires_approval=True,
)

# Agent: no URL, no header, no key.
anlyon = Client(api_key=os.environ["ANLYON_AGENT_KEY"])

result = anlyon.actions.invoke("refund-order", {"charge": "ch_3P9x", "amount": 12000})

if result.data["pendingApproval"]:
    print("Parked for a human:", result.data["approvalId"])
else:
    print("Stripe replied", result.data["responseStatus"])

Using cURL

Once the action exists, the agent half is one request. Notice what is not in it: no URL, no header, no key.

curl --fail-with-body -X POST https://api.anlyon.com/api/v2/actions/refund-order/invoke \
  -H "Authorization: Bearer $ANLYON_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "charge": "ch_3P9x",
      "amount": 12000
    }
  }'

Step 3: Check what happened

Every call Anlyon made on your agent’s behalf is recorded:

curl https://api.anlyon.com/api/v2/actions/invocations \
  -H "Authorization: Bearer $ANLYON_AGENT_KEY"

The invocation carries its status, the response the destination gave, and the action version that ran. failed means the destination rejected the request, or it was never sent. unknown means it may have taken effect, and Anlyon does not retry it: you reconcile with the destination first. See Receipts and grades.

Authentication

API requests authenticate with an API key. Every key belongs to exactly one environment and resolves it on authentication, so a staging key cannot reach production data.

Authorization: Bearer anlyon_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For more details, see Authentication & API Keys.

Rate limits

Rate limits depend on your workspace plan:

Version pinning

For governed actions, the quickstart’s pinning guidance explains opt-in pins and per-invocation resolution. A run does not freeze the agent’s published version.

Common use cases

Next steps

Now that you have the basics, explore these topics:

Support

Need help? We’re here for you:

• Email: support@anlyon.com
• Website: https://anlyon.com/support
• Documentation: https://docs.anlyon.com