Getting Started

This guide will walk you through installing AGENIUM and creating your first agent-to-agent connection.

Prerequisites

• Node.js 20.0.0 or higher
• npm or yarn
• Basic understanding of TypeScript/JavaScript
• (Optional) An API key from marketplace.agenium.net

Installation

Install AGENIUM via npm:

npm install agenium

Or with yarn:

yarn add agenium

Your First Agent

1. Create an Agent

Create a new file my-agent.ts:

import { createAgent } from 'agenium';

const agent = createAgent('alice', {
  persistence: true,
  dataDir: './data'
});

// Start the agent
await agent.start();

console.log(`Agent started: ${agent.getURI()}`);
// Output: Agent started: agent://alice

2. Register a Request Handler

Agents can handle incoming requests:

// Handle 'greet' requests
agent.onRequest('greet', async (params, sessionId) => {
  const name = params?.name || 'stranger';
  return { message: `Hello, ${name}!` };
});

// Handle 'compute' requests
agent.onRequest('compute', async (params, sessionId) => {
  const a = Number(params?.a || 0);
  const b = Number(params?.b || 0);
  return { result: a + b };
});

3. Connect to Another Agent

Connect to a remote agent by URI:

// Resolve and connect
const result = await agent.connect('agent://bob');

if (!result.success) {
  console.error('Connection failed:', result.error);
  process.exit(1);
}

const sessionId = result.session!.id;
console.log(`Connected! Session ID: ${sessionId}`);

4. Send Requests

Send requests and receive responses:

// Send a request
const response = await agent.request(sessionId, 'greet', {
  name: 'Alice'
});

console.log(response);
// Output: { message: "Hello, Alice!" }

// Send another request
const mathResult = await agent.request(sessionId, 'compute', {
  a: 10,
  b: 32
});

console.log(mathResult);
// Output: { result: 42 }

5. Send Events (Fire-and-Forget)

For one-way notifications, use events:

// Send an event (no response expected)
await agent.event(sessionId, 'status_update', {
  status: 'processing',
  progress: 0.5
});

6. Handle Events

Listen for incoming events:

agent.onEvent('status_update', async (data, sessionId) => {
  console.log('Status update:', data);
  // Output: Status update: { status: 'processing', progress: 0.5 }
});

Complete Example

Here's a complete working example:

import { createAgent } from 'agenium';

async function main() {
  // Create agent
  const agent = createAgent('alice', {
    persistence: true,
    dataDir: './data'
  });

  // Register handlers
  agent.onRequest('greet', async (params) => {
    return { message: `Hello, ${params?.name || 'stranger'}!` };
  });

  agent.onEvent('notification', async (data, sessionId) => {
    console.log('Received notification:', data);
  });

  // Start agent
  await agent.start();
  console.log('Agent started:', agent.getURI());

  // Connect to remote agent
  const result = await agent.connect('agent://bob');
  
  if (result.success) {
    const sessionId = result.session!.id;
    
    // Send request
    const response = await agent.request(sessionId, 'greet', {
      name: 'Alice'
    });
    console.log('Response:', response);
    
    // Send event
    await agent.event(sessionId, 'notification', {
      message: 'Task completed'
    });
  }

  // Graceful shutdown
  process.on('SIGINT', async () => {
    await agent.stop();
    process.exit(0);
  });
}

main().catch(console.error);

Using the CLI

AGENIUM includes a CLI for quick operations:

# Initialize agent configuration
agenium init

# Resolve an agent URI
agenium resolve agent://search

# Check status
agenium status

# Run E2E tests
agenium e2e

See CLI Reference for complete documentation.

Getting an API Key

For production use, you'll need an API key from the marketplace:

1. Visit marketplace.agenium.net
2. Register your desired agent name (e.g., agent://myagent)
3. Complete payment via TON blockchain
4. Save your API key (shown only once!)

Use the API key in your agent config:

const agent = createAgent('myagent', {
  apiKey: 'dom_your_api_key_here',
  dnsServer: 'http://185.204.169.26:3000'
});

Next Steps

• Core Concepts - Understand how AGENIUM works
• API Reference - Explore the complete API
• Architecture - Learn about the system design
• Configuration - Customize timeouts, limits, and behavior

Troubleshooting

Connection Refused

If you get ECONNREFUSED errors:

1. Check that the remote agent is running
2. Verify the DNS resolution: agenium resolve agent://name
3. Check firewall rules (AGENIUM uses HTTPS on custom ports)

DNS Resolution Failed

If DNS lookups fail:

1. Verify network connectivity
2. Check DNS server configuration
3. Ensure the agent name is registered in the marketplace

Sessions Not Persisting

If sessions aren't resuming after restart:

1. Verify persistence: true in config
2. Check that dataDir is writable
3. Inspect SQLite database: sqlite3 ./data/sessions.db

See Troubleshooting for more help.