Agent Management

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.conversationalAi.agents

/**
 * Create a new agent
 */
client.conversationalAi.agents.create(
  request: BodyCreateAgentV1ConvaiAgentsCreatePost,
  requestOptions?: RequestOptions
): HttpResponsePromise<CreateAgentResponseModel>;

/**
 * Get agent configuration
 */
client.conversationalAi.agents.get(
  agent_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAgentResponseModel>;

/**
 * List all agents
 */
client.conversationalAi.agents.list(
  request?: AgentsListRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAgentsPageResponseModel>;

/**
 * Update agent configuration
 */
client.conversationalAi.agents.update(
  agent_id: string,
  request: UpdateAgentRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAgentResponseModel>;

/**
 * Delete an agent
 */
client.conversationalAi.agents.delete(
  agent_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<void>;

/**
 * Duplicate an agent
 */
client.conversationalAi.agents.duplicate(
  agent_id: string,
  request: BodyDuplicateAgentV1ConvaiAgentsAgentIdDuplicatePost,
  requestOptions?: RequestOptions
): HttpResponsePromise<CreateAgentResponseModel>;

interface BodyCreateAgentV1ConvaiAgentsCreatePost {
  /** Agent conversation configuration */
  conversationConfig: ConversationalConfig;
  /** Agent name */
  name?: string;
  /** Platform-specific settings for the agent */
  platformSettings?: AgentPlatformSettingsRequestModel;
  /** Workflow configuration for the agent */
  workflow?: AgentWorkflowRequestModel;
}

/**
 * Platform-specific settings for agents
 */
interface AgentPlatformSettingsRequestModel {
  /** Evaluation settings */
  evaluation?: EvaluationSettings;
  /** Widget configuration */
  widget?: WidgetConfig;
  /** Data collection settings */
  dataCollection?: Record<string, any>;
  /** Conversation initiation overrides */
  overrides?: ConversationInitiationClientDataConfigInput;
  /** Workspace overrides */
  workspaceOverrides?: AgentWorkspaceOverridesInput;
  /** Testing configuration */
  testing?: AgentTestingSettings;
  /** Whether agent is archived */
  archived?: boolean;
  /** Authentication settings */
  auth?: AuthSettings;
  /** Call limits for the agent */
  callLimits?: AgentCallLimits;
  /** Privacy settings */
  privacy?: PrivacyConfig;
}

/**
 * Workflow configuration for agent
 */
interface AgentWorkflowRequestModel {
  /** Workflow edges connecting nodes */
  edges?: Record<string, WorkflowEdgeModelInput>;
  /** Workflow nodes */
  nodes?: Record<string, any>;
  /** Prevent loops in workflow execution */
  preventSubagentLoops?: boolean;
}

interface AgentsListRequest {
  /** Maximum number of items to return per page */
  pageSize?: number;
  /** Search query to filter agents by name or description */
  search?: string;
  /** Filter for archived agents */
  archived?: boolean;
  /** Show only agents owned by the user */
  showOnlyOwnedAgents?: boolean;
  /** Sort direction: "asc" or "desc" */
  sortDirection?: "asc" | "desc";
  /** Field to sort by (e.g., "name", "created_at") */
  sortBy?: string;
  /** Pagination cursor for next page */
  cursor?: string;
}

/**
 * Get agent widget configuration
 */
client.conversationalAi.agents.widget.get(
  agent_id: string,
  request?: WidgetGetRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAgentWidgetResponseModel>;

/**
 * Upload agent avatar
 */
client.conversationalAi.agents.widget.avatar.create(
  agent_id: string,
  request: BodyPostAgentAvatarV1ConvaiAgentsAgentIdAvatarPost,
  requestOptions?: RequestOptions
): HttpResponsePromise<void>;

/**
 * Get knowledge base size for agent
 * @param agent_id - The agent ID
 * @param requestOptions - Optional request configuration
 * @returns Number of pages in agent's knowledge base
 * @throws UnprocessableEntityError if request fails
 */
client.conversationalAi.agents.knowledgeBase.size(
  agent_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAgentKnowledgebaseSizeResponseModel>;

interface GetAgentKnowledgebaseSizeResponseModel {
  /** Number of pages in knowledge base */
  page_count: number;
}

/**
 * Simulate a conversation with an agent
 */
client.conversationalAi.agents.simulateConversation(
  agent_id: string,
  request: BodySimulatesAConversationV1ConvaiAgentsAgentIdSimulateConversationPost,
  requestOptions?: RequestOptions
): HttpResponsePromise<SimulateConversationResponse>;

/**
 * Simulate conversation with streaming
 */
client.conversationalAi.agents.simulateConversationStream(
  agent_id: string,
  request: BodySimulatesAConversationStreamV1ConvaiAgentsAgentIdSimulateConversationStreamPost,
  requestOptions?: RequestOptions
): HttpResponsePromise<void>;

/**
 * Run agent test suite
 */
client.conversationalAi.agents.runTests(
  agent_id: string,
  request: RunAgentTestsRequestModel,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetTestSuiteInvocationResponseModel>;

/**
 * Response from creating an agent
 */
interface CreateAgentResponseModel {
  /** Unique identifier for the created agent */
  agent_id: string;
}

/**
 * Response from getting agent details
 */
interface GetAgentResponseModel {
  /** Unique identifier for the agent */
  agent_id: string;
  /** Agent name */
  name: string;
  /** Agent conversation configuration */
  conversation_config: ConversationalConfig;
  /** Platform-specific settings */
  platform_settings?: AgentPlatformSettingsRequestModel;
  /** Workflow configuration */
  workflow?: WorkflowConfigInput;
  /** Evaluation settings */
  evaluation_settings?: EvaluationSettings;
  /** Widget configuration */
  widget_config?: WidgetConfig;
  /** Creation timestamp */
  created_at_unix_secs: number;
  /** Whether the agent is archived */
  is_archived?: boolean;
}

/**
 * Paginated response for listing agents
 */
interface GetAgentsPageResponseModel {
  /** Array of agent metadata */
  agents: AgentMetadata[];
  /** Cursor for next page, if available */
  next_cursor?: string;
  /** Whether there are more pages */
  has_more: boolean;
}

/**
 * Agent metadata in list responses
 */
interface AgentMetadata {
  /** Unique identifier for the agent */
  agent_id: string;
  /** Agent name */
  name: string;
  /** Creation timestamp */
  created_at_unix_secs: number;
  /** Whether the agent is archived */
  is_archived?: boolean;
}

/**
 * Response from running agent tests
 */
interface GetTestSuiteInvocationResponseModel {
  /** Unique identifier for the test invocation */
  invocation_id: string;
  /** Status of the test run */
  status: "pending" | "running" | "completed" | "failed";
  /** Test results when completed */
  results?: TestResult[];
}

/**
 * Individual test result
 */
interface TestResult {
  /** Test identifier */
  test_id: string;
  /** Whether the test passed */
  passed: boolean;
  /** Error message if test failed */
  error?: string;
}

/**
 * Get the current link used to share the agent with others
 * @param agent_id - The agent ID
 * @param requestOptions - Optional request configuration
 * @returns Agent link response
 * @throws UnprocessableEntityError if request fails
 */
client.conversationalAi.agents.link.get(
  agent_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<GetAgentLinkResponseModel>;

interface GetAgentLinkResponseModel {
  /** The sharable link URL for the agent */
  link: string;
}

/**
 * Calculates expected number of LLM tokens needed for the specified agent
 * @param agent_id - The agent ID
 * @param request - Optional calculation parameters
 * @param requestOptions - Optional request configuration
 * @returns LLM usage calculation response
 * @throws UnprocessableEntityError if request fails
 */
client.conversationalAi.agents.llmUsage.calculate(
  agent_id: string,
  request?: LlmUsageCalculatorRequestModel,
  requestOptions?: RequestOptions
): HttpResponsePromise<LlmUsageCalculatorResponseModel>;

interface LlmUsageCalculatorRequestModel {
  /** Optional parameters for LLM usage calculation */
  [key: string]: any;
}

interface LlmUsageCalculatorResponseModel {
  /** Estimated token usage */
  estimated_tokens: number;
  /** Additional usage details */
  [key: string]: any;
}

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

// Create an agent
const agent = await client.conversationalAi.agents.create({
  name: "Customer Support Agent",
  conversationConfig: {
    agent: {
      prompt: {
        prompt: "You are a helpful customer support agent. Be friendly and professional.",
      },
    },
  },
});

console.log("Agent ID:", agent.agent_id);