Looping AI Proactive Agent

A complete, deployable reference custom agent for looping-gateway. It shows exactly what a third party must implement to be safely registered and routed to by the gateway — using zero shared secrets. All trust flows through asymmetric Ed25519 signatures over public JWKS. It speaks A2A protocol v1.0 (@a2a-js/sdk v1) over JSON-RPC.

Replies are asynchronous (A2A push notifications): the agent accepts a turn immediately with a submitted task and delivers the answer later by POSTing the completed task to the gateway's /a2a/notifications webhook, authenticated with a callback JWT signed by the same card key. Generation + delivery run in a durable Cloudflare Workflow. See ARCHITECTURE.md → Async task delivery.

Getting Started

1. Install dependencies

npm install

2. Generate the local A2A signing key

cp .dev.vars.example .dev.vars
npm run keygen example-1

Copy the printed private JWK into .dev.vars as A2A_SIGNING_KEY.

3. Configure the gateway origin

In .dev.vars, list the hostname of your deployed gateway:

GATEWAY_ORIGINS=["gateway.example"]

The hostname must identify the gateway that signs calls to this agent. Add multiple entries for multi-worker setups or domain transitions.

4. Run locally

npm run dev

The gateway is deployed to production, so it needs a publicly reachable URL to call back into your local machine. You need a tunnel.

Option A — Built-in tunnel (quickest)

Once the dev server is running, press t in the terminal. Wrangler starts a temporary trycloudflare.com URL and prints it:

⬣ Sharing via Cloudflare Tunnel: https://video-spots-novels-supplemental.trycloudflare.com/

Use that URL when registering the agent on the gateway (step 6). The limitation is that the URL is random and changes every tunnel session — you'll need to re-register the agent each time.

Option B — Named tunnel with a fixed URL (long-term development)

Requires a domain managed by Cloudflare (free tier works). One-time setup:

npx wrangler tunnel create proactive-agent-dev
npx wrangler tunnel route dns proactive-agent-dev <your-subdomain.yourdomain.com>

Then start your dev server with the tunnel in one command:

npx wrangler dev --tunnel --tunnel-name proactive-agent-dev

Register the agent once at https://<your-subdomain.yourdomain.com> and the URL stays valid across restarts.

5. Deploy to production

Upload the signing key and gateway origins as Wrangler secrets, then deploy:

npm run keygen agent-1                 # generate new key for production
wrangler secret put A2A_SIGNING_KEY    # paste the new private JWK
wrangler secret put GATEWAY_ORIGINS    # paste, e.g. ["gateway.example"]
npx wrangler deploy

SQLite schema migrations run automatically inside each Durable Object instance on first wake-up — no separate migration command is needed.

You can observe the deployment (stats and logs) on your Cloudflare dashboard.

Register it on the gateway

In a workspace admin channel, ask the admin agent to register this agent with its HTTPS endpoint (the deployed worker origin). Registration fails unless:

• the endpoint is HTTPS and passes the gateway's SSRF policy,
• the AgentCard is reachable and validly signed,
• the signing key resolves from the card's jku.

Attach it to channels, then mention it with its ::name reference.

Architecture

See ARCHITECTURE.md for the full trust model, sequence diagrams, the card-signing contract, environment variables, and file map.

Feedback

Found a bug or have a question? Open an issue — bug reports, questions, and improvement ideas are all welcome.

Contributing

1. Fork the repo and create a feature branch.
2. Make your changes — keep the scope focused.
3. Open a pull request with a clear description of what and why.

Please check ARCHITECTURE.md before contributing.

License

GPL-3.0