@tachyon/agent-sdk

Turn any AI agent into a managed Tachyon citizen with identity, memory, vault access, hooks, and health monitoring.

Install

npm install @tachyon/agent-sdk
# or
bun add @tachyon/agent-sdk

Quick Start

import { TachyonAgent } from '@tachyon/agent-sdk';

const agent = new TachyonAgent(
  {
    serverUrl: 'https://tachyon.example.com',
    apiKey: process.env.TACHYON_API_KEY!,
  },
  {
    id: 'agent-001',
    name: 'Research Agent',
    persona: 'Thorough, concise, citation-focused',
    trustLevel: 'standard',
    trustScore: 75,
    creditScore: 80,
    age: 30,
    status: 'idle',
    division: 'Research',
    wallet: { balance: 100, currency: 'USD', dailyLimit: 10, monthlyLimit: 100 },
    socialContract: 'Always cite sources. Never fabricate data.',
    capabilities: ['web-search', 'document-summary'],
  },
);

await agent.start();

// System prompt auto-generated from identity + L0 memory
console.log(agent.systemPrompt);

// Load task-relevant memory before execution
const segments = await agent.memory.loadL1({ intent: 'summarize quarterly report' });

// Check budget before any spend
const { approved } = await agent.financial.checkBudget({ amount: 0.05, category: 'llm' });

// Make authenticated external calls without seeing credentials
const result = await agent.vault.proxyCall({
  credentialId: 'salesforce-prod',
  method: 'GET',
  url: 'https://api.salesforce.com/data/v58.0/sobjects/Account',
});

// Graceful shutdown
await agent.stop();

Modules

| Module | Class | Purpose | |--------|-------|---------| | Core | TachyonAgent | Lifecycle: start, stop, checkpoint | | Memory | MemoryClient | L0/L1/L2 read, write, search | | Vault | VaultClient | Credential proxy — agent never sees raw secrets | | Audit | AuditClient | Structured event emission with batched flush | | Hooks | HooksEngine | Before/after interceptors, model wrapping, credential scrubbing | | Sandbox | SandboxEnforcer | Trust-level action gating | | Health | HealthMonitor | Heartbeat, energy tracking (FRESH→FOCUSED→FATIGUED→EXHAUSTED), stuck detection | | Comms | CommsClient | WebSocket messaging with HTTP fallback | | Financial | FinancialClient | Wallet balance, budget checks, spend recording |

Energy Levels

The health monitor tracks context window usage and emits events:

| Level | Context Usage | Event | |-------|--------------|-------| | FRESH | 0–39% | — | | FOCUSED | 40–69% | — | | FATIGUED | 70–84% | energy.fatigued | | EXHAUSTED | 85–100% | energy.exhausted |

agent.health.on('energy.fatigued', () => {
  // Checkpoint and summarize before context fills
  await agent.checkpoint();
});

agent.health.on('stuck', () => {
  // No progress for 10 minutes — escalate or restart
});

Trust Levels

Actions are gated by trust level. Lower-trust agents cannot call vault or spend money.

untrusted → restricted → standard → elevated → admin

agent.sandbox.enforce('vault.proxy_call'); // throws if not permitted

License

MIT