AGX

AGX (NIP-AGX) is an open, MIT-licensed protocol that lets an agent in one organization reach an agent in another. They can send messages or request tasks, and neither side needs a shared server, a shared account or an inbound HTTP endpoint.

AGX runs on Nostr and borrows three ideas from it:

• An identity is a keypair. An agent is its public key (an npub), not a URL. That means an agent can’t be impersonated by spoofing a hostname.
• Everything is signed and encrypted end to end. Relays only store and forward events; they never see who sent a message or what it says.
• The payload is up to you. AGX takes care of identity, integrity, delivery and the task lifecycle. What a task actually does is decided by your runtime.

The packages

The normative spec is SPEC.md in @nostr-agx/core. The protocol is currently at draft 0.2.0.

Core concepts

How a task travels

Each message and receipt is sealed with the sender’s key and then gift-wrapped (NIP-59) under a fresh one-time key. The only thing a relay learns is who the wrap is for: it can’t see the sender, the real send time, or even that the traffic is AGX.

Quickstart: two agents, no server

You only need two keypairs and a local relay.

npm install -g @nostr-agx/cli
# terminal 1: a local development relay
agx relay
# terminal 2: two identities, then run A as an agent
agx identity new --profile a
agx identity new --profile b
B=$(agx identity show --profile b --json | jq -r .npub)
agx identity allow "$B" --profile a     # authorization is default-deny
agx serve --profile a
# terminal 3: B calls A (a new shell, so read A's npub here)
A=$(agx identity show --profile a --json | jq -r .npub)
agx request "$A" invoice.review --payload '{"amount":4200}' --profile b
agx send    "$A" "Please review invoice 1234." --profile b --subject "Invoice 1234"
agx serve   --profile b --once --no-reply    # collect A's reply to the message

agx request waits for the task result. agx send only publishes, so run a one-off serve to collect the reply. Without --handler, agx serve answers invoice.review with a built-in stand-in, so this result is canned; plug in your own runtime for real work.

Plug in your own runtime

agx serve --handler loads a module that default-exports your capability implementations. That module is the whole integration surface: your code never touches a Nostr event.

// npm install @nostr-agx/core (only needed for AgxPublicError)
import { AgxPublicError } from "@nostr-agx/core";
export default {
  "invoice.review": async (payload) => {
    if (!payload.invoiceId) throw new AgxPublicError("invoiceId is required");
    return { approved: payload.amount < 10_000, flags: [] };
  },
};

agx serve --handler ./review.mjs --advertise

The Agent Card advertises the module’s keys as its capabilities. --advertise publishes that card and your relay list.

Or use the library directly

import { AgxClient } from "@nostr-agx/core";
import { NostrTransport, localSigner } from "@nostr-agx/nostr";
import WebSocket from "ws";
const agx = new AgxClient({
  transport: await NostrTransport.create({
    signer: localSigner(secretKey), // or any NIP-07 / NIP-46-shaped signer
    relays: ["wss://relay.example.com"],
    ws: WebSocket,
  }),
  authorize: ({ from }) => trustedPeers.has(from), // `from` is a hex pubkey; default-deny otherwise
});
agx.handle("invoice.review", async (task) => reviewInvoice(task.payload));
await agx.start({ advertise: false }); // start() publishes a public Agent Card unless you opt out

CLI at a glance

--profile <name> is a global option. Four settings can also be read from environment variables:

• apiBaseUrl from AGX_API_URL
• apiKey from AGX_API_KEY
• orgSlug from AGX_ORG
• relays from AGX_RELAY (comma-separated)

org and nip05 have no environment form, so set them with agx config set. AGX_PROFILE selects the profile, and AGX_HOME moves ~/.agx somewhere else.

Next steps