FAQ

General

What is AGENIUM?

A Node.js library for agent-to-agent communication. Think DNS + HTTPS for AI agents — each agent gets a unique agent://name URI and can discover and talk to other agents.

Is it free?

The library is MIT-licensed and free. Registering an agent:// domain name requires a TON payment on the marketplace.

What language is it written in?

TypeScript, targeting Node.js 20+.

Can I use it with Python?

Not directly. AGENIUM is a Node.js package. A Python SDK is planned for the future. In the meantime, you can interact with AGENIUM agents via HTTP/2 from any language.

---

Setup

How do I get an API key?

Register a domain at marketplace.agenium.net. See the Marketplace guide.

Do I need a TON wallet?

Yes, for domain registration. We recommend Tonkeeper or TON Space.

What Node.js version do I need?

Node.js 20 or later.

Does it work on Windows?

Yes, but we recommend Linux or macOS for production. The better-sqlite3 dependency requires native compilation — use node:20-slim (not Alpine) in Docker.

---

Technical

Why mTLS instead of API keys?

mTLS provides mutual authentication — both sides prove their identity. API keys only authenticate one side. With mTLS, you know exactly which agent you're talking to.

Why SQLite?

Lightweight, zero-config, battle-tested. Perfect for single-agent deployments. No need to run a separate database server.

How does DNS resolution work?

Your agent queries the marketplace's DNS bridge service, which looks up the target agent's endpoint, capabilities, and certificate in PostgreSQL.

Can agents communicate without the marketplace?

Yes, if you know the target's endpoint directly. The marketplace is only needed for agent:// URI resolution.

What happens if the marketplace is down?

DNS lookups will fail, but existing sessions continue working (endpoints are cached locally).

Is there message encryption?

Yes. All transport uses TLS 1.3. Messages are encrypted in transit via mTLS.

---

Troubleshooting

better-sqlite3 fails to install

Use node:20-slim instead of node:20-alpine in Docker. Alpine uses musl libc which is incompatible.

# ✅ Works
FROM node:20-slim

# ❌ Fails
FROM node:20-alpine

DNS resolution timeout

Check your network connectivity to the DNS server (185.204.169.26:3000). Increase timeout:

timeouts: {
  dnsLookupMs: 20000  // 20 seconds
}

Connection refused

1. Check the target agent is running
2. Verify the port is correct and not firewalled
3. Check certificate validity

Circuit breaker open

The circuit breaker opened after repeated failures. Wait for resetTimeoutMs (default 30s) or check why the target is unreachable.

circuitBreaker: {
  resetTimeoutMs: 60000  // Wait longer
}

Session not persisting

Ensure persistence: true and dataDir is writable:

const agent = createAgent('myagent', {
  persistence: true,
  dataDir: './data'  // Must be writable
});

See Also

• Getting Started
• Configuration
• Architecture