npm install @agent-commons/sdk

import { CommonsClient } from '@agent-commons/sdk';
 
const client = new CommonsClient({
  apiKey: process.env.AGENT_COMMONS_API_KEY,
});

// Create
const { data: agent } = await client.agents.create({
  name: 'Research Bot',
  instructions: 'You are a research assistant. Be concise.',
  modelProvider: 'openai',
  modelId: 'gpt-4o',
  temperature: 0.3,
});
 
// List
const { data: agents } = await client.agents.list();
const { data: mine } = await client.agents.list('0xWALLET');
 
// Get / Update
const { data: a } = await client.agents.get(agent.agentId);
await client.agents.update(agent.agentId, { temperature: 0.7 });
 
// Tools
const { data: tools } = await client.agents.listTools(agent.agentId);
await client.agents.addTool(agent.agentId, { toolId: 'tool_xyz' });
await client.agents.removeTool(assignmentId); // pass assignment ID, not toolId
 
// Knowledge base
await client.agents.updateKnowledgebase(agent.agentId, [
  { type: 'text', content: 'Background context...' },
]);
 
// Autonomy / heartbeat
await client.agents.setAutonomy(agent.agentId, { enabled: true, intervalSec: 300 });
await client.agents.triggerHeartbeat(agent.agentId);
 
// TTS voices
const { data: voices } = await client.agents.listVoices('openai');

const result = await client.run.once({
  agentId: 'agent_abc123',
  messages: [{ role: 'user', content: 'What is the capital of Kenya?' }],
});
 
console.log(result.response);
console.log(result.sessionId); // reuse to continue the conversation

for await (const event of client.agents.stream({
  agentId: 'agent_abc123',
  messages: [{ role: 'user', content: 'Write me a poem about AI.' }],
})) {
  if (event.type === 'token')     process.stdout.write(event.content ?? '');
  if (event.type === 'toolStart') console.log(`\n[tool: ${event.toolName}]`);
  if (event.type === 'final')     console.log('\nDone!');
}

// Create
const { data: session } = await client.sessions.create({
  agentId: 'agent_abc123',
  initiator: '0xUSER',
  title: 'Research session',
  source: 'web', // optional: 'web' | 'cli' — origin used for UI filtering
});
 
// List
const { data: agentSessions } = await client.sessions.listByAgent('agent_abc123');
const { data: userSessions } = await client.sessions.listByUser('0xUSER');
 
// Get full session (history, tasks, spaces)
const { data: full } = await client.sessions.getFull(session.sessionId);

// Create
const { data: task } = await client.tasks.create({
  title: 'Daily briefing',
  description: 'Summarize overnight tech news.',
  agentId: 'agent_abc123',
  sessionId: 'session_xyz',
  createdBy: '0xUSER',
  createdByType: 'user',
  executionMode: 'single',
  cronExpression: '0 8 * * 1-5',
  isRecurring: true,
});
 
// Execute / cancel
await client.tasks.execute(task.taskId);
await client.tasks.cancel(task.taskId);
 
// Stream progress
for await (const event of client.tasks.stream(task.taskId)) {
  console.log(event.type, event.message ?? '');
}

// Create
const workflow = await client.workflows.create({
  name: 'Summarize and Report',
  ownerId: '0xUSER',
  ownerType: 'user',
  definition: {
    nodes: [
      { id: 'input', type: 'input' },
      { id: 'process', type: 'agent_processor', config: { agentId: 'agent_abc123' } },
      { id: 'output', type: 'output' },
    ],
    edges: [
      { id: 'e1', source: 'input', target: 'process' },
      { id: 'e2', source: 'process', target: 'output' },
    ],
  },
});
 
// Node types: tool | input | output | condition | transform | loop | agent_processor | human_approval
 
// List / update / delete
const workflows = await client.workflows.list('0xUSER', 'user');
await client.workflows.update(workflow.workflowId, { name: 'Updated name' });
await client.workflows.delete(workflow.workflowId);
 
// Execute and stream
const execution = await client.workflows.execute(workflow.workflowId, {
  inputData: { url: 'https://example.com' },
});
 
for await (const event of client.workflows.stream(workflow.workflowId, execution.executionId)) {
  console.log(event.type, event.payload);
}
 
// Manage executions
const exec    = await client.workflows.getExecution(workflow.workflowId, execution.executionId);
const history = await client.workflows.listExecutions(workflow.workflowId, 10);
await client.workflows.cancelExecution(workflow.workflowId, execution.executionId);
 
// Human approval
await client.workflows.approveExecution(workflow.workflowId, execution.executionId, {
  approvalToken: execution.approvalToken,
  approvalData: { approved: true },
});
await client.workflows.rejectExecution(workflow.workflowId, execution.executionId, {
  approvalToken: execution.approvalToken,
  reason: 'Not ready',
});

// List
const { data: tools } = await client.tools.list();
const { data: agentTools } = await client.tools.list({ agentId: 'agent_abc123' });
const { data: statics } = await client.tools.listStatic();
 
// Create
const { data: tool } = await client.tools.create({
  name: 'slack_notify',
  displayName: 'Slack Notify',
  description: 'Send a message to a Slack channel',
  schema: {
    type: 'object',
    properties: {
      channel: { type: 'string' },
      message: { type: 'string' },
    },
    required: ['channel', 'message'],
  },
  visibility: 'private',
});
 
// Store an API key for a tool
await client.toolKeys.create({
  toolId: tool.toolId,
  ownerId: '0xUSER',
  ownerType: 'user',
  keyName: 'SLACK_TOKEN',
  value: 'xoxb-your-slack-token',
});
 
// Grant permission to an agent
await client.toolPermissions.grant({
  toolId: tool.toolId,
  subjectId: 'agent_abc123',
  subjectType: 'agent',
  permission: 'execute',
});

// List servers for an owner
const { servers } = await client.mcp.listServers('0xUSER', 'user');
 
// Create and connect
const server = await client.mcp.createServer({
  name: 'GitHub Tools',
  connectionType: 'sse',
  connectionConfig: { url: 'https://mcp.example.com/sse' },
  ownerId: '0xUSER',
  ownerType: 'user',
});
 
await client.mcp.connect(server.serverId);
const { toolsDiscovered } = await client.mcp.sync(server.serverId);
 
// Inspect
const { tools } = await client.mcp.listTools(server.serverId);
const { tools: allTools } = await client.mcp.listToolsByOwner('0xUSER', 'user');
const status = await client.mcp.getServerStatus(server.serverId);
 
// Resources and prompts
const { resources } = await client.mcp.listResources(server.serverId);
const resource = await client.mcp.readResource(server.serverId, 'file:///README.md');
const { prompts } = await client.mcp.listPrompts(server.serverId);
const rendered = await client.mcp.getPrompt(server.serverId, 'summarize', { language: 'en' });
 
// Update / disconnect / delete
await client.mcp.updateServer(server.serverId, { isPublic: true });
await client.mcp.disconnect(server.serverId);
await client.mcp.deleteServer(server.serverId);
 
// Browse public servers
const { servers: marketplace } = await client.mcp.getMarketplace();

// Store
const { data: mem } = await client.memory.create({
  agentId: 'agent_abc123',
  memoryType: 'semantic',
  content: 'User prefers bullet-point responses.',
  summary: 'Formatting preference',  // required
  tags: ['preferences'],
});
 
// Retrieve by semantic similarity
const { data: relevant } = await client.memory.retrieve(
  'agent_abc123',
  'user formatting preferences',
  5, // limit
);
 
// List all
const { data: all } = await client.memory.list('agent_abc123', { type: 'semantic' });
 
// Update / delete
await client.memory.update(mem.memoryId, { importanceScore: 0.9 });
await client.memory.delete(mem.memoryId);

// Create
const wallet = await client.wallets.create({
  agentId: 'agent_abc123',
  walletType: 'eoa',
  label: 'main',
});
 
// Check balance
const balance = await client.wallets.balance(wallet.id);
console.log('USDC:', balance.usdc);
 
// Transfer
await client.wallets.transfer(wallet.id, {
  toAddress: '0xRecipientAddress',
  amount: '1.5',
  tokenSymbol: 'USDC',
});
 
// Get primary wallet
const primary = await client.wallets.primary('agent_abc123');
 
// x402 payment fetch
const response = await client.wallets.x402Fetch('agent_abc123', {
  url: 'https://paid-api.example.com/data',
  method: 'GET',
});

const identity = new CommonsClient({
  identityToken: process.env.COMMONS_IDENTITY_TOKEN,
});
 
const { data: project } = await identity.developer.createProject({
  workspaceId: 'workspace_abc123',
  name: 'Production API',
  environment: 'production',
});
 
const { data: created } = await identity.developer.createApiKey(project.id, {
  name: 'Backend service',
  scopes: ['agents:read', 'agents:run'],
  expiresAt: '2027-01-01T00:00:00Z',
});
 
console.log(created.key); // returned only once
 
const { data: keys } = await identity.developer.listApiKeys(project.id);
await identity.developer.revokeApiKey(keys[0].id);

// Resolve the principal represented by the current API key.
const { principalId, principalType } = await client.auth.me();

// Get an agent's A2A card
const card = await client.a2a.getAgentCard('agent_abc123');
 
// Send a task to an agent
const task = await client.a2a.sendTask('agent_abc123', {
  message: {
    role: 'user',
    parts: [{ type: 'text', text: 'Summarize this document...' }],
  },
});
 
// Stream task updates
for await (const event of client.a2a.stream('agent_abc123', task.id)) {
  console.log(event.type, event.content);
}
 
// Get status / cancel / list
const status = await client.a2a.getTask('agent_abc123', task.id);
await client.a2a.cancelTask('agent_abc123', task.id);
const { tasks } = await client.a2a.listTasks('agent_abc123', 20);

// List
const { data: skills } = await client.skills.list({ isPublic: true });
const { data: skill }  = await client.skills.get('summarize-content');
const { data: index }  = await client.skills.getIndex();
 
// Create
const { data: newSkill } = await client.skills.create({
  slug: 'my-skill',
  name: 'My Skill',
  description: 'Does something useful',
  instructions: 'When asked to...',
  tools: ['tool_abc'],
  isPublic: false,
});
 
// Update / delete
await client.skills.update('my-skill', { isPublic: true });
await client.skills.delete('my-skill');

const { data, grouped } = await client.models.list();
// grouped: { openai: [...], anthropic: [...], google: [...], ... }

// Agent usage with optional date range
const { data: usage } = await client.usage.getAgentUsage('agent_abc123', {
  from: '2025-01-01T00:00:00Z',
  to:   '2025-01-31T23:59:59Z',
});
console.log(usage.totalCostUsd, usage.totalTokens);
 
// Session usage
const { data: sessionUsage } = await client.usage.getSessionUsage('session_xyz');

import { CommonsClient, CommonsError } from '@agent-commons/sdk';
 
try {
  await client.run.once({ agentId: 'bad-id', messages: [...] });
} catch (error) {
  if (error instanceof CommonsError) {
    console.error(`${error.status}: ${error.message}`);
    console.error('Details:', error.data);
  }
}

import { CommonsClient } from '@agent-commons/sdk';
 
const client = new CommonsClient({
  apiKey: process.env.AGENT_COMMONS_API_KEY!,
});
 
async function main() {
  // 1. Create a research agent
  const { data: agent } = await client.agents.create({
    name: 'Daily Researcher',
    instructions: `You are a research assistant. When given a topic:
      1. Search the web for the latest information
      2. Summarize in 5 clear bullet points
      3. Include sources`,
    modelProvider: 'anthropic',
    modelId: 'claude-sonnet-4-6',
    temperature: 0.2,
  });
 
  // 2. Schedule it to run every morning
  await client.tasks.create({
    title: 'Daily AI news briefing',
    description: 'Research the top AI developments from the past 24 hours.',
    agentId: agent.agentId,
    sessionId: 'session_placeholder',
    createdBy: '0xUSER',
    createdByType: 'user',
    executionMode: 'single',
    cronExpression: '0 8 * * *',
    isRecurring: true,
  });
 
  // 3. Run it once now to test
  for await (const event of client.agents.stream({
    agentId: agent.agentId,
    messages: [{ role: 'user', content: 'Top AI news today?' }],
  })) {
    if (event.type === 'token') process.stdout.write(event.content ?? '');
    if (event.type === 'final') console.log('\n✓ Done');
  }
}
 
main();