Agents API

Deploy and manage autonomous agents that can execute functions, run workflows, and make intelligent business decisions. Agents are AI-powered entities that operate with specific roles and capabilities.

Overview

Business agents are autonomous AI entities that:

Execute functions and workflows independently
Make intelligent decisions based on context
Have specific roles and capabilities (CFO, CMO, CTO, SWE, SDR, BDR)
Can be assigned tasks and delegate work
Learn and adapt from interactions

import { createBusinessApi } from 'business-as-code'

const api = createBusinessApi({
  apiKey: process.env.APIS_DO_KEY,
})

// Create an agent
const agent = await api.agents.create({
  name: 'Sarah - Sales Development Rep',
  role: 'sdr',
  functions: ['qualify-lead', 'schedule-demo', 'send-followup'],
  capabilities: ['lead-qualification', 'email-outreach', 'crm-management'],
})

// Assign a task
const task = await api.agents.assign(agent.id, {
  type: 'qualify-lead',
  lead: { id: 'lead-123', name: 'Acme Corp' },
})

create()

Create a new autonomous agent with specific role and capabilities.

Signature

create(
  agent: Omit<BusinessAgent, 'id'>
): Promise<BusinessAgent>

Parameters

Parameter	Type	Required	Description
agent	object	Yes	Agent definition without ID

Returns

Promise that resolves to the created BusinessAgent with generated ID.

Agent Roles

Role	Description	Common Use Cases
cfo	Chief Financial Officer	Financial analysis, budgeting, forecasting
cmo	Chief Marketing Officer	Campaign management, content strategy, analytics
cto	Chief Technology Officer	Architecture decisions, technical planning
swe	Software Engineer	Code review, testing, deployment
sdr	Sales Development Rep	Lead qualification, outreach, scheduling
bdr	Business Development Rep	Partnership development, deal sourcing
custom	Custom role	Specialized business functions

Example: Sales Development Rep

const sdrAgent = await api.agents.create({
  name: 'Alex - SDR Agent',
  description: 'Autonomous SDR for inbound lead qualification',
  role: 'sdr',

  functions: ['qualify-lead', 'check-budget', 'assess-timeline', 'schedule-demo', 'send-followup-email', 'update-crm'],

  workflows: ['inbound-lead-qualification', 'demo-scheduling', 'followup-sequence'],

  capabilities: ['lead-scoring', 'email-composition', 'calendar-management', 'crm-updates', 'budget-assessment', 'timeline-qualification'],

  config: {
    timezone: 'America/New_York',
    workingHours: {
      start: '09:00',
      end: '17:00',
      days: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
    },
    personality: {
      tone: 'professional',
      style: 'consultative',
    },
    rules: ['Only qualify leads with budget > $10k', 'Schedule demos within 48 hours', 'Follow up within 24 hours of demo request'],
  },
})

console.log('Created SDR agent:', sdrAgent.id)

Example: Chief Marketing Officer

const cmoAgent = await api.agents.create({
  name: 'Morgan - CMO Agent',
  description: 'Autonomous CMO for marketing strategy and execution',
  role: 'cmo',

  functions: [
    'analyze-campaign-performance',
    'optimize-ad-spend',
    'generate-content-ideas',
    'schedule-social-posts',
    'analyze-audience-insights',
    'calculate-marketing-roi',
  ],

  workflows: ['campaign-planning', 'content-calendar-generation', 'performance-reporting', 'budget-optimization'],

  capabilities: ['campaign-analytics', 'content-strategy', 'audience-segmentation', 'budget-allocation', 'performance-optimization', 'trend-analysis'],

  config: {
    platforms: ['facebook', 'instagram', 'linkedin', 'twitter'],
    budgetAuthority: 50000,
    reportingFrequency: 'weekly',
    decisionCriteria: {
      minROI: 3.0,
      maxCPL: 100,
      targetConversionRate: 0.05,
    },
  },
})

Example: Software Engineer

const sweAgent = await api.agents.create({
  name: 'Taylor - SWE Agent',
  description: 'Autonomous software engineer for code review and testing',
  role: 'swe',

  functions: ['review-code', 'run-tests', 'analyze-performance', 'suggest-improvements', 'generate-documentation', 'check-security'],

  workflows: ['code-review-workflow', 'automated-testing', 'deployment-validation', 'documentation-generation'],

  capabilities: ['code-analysis', 'test-generation', 'security-scanning', 'performance-profiling', 'documentation-writing', 'best-practices-validation'],

  config: {
    languages: ['typescript', 'python', 'go'],
    frameworks: ['react', 'node', 'fastapi'],
    reviewCriteria: {
      maxComplexity: 10,
      minCoverage: 80,
      requireTests: true,
      checkSecurity: true,
    },
  },
})

Example: Chief Financial Officer

const cfoAgent = await api.agents.create({
  name: 'Jordan - CFO Agent',
  description: 'Autonomous CFO for financial planning and analysis',
  role: 'cfo',

  functions: ['forecast-revenue', 'analyze-expenses', 'calculate-burn-rate', 'project-runway', 'optimize-pricing', 'generate-financial-report'],

  workflows: ['monthly-close', 'quarterly-planning', 'annual-budget', 'cashflow-analysis'],

  capabilities: ['financial-modeling', 'variance-analysis', 'scenario-planning', 'cash-management', 'pricing-strategy', 'risk-assessment'],

  config: {
    reportingCurrency: 'USD',
    fiscalYearStart: 'January',
    approvalAuthority: {
      expenses: 10000,
      investments: 50000,
    },
    kpis: ['monthly-recurring-revenue', 'cash-burn-rate', 'runway-months', 'gross-margin', 'customer-acquisition-cost'],
  },
})

list()

Retrieve a list of all agents.

Signature

list(): Promise<BusinessAgent[]>

Returns

Promise that resolves to an array of BusinessAgent objects.

Example

const agents = await api.agents.list()

console.log(`Found ${agents.length} agents`)

agents.forEach((agent) => {
  console.log(`- ${agent.name} (${agent.role})`)
  console.log(`  Functions: ${agent.functions.length}`)
  console.log(`  Capabilities: ${agent.capabilities?.join(', ')}`)
})

Filter by Role

const agents = await api.agents.list()

// Get all SDR agents
const sdrAgents = agents.filter((a) => a.role === 'sdr')

// Get all agents with specific capability
const leadQualifiers = agents.filter((a) => a.capabilities?.includes('lead-qualification'))

get()

Retrieve a specific agent by ID.

Signature

get(id: string): Promise<BusinessAgent>

Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the agent

Returns

Promise that resolves to a BusinessAgent object.

Example

const agent = await api.agents.get('agent-abc123')

console.log('Agent:', agent.name)
console.log('Role:', agent.role)
console.log('Functions:', agent.functions)
console.log('Capabilities:', agent.capabilities)

assign()

Assign a task to an agent for autonomous execution.

Signature

assign(
  agentId: string,
  task: any
): Promise<{ taskId: string }>

Parameters

Parameter	Type	Required	Description
agentId	string	Yes	ID of the agent to assign the task to
task	any	Yes	Task data and instructions

Returns

Promise that resolves to an object containing the taskId.

Example

const task = await api.agents.assign('agent-sdr-123', {
  type: 'qualify-lead',
  priority: 'high',
  data: {
    lead: {
      id: 'lead-456',
      name: 'Acme Corporation',
      email: '[email protected]',
      phone: '+1-555-0100',
      website: 'https://acme.com',
    },
    context: {
      source: 'website-form',
      campaign: 'product-launch-2024',
      interests: ['enterprise-plan', 'api-access'],
    },
  },
  instructions: ['Assess budget and timeline', 'Determine decision makers', 'Schedule demo if qualified', 'Update CRM with notes'],
  deadline: '2024-10-30T17:00:00Z',
})

console.log('Task assigned:', task.taskId)

Task Types by Role

SDR Tasks:

// Lead qualification
await api.agents.assign(sdrAgent.id, {
  type: 'qualify-lead',
  data: { lead },
})

// Demo scheduling
await api.agents.assign(sdrAgent.id, {
  type: 'schedule-demo',
  data: { lead, availability },
})

// Follow-up sequence
await api.agents.assign(sdrAgent.id, {
  type: 'send-followup',
  data: { lead, sequence: 'trial-nurture' },
})

CMO Tasks:

// Campaign analysis
await api.agents.assign(cmoAgent.id, {
  type: 'analyze-campaign',
  data: { campaignId: 'camp-123' },
})

// Content planning
await api.agents.assign(cmoAgent.id, {
  type: 'plan-content',
  data: { topic: 'product-launch', channels: ['blog', 'social'] },
})

// Budget optimization
await api.agents.assign(cmoAgent.id, {
  type: 'optimize-budget',
  data: { currentSpend, targets },
})

SWE Tasks:

// Code review
await api.agents.assign(sweAgent.id, {
  type: 'review-code',
  data: { pullRequest: 123 },
})

// Run tests
await api.agents.assign(sweAgent.id, {
  type: 'run-tests',
  data: { branch: 'feature/new-api' },
})

CFO Tasks:

// Financial forecast
await api.agents.assign(cfoAgent.id, {
  type: 'create-forecast',
  data: { period: 'Q4-2024' },
})

// Expense analysis
await api.agents.assign(cfoAgent.id, {
  type: 'analyze-expenses',
  data: { department: 'engineering', month: 'October' },
})

Agent Response Types

interface BusinessAgent {
  id: string
  name: string
  description?: string
  role: 'cfo' | 'cmo' | 'cto' | 'swe' | 'sdr' | 'bdr' | 'custom'
  functions: string[] | BusinessFunction[]
  workflows?: string[] | BusinessWorkflow[]
  capabilities?: string[]
  config?: Record<string, any>
}

Complete Examples

Lead Qualification System

// Create SDR agent
const sdrAgent = await api.agents.create({
  name: 'Lead Qualifier',
  role: 'sdr',
  functions: ['qualify-lead', 'schedule-demo', 'update-crm'],
  capabilities: ['lead-scoring', 'calendar-management'],
  config: {
    qualificationCriteria: {
      minBudget: 10000,
      maxTimeToClose: 90,
      requiredAuthority: true,
    },
  },
})

// Assign lead qualification task
const qualifyTask = await api.agents.assign(sdrAgent.id, {
  type: 'qualify-lead',
  data: {
    lead: {
      id: 'lead-789',
      name: 'TechCorp',
      contact: '[email protected]',
    },
  },
})

// Check task status (workflow execution)
const status = await api.workflows.status(qualifyTask.taskId)

if (status.status === 'completed' && status.result.qualified) {
  // Lead is qualified, schedule demo
  const demoTask = await api.agents.assign(sdrAgent.id, {
    type: 'schedule-demo',
    data: {
      lead: status.result.lead,
      proposedTimes: ['2024-10-28T14:00', '2024-10-29T10:00'],
    },
  })
}

Marketing Campaign Manager

// Create CMO agent
const cmoAgent = await api.agents.create({
  name: 'Campaign Manager',
  role: 'cmo',
  functions: ['create-campaign', 'analyze-performance', 'optimize-targeting', 'generate-report'],
  capabilities: ['audience-segmentation', 'performance-analytics', 'content-optimization'],
  config: {
    platforms: ['google-ads', 'facebook-ads', 'linkedin-ads'],
    budgetLimit: 50000,
    targetROI: 3.0,
  },
})

// Launch campaign
const campaignTask = await api.agents.assign(cmoAgent.id, {
  type: 'launch-campaign',
  data: {
    name: 'Q4 Product Launch',
    budget: 30000,
    duration: 30,
    objectives: ['awareness', 'lead-generation'],
    targetAudience: {
      industries: ['technology', 'finance'],
      companySize: ['50-200', '200-1000'],
      jobTitles: ['CTO', 'VP Engineering', 'Director of IT'],
    },
  },
})

// Daily optimization
const optimizeTask = await api.agents.assign(cmoAgent.id, {
  type: 'optimize-campaign',
  data: {
    campaignId: 'camp-456',
    metrics: ['cpl', 'ctr', 'conversion-rate'],
    adjustBudget: true,
    adjustTargeting: true,
  },
})

Automated Code Review

// Create SWE agent
const sweAgent = await api.agents.create({
  name: 'Code Reviewer',
  role: 'swe',
  functions: ['review-code', 'run-tests', 'check-security', 'suggest-improvements'],
  capabilities: ['static-analysis', 'security-scanning', 'performance-profiling', 'best-practices'],
  config: {
    languages: ['typescript', 'python'],
    standards: ['airbnb', 'google'],
    autoApprove: false,
    requireTests: true,
  },
})

// Review pull request
const reviewTask = await api.agents.assign(sweAgent.id, {
  type: 'review-pr',
  data: {
    repository: 'company/api',
    pullRequest: 123,
    checks: ['code-style', 'test-coverage', 'security-vulnerabilities', 'performance-issues', 'documentation'],
  },
})

// Get review results
const reviewStatus = await api.workflows.status(reviewTask.taskId)

if (reviewStatus.status === 'completed') {
  console.log('Review:', reviewStatus.result)
  // {
  //   approved: false,
  //   issues: [
  //     { type: 'security', severity: 'high', message: 'SQL injection risk' },
  //     { type: 'coverage', severity: 'medium', message: 'Test coverage 65%' }
  //   ],
  //   suggestions: [...]
  // }
}

Best Practices

1. Define Clear Roles

// ✅ Good - specific role and capabilities
const agent = await api.agents.create({
  name: 'Lead Qualification Specialist',
  role: 'sdr',
  capabilities: ['lead-scoring', 'budget-assessment', 'timeline-qualification'],
})

// ❌ Bad - too broad
const agent = await api.agents.create({
  name: 'Do Everything Agent',
  role: 'custom',
  capabilities: ['everything'],
})

2. Provide Context

// ✅ Good - rich context
await api.agents.assign(agent.id, {
  type: 'qualify-lead',
  data: { lead },
  context: {
    previousInteractions: [...],
    campaignData: {...},
    competitorInfo: {...}
  },
  instructions: [
    'Focus on budget and timeline',
    'Be consultative, not pushy'
  ]
})

3. Set Boundaries

// ✅ Good - clear boundaries
const agent = await api.agents.create({
  name: 'Junior SDR',
  role: 'sdr',
  config: {
    approvalRequired: {
      discounts: true,
      customPricing: true,
    },
    maxDealSize: 50000,
    escalateTo: 'senior-sdr-agent',
  },
})

4. Monitor Performance

// Track agent performance
const tasks = await api.agents.list()
const metrics = await api.metrics.list({
  agentId: agent.id,
  type: 'kpi',
})

console.log('Agent Performance:')
console.log('- Tasks completed:', metrics.tasksCompleted)
console.log('- Success rate:', metrics.successRate)
console.log('- Avg completion time:', metrics.avgCompletionTime)

Next Steps

Workflows API - Assign workflows to agents
Functions API - Create functions for agents to execute
Actions API - Execute actions through agents

Agents API

On this page