> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wassist.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create, update, and manage AI agents with the SDK

The Agents resource provides complete control over your AI agents—from creation to deployment.

## Overview

```typescript theme={null}
client.agents.list(params?)      // List all agents
client.agents.get(id)            // Get a single agent
client.agents.create(input)      // Create a new agent
client.agents.update(id, input)  // Update an agent
client.agents.delete(id)         // Delete an agent
client.agents.deploy(id, input)  // Deploy to WhatsApp
client.agents.share(id, input)   // Share with another user
client.agents.unshare(id, input) // Remove sharing
```

## List Agents

Retrieve all agents you have access to.

```typescript theme={null}
const { data: agents, totalCount, hasMore } = await client.agents.list({
  offset: 0,
  limit: 20,
});

console.log(`Found ${totalCount} agents`);
agents.forEach(agent => {
  console.log(`- ${agent.name} (${agent.id})`);
});
```

### Parameters

| Parameter | Type     | Description                           |
| --------- | -------- | ------------------------------------- |
| `offset`  | `number` | Number of items to skip (default: 0)  |
| `limit`   | `number` | Maximum items to return (default: 20) |

### Response

```typescript theme={null}
interface PaginatedResponse<Agent> {
  data: Agent[];
  totalCount: number;
  hasMore: boolean;
}
```

## Get Agent

Retrieve a single agent with all nested resources.

```typescript theme={null}
const agent = await client.agents.get('agent-uuid');

console.log(agent.name);
console.log(agent.systemPrompt);
console.log(`Has ${agent.tools.length} tools`);
console.log(`Has ${agent.documents.length} documents`);
```

### Response Type

```typescript theme={null}
interface Agent {
  id: UUID;
  name: string;
  description: string;
  systemPrompt: string;
  firstMessage: string;
  profilePicture: ImageInfo | null;
  icebreakers: string[];
  
  // Nested resources
  tools: AgentTool[];
  documents: AgentDocument[];
  memoryKeys: AgentMemoryKey[];
  wakeUpConfigs: AgentWakeUpConfig[];
  outboundTriggers: AgentOutboundTrigger[];
  websiteTools: AgentWebsiteTool[];
  imageGenerateTools: AgentImageGenerateTool[];
  handoffTools: AgentHandoffTool[];
  mcpConfigs: AgentMcpConfig[];
  
  // Configs
  paywallConfig: AgentPaywallConfig | null;
  adConfig: AgentAdConfig | null;
  creditSettings: AgentCreditSettings | null;
  voiceCallConfig: AgentVoiceCallConfig | null;
  
  // Metadata
  owner: PublicUser | null;
  sharings: PublicUser[];
  phoneNumbers: AgentWhatsAppPhoneNumber[];
  totalMessages: number;
  totalSessions: number;
  connectUrl: string;
  ownerActive: boolean;
  
  createdAt: string;
  updatedAt: string;
}
```

## Create Agent

Create a new agent with minimal configuration.

```typescript theme={null}
const agent = await client.agents.create({
  name: 'Customer Support Bot',
});

console.log(`Created agent: ${agent.id}`);
```

After creation, use `update()` to add configuration, or use the onboarding methods for AI-assisted setup.

### Input

| Field  | Type     | Required | Description        |
| ------ | -------- | -------- | ------------------ |
| `name` | `string` | Yes      | Agent display name |

## Update Agent

Update an agent and all its nested resources. Pass the full configuration—nested resources are fully replaced.

```typescript theme={null}
const updated = await client.agents.update(agentId, {
  name: 'Updated Name',
  systemPrompt: 'You are a helpful assistant...',
  firstMessage: 'Hello! How can I help you today?',
  icebreakers: ['What can you help me with?', 'Tell me about your services'],
  
  // Update tools (replaces all existing tools)
  tools: [
    {
      name: 'check_order',
      description: 'Look up order status',
      apiSchema: { /* ... */ },
      active: true,
    },
  ],
  
  // Update paywall config
  paywallConfig: {
    messageLimit: 10,
    paywallAction: 'purchase_link',
    paywallUrl: 'https://example.com/upgrade',
    ctaButtonText: 'Upgrade Now',
  },
});
```

### Updating with File Uploads

When updating with files (profile picture or documents), the SDK automatically uses FormData:

```typescript theme={null}
const fileInput = document.getElementById('profile-pic') as HTMLInputElement;

await client.agents.update(agentId, {
  profilePicture: fileInput.files[0],
  documents: [
    {
      name: 'Product Manual',
      file: documentFile,
    },
  ],
});
```

### Available Update Fields

<AccordionGroup>
  <Accordion title="Basic Fields" icon="sliders">
    ```typescript theme={null}
    {
      name?: string;
      description?: string;
      systemPrompt?: string;
      firstMessage?: string;
      profilePicture?: File | null;
      icebreakers?: string[];
    }
    ```
  </Accordion>

  <Accordion title="Tools" icon="plug">
    ```typescript theme={null}
    {
      tools?: Array<{
        id?: UUID;              // Include to update existing
        name: string;
        description: string;
        apiSchema: Record<string, unknown>;
        active?: boolean;
        creditCost?: number;
      }>;
    }
    ```
  </Accordion>

  <Accordion title="Documents" icon="file">
    ```typescript theme={null}
    {
      documents?: Array<{
        id?: UUID;
        name: string;
        file: File;
      }>;
    }
    ```
  </Accordion>

  <Accordion title="Memory Keys" icon="brain">
    ```typescript theme={null}
    {
      memoryKeys?: Array<{
        id?: UUID;
        key: string;
        type: 'string' | 'number' | 'boolean' | 'json';
        initialValue: string;
        whenToUpdate: string;
      }>;
    }
    ```
  </Accordion>

  <Accordion title="Paywall Config" icon="lock">
    ```typescript theme={null}
    {
      paywallConfig?: {
        messageLimit?: number | null;
        paywallAction?: 'none' | 'purchase_link' | 'subscribe' | 'terminal';
        paywallUrl?: string | null;
        ctaButtonText?: string;
        terminalStateMessage?: string;
        subscriptionPricePerMonth?: number | null;
      } | null;
    }
    ```
  </Accordion>

  <Accordion title="Credit Settings" icon="coins">
    ```typescript theme={null}
    {
      creditSettings?: {
        initialCredits?: number;
        creditGrantPassword?: string | null;
        creditGrantAmount?: number;
      } | null;
    }
    ```
  </Accordion>
</AccordionGroup>

## Delete Agent

Soft-delete an agent.

```typescript theme={null}
await client.agents.delete(agentId);
console.log('Agent deleted');
```

## Deploy Agent

Deploy an agent to a WhatsApp phone number.

```typescript theme={null}
const deployed = await client.agents.deploy(agentId, {
  phoneNumberId: 'phone-number-uuid',
});

console.log(`Deployed to: ${deployed.phoneNumbers[0].phoneNumber}`);
```

### Input

| Field           | Type   | Description                   |
| --------------- | ------ | ----------------------------- |
| `phoneNumberId` | `UUID` | The phone number to deploy to |

## Share Agent

Share an agent with another Wassist user.

```typescript theme={null}
await client.agents.share(agentId, {
  userPhoneNumber: '+1234567890',
});
```

### Unshare

Remove sharing with a user.

```typescript theme={null}
await client.agents.unshare(agentId, {
  userPhoneNumber: '+1234567890',
});
```

## Complete Example

```typescript theme={null}
import { createWassistClient } from '@wassist/sdk';

const client = createWassistClient({
  baseUrl: 'https://backend.wassist.app/api/v1/',
  authToken: process.env.WASSIST_TOKEN,
});

async function setupCustomerSupportAgent() {
  // Create a basic agent
  const agent = await client.agents.create({
    name: 'Support Bot',
  });
  
  // Configure it fully
  await client.agents.update(agent.id, {
    systemPrompt: `You are a helpful customer support agent for Acme Inc.
    
    Guidelines:
    - Be friendly and professional
    - Answer questions about our products
    - Help with order issues
    - Escalate complex problems to human support
    
    Our return policy: 30 days, original packaging required.
    Support hours: Monday-Friday 9am-5pm EST.`,
    
    firstMessage: "Hi there! 👋 I'm the Acme support assistant. How can I help you today?",
    
    icebreakers: [
      "Track my order",
      "Return an item",
      "Product question",
    ],
    
    tools: [
      {
        name: 'lookup_order',
        description: 'Look up order status by order number (format: ACM-XXXXX)',
        apiSchema: {
          type: 'object',
          properties: {
            endpoint: { type: 'string', const: 'https://api.acme.com/orders/{order_id}' },
            method: { type: 'string', const: 'GET' },
            parameters: {
              type: 'object',
              properties: {
                order_id: { type: 'string', description: 'Order number' }
              },
              required: ['order_id']
            }
          }
        },
        active: true,
        creditCost: 0,
      },
    ],
    
    paywallConfig: {
      messageLimit: 20,
      paywallAction: 'terminal',
      terminalStateMessage: 'Thanks for chatting! For more help, email support@acme.com',
    },
  });
  
  // Deploy to a phone number
  await client.agents.deploy(agent.id, {
    phoneNumberId: 'your-phone-number-uuid',
  });
  
  console.log(`Agent deployed! URL: ${agent.connectUrl}`);
}
```

## Related

<CardGroup cols={2}>
  <Card title="Conversations" icon="comments" href="/sdk/conversations">
    Manage conversations with your agents.
  </Card>

  <Card title="Concepts: Agents" icon="lightbulb" href="/concepts#agents">
    Understand how agents work.
  </Card>
</CardGroup>