TypeScript SDK

npm install @agent-commons/sdk

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

import { CommonsError } from '@agent-commons/sdk';
 
try {
  await commons.agents.get('agent_missing');
} catch (error) {
  if (error instanceof CommonsError && error.status === 404) {
    // …
  }
}

const result = await commons.request<{ data: unknown }>(
  'POST',
  '/v1/some/new/route',
  { hello: 'world' },
);

const { data: agent } = await commons.agents.create({
  name: 'Research Bot',
  instructions: 'You research topics and answer with sources.',
  modelProvider: 'anthropic',
  modelId: 'claude-sonnet-4-6',
  temperature: 0.3,
});
 
const { data: agents } = await commons.agents.list();
await commons.agents.update(agent.agentId, { temperature: 0.1 });

const result = await commons.run.once({
  agentId,
  messages: [{ role: 'user', content: 'Summarise this quarter.' }],
  sessionId,
});

for await (const event of commons.agents.stream({
  agentId,
  messages: [{ role: 'user', content: 'Research the EU AI Act.' }],
  provenance: { mode: 'metadata' },
})) {
  switch (event.type) {
    case 'token':
      process.stdout.write(event.content ?? '');
      break;
    case 'toolStart':
      console.log(`\n→ ${event.toolName}`);
      break;
    case 'final':
      console.log(`\nsession ${event.sessionId}`);
      break;
    case 'error':
      throw new Error(event.message);
  }
}

for await (const event of commons.agents.stream({
  agentId,
  messages,
  cliTools: [
    {
      name: 'readFile',
      description: 'Read a file from the local working directory',
      parameters: {
        type: 'object',
        properties: { path: { type: 'string' } },
        required: ['path'],
      },
    },
  ],
})) {
  if (event.type === 'cli_tool_request') {
    const output = await runLocally(event.toolName!, event.args);
    await commons.agents.submitCliToolResult(event.requestId!, output);
  }
}

const { data: session } = await commons.sessions.create({ agentId, title: 'Q3 research' });
const { data: full } = await commons.sessions.getFull(session.sessionId);
await commons.sessions.rename(session.sessionId, 'Q3 research — final');

const { data: task } = await commons.tasks.create({
  agentId,
  sessionId,
  title: 'Daily briefing',
  description: 'Summarise overnight news.',
  executionMode: 'single',
  cronExpression: '0 8 * * 1-5',
  isRecurring: true,
  createdBy: userId,
  createdByType: 'user',
});
 
for await (const event of commons.tasks.stream(task.taskId)) {
  console.log(event.type, event.status);
}

const { data: workflow } = await commons.workflows.create({
  name: 'Summarise a URL',
  definition: {
    nodes: [
      { id: 'in', type: 'input' },
      { id: 'fetch', type: 'tool', toolName: 'webSearch' },
      { id: 'write', type: 'agent_processor', agentId },
      { id: 'out', type: 'output' },
    ],
    edges: [
      { id: 'e1', source: 'in', target: 'fetch' },
      { id: 'e2', source: 'fetch', target: 'write' },
      { id: 'e3', source: 'write', target: 'out' },
    ],
  },
});
 
const { data: execution } = await commons.workflows.execute(workflow.workflowId, {
  inputData: { url: 'https://example.com' },
});
 
for await (const event of commons.workflows.stream(workflow.workflowId, execution.executionId)) {
  console.log(event.type, event.stage);
}

import { listWorkflowTemplates, buildWorkflowTemplate } from '@agent-commons/sdk';

const { data: tool } = await commons.tools.create({
  name: 'weather_lookup',
  description: 'Get the current weather for a city',
  schema: {
    type: 'object',
    properties: { city: { type: 'string' } },
    required: ['city'],
  },
  apiSpec: {
    baseUrl: 'https://api.example.com',
    path: '/weather',
    method: 'GET',
    queryParams: { q: '{{city}}' },
    authType: 'api-key',
    authKeyName: 'X-API-Key',
  },
});
 
await commons.agents.addTool(agentId, { toolId: tool.toolId });

const server = await commons.mcp.createServer({
  name: 'Filesystem',
  connectionType: 'stdio',
  connectionConfig: {
    command: 'npx',
    args: ['@modelcontextprotocol/server-filesystem', '/Users/me/projects'],
  },
  ownerId: userId,
  ownerType: 'user',
});
 
await commons.mcp.connect(server.mcpServerId);
await commons.mcp.sync(server.mcpServerId);
const { data: tools } = await commons.mcp.listTools(server.mcpServerId);

const { data: skill } = await commons.skills.create({
  slug: 'weekly-report',
  name: 'Weekly report',
  description: 'Produce the standard weekly status report',
  instructions: '1. Pull last week…',
  tools: ['webSearch', 'createDocumentFile'],
  triggers: ['weekly report', 'status update'],
});
 
await commons.skills.setAgentAvailability(skill.skillId, agentId, true);

await commons.memory.create({
  agentId,
  content: 'The user prefers concise bullet-point answers.',
  memoryType: 'semantic',
});
 
const { data: hits } = await commons.memory.retrieve(
  agentId,
  'formatting preferences',
  5,
);

const { data: space } = await commons.knowledge.createSpace({ name: 'Handbook' });
 
await commons.knowledge.createDocument(space.spaceId, {
  path: 'onboarding/day-one.md',
  title: 'Day one',
  content: '# Day one\n…',
});
 
const { data: results } = await commons.knowledge.search({ query: 'expense policy' });

const { data: uploaded } = await commons.files.upload(
  [{ name: 'report.pdf', data: fileBlob }],
  { agentId, sessionId },
);
 
const { data: text } = await commons.files.content(uploaded[0].fileId, { maxChars: 20_000 });

await commons.agents.wakeComputer(agentId);
 
const { data: run } = await commons.agents.execComputer(agentId, {
  command: 'python analyse.py',
  cwd: '/workspace',
  timeoutSeconds: 300,
});
 
await commons.agents.sleepComputer(agentId);

const { data: release } = await commons.arcade.publish(agentId, projectId);

const { data: providers } = await commons.oauth.listProviders();
 
const flow = await commons.oauth.connect({
  providerKey: 'google',
  scopes: ['https://www.googleapis.com/auth/gmail.send'],
});
// send the user to flow.authorizationUrl
 
const { data: connections } = await commons.oauth.listConnections();

const card = await commons.a2a.getAgentCard(agentId);
 
const task = await commons.a2a.sendTask(agentId, {
  message: { role: 'user', parts: [{ type: 'text', text: 'Research quantum computing' }] },
});
 
for await (const event of commons.a2a.stream(agentId, task.id)) {
  console.log(event.type);
}

const { data: wallet } = await commons.wallets.primary(agentId);
const { data: balance } = await commons.wallets.balance(wallet.walletId);
 
const paid = await commons.wallets.x402Fetch(agentId, {
  url: 'https://paid.example.com/dataset',
  method: 'GET',
});

const { data: report } = await commons.provenance.session(sessionId);
const { data: bundle } = await commons.provenance.bundle(traceId);

import type { Agent, StreamEvent, WorkflowNodeType } from '@agent-commons/sdk';