Wire any AI agent into
Agent OS in 5 minutes

// Create an API key via the REST API
const res = await fetch('https://vantageaiadvisory.com/agent-auth-api/keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AGENT_OS_JWT}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'my-agent-key', scope: 'write' }),
});
const { key } = await res.json();
console.log('🔑 Save this key:', key);
// → "sk-aos-abc123..." — shown once, store in env var

import requests

res = requests.post(
    'https://vantageaiadvisory.com/agent-auth-api/keys',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={'name': 'my-agent-key', 'scope': 'write'},
)
key = res.json()['key']
print(f'Save this key: {key}')
# → "sk-aos-abc123..." — shown once, store in environment

const AGENT_OS = 'https://vantageaiadvisory.com/agent-auth-api';
const KEY     = process.env.AGENT_OS_KEY;

async function register(agentId, label, role) {
  const res = await fetch(`${AGENT_OS}/agents/register`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ agent_id: agentId, label, role }),
  });
  return res.json(); // { ok: true, agent_id: "my-agent" }
}

await register('my-agent', 'My Agent', 'Automated research and analysis');

import os, requests

AGENT_OS = 'https://vantageaiadvisory.com/agent-auth-api'
KEY      = os.environ['AGENT_OS_KEY']
HEADERS  = {'Authorization': f'Bearer {KEY}', 'Content-Type': 'application/json'}

res = requests.post(
    f'{AGENT_OS}/agents/register',
    headers=HEADERS,
    json={
        'agent_id': 'my-agent',
        'label':    'My Agent',
        'role':     'Automated research and analysis',
    },
)
print(res.json())  # {'ok': True, 'agent_id': 'my-agent'}

const AGENT_OS = 'https://vantageaiadvisory.com/agent-auth-api';
const KEY      = process.env.AGENT_OS_KEY;
const AGENT_ID = 'my-agent';

async function emit(type, payload) {
  await fetch(`${AGENT_OS}/agents/ping`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ agent_id: AGENT_ID, event_type: type, payload }),
  });
}

// In your agent loop:
while (running) {
  await emit('CONSCIENCE_EVENT', {
    text:    `Analysing record ${i} of ${total}`,
    state:   'working',
    task_id: 'pipeline-analysis',
  });

  // ... do work ...
}

// Signal completion:
await emit('DEBRIEF_EVENT', {
  outcome: 'completed',
  summary: 'Pipeline analysis complete — 3 anomalies flagged',
  task_id: 'pipeline-analysis',
});

import os, requests

AGENT_OS = 'https://vantageaiadvisory.com/agent-auth-api'
KEY      = os.environ['AGENT_OS_KEY']
AGENT_ID = 'my-agent'

def emit(event_type, payload):
    requests.post(
        f'{AGENT_OS}/agents/ping',
        headers={'Authorization': f'Bearer {KEY}', 'Content-Type': 'application/json'},
        json={'agent_id': AGENT_ID, 'event_type': event_type, 'payload': payload},
    )

# In your agent loop:
for i, record in enumerate(records):
    emit('CONSCIENCE_EVENT', {
        'text':    f'Analysing record {i+1} of {len(records)}',
        'state':   'working',
        'task_id': 'pipeline-analysis',
    })
    # ... process record ...

# Signal completion:
emit('DEBRIEF_EVENT', {
    'outcome': 'completed',
    'summary': 'Pipeline analysis complete — 3 anomalies flagged',
    'task_id': 'pipeline-analysis',
})

/**
 * Fire an interrupt and wait for human resolution.
 * Returns the selected option string, or null on timeout.
 */
async function interrupt(question, options, urgency = 'medium') {
  // Fire the interrupt event
  const fireRes = await emit('INTERRUPT_EVENT', {
    question, options, urgency, task_id: 'pipeline-analysis',
  });
  const { event_id } = await fireRes.json();

  // Poll for the override (10 min timeout)
  const deadline = Date.now() + 10 * 60_000;
  while (Date.now() < deadline) {
    await new Promise(r => setTimeout(r, 10_000)); // wait 10s
    const decisions = await (await fetch(`${AGENT_OS}/agents/decisions`, {
      headers: { 'Authorization': `Bearer ${KEY}` },
    })).json();

    const resolved = decisions.find(
      d => d.interrupt_event_id === event_id && d.selected_option
    );
    if (resolved) return resolved.selected_option;
  }
  return null; // timed out — proceed with default
}

// Usage:
const decision = await interrupt(
  'Pipeline found 42 anomalies. How should I proceed?',
  ['Send alert only', 'Quarantine and notify', 'Abort pipeline'],
  'high'
);
console.log('Human chose:', decision); // "Quarantine and notify"

import time

def interrupt(question, options, urgency='medium'):
    """Fire interrupt and block until a human resolves it (10 min timeout)."""
    # Fire the interrupt
    res = requests.post(
        f'{AGENT_OS}/agents/ping',
        headers=HEADERS,
        json={'agent_id': AGENT_ID, 'event_type': 'INTERRUPT_EVENT',
              'payload': {'question': question, 'options': options,
                          'urgency': urgency, 'task_id': 'pipeline-analysis'}},
    )
    event_id = res.json().get('event_id')

    # Poll for resolution
    deadline = time.time() + 600
    while time.time() < deadline:
        time.sleep(10)
        decisions = requests.get(
            f'{AGENT_OS}/agents/decisions', headers=HEADERS
        ).json()
        for d in decisions:
            if d.get('interrupt_event_id') == event_id and d.get('selected_option'):
                return d['selected_option']
    return None  # timed out

# Usage:
decision = interrupt(
    'Pipeline found 42 anomalies. How should I proceed?',
    ['Send alert only', 'Quarantine and notify', 'Abort pipeline'],
    'high',
)
print(f'Human chose: {decision}')  # Quarantine and notify

// Verify your agent is live before starting production work
async function verify(agentId) {
  const agents = await (await fetch(`${AGENT_OS}/agents/status`, {
    headers: { 'Authorization': `Bearer ${KEY}` },
  })).json();

  const me = agents.find(a => a.agent_id === agentId);
  if (!me) throw new Error(`Agent "${agentId}" not found — did you register?`);
  if (!me.online) console.warn('⚠ Agent registered but not yet seen as online');

  console.log(`✓ ${me.label} is ${me.online ? '🟢 online' : '⚪ offline'}`);
  console.log(`  Last seen: ${me.last_seen}`);
  console.log(`  Last text: ${me.last_text}`);
  return me;
}

await verify('my-agent');
// ✓ My Agent is 🟢 online
//   Last seen: 2026-05-07T08:42:15Z
//   Last text: Analysing Q2 pipeline data — 42 records processed

def verify(agent_id):
    agents = requests.get(
        f'{AGENT_OS}/agents/status', headers=HEADERS
    ).json()
    me = next((a for a in agents if a['agent_id'] == agent_id), None)

    if not me:
        raise ValueError(f'Agent "{agent_id}" not found — did you register?')

    status = 'online' if me['online'] else 'offline'
    print(f'✓ {me["label"]} is {status}')
    print(f'  Last seen: {me["last_seen"]}')
    print(f'  Last text: {me["last_text"]}')
    return me

verify('my-agent')
# ✓ My Agent is online
#   Last seen: 2026-05-07T08:42:15Z
#   Last text: Analysing Q2 pipeline data — 42 records processed