@zavudev/sdk 0.54.0 → 0.56.0

package/src/resources/agents/agents.ts

@@ -0,0 +1,603 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as SendersAPI from './senders';
+import { SenderConnectParams, SenderConnectResponse, SenderDisconnectParams, Senders } from './senders';
+import * as AgentAPI from '../senders/agent/agent';
+import { AgentsCursor } from '../senders/agent/agent';
+import { APIPromise } from '../../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Agents extends APIResource {
+  senders: SendersAPI.Senders = new SendersAPI.Senders(this._client);
+
+  /**
+   * Create an agent without a sender. It is created disabled; connect a sender and
+   * enable it when you are ready for it to answer.
+   *
+   * **Sub-resources.** An agent's tools, flows and knowledge bases are reachable at
+   * `/v1/agents/{agentId}/tools`, `/v1/agents/{agentId}/flows` and
+   * `/v1/agents/{agentId}/knowledge-bases`, mirroring the sender-scoped routes
+   * documented under `/v1/senders/{senderId}/agent/...` exactly. Use the
+   * agent-scoped form while the agent has no sender: the sender-scoped one cannot
+   * address it.
+   *
+   * @example
+   * ```ts
+   * const agent = await client.agents.create({
+   *   model: 'model',
+   *   name: 'name',
+   *   provider: 'openai',
+   *   systemPrompt: 'systemPrompt',
+   * });
+   * ```
+   */
+  create(body: AgentCreateParams, options?: RequestOptions): APIPromise<AgentCreateResponse> {
+    return this._client.post('/v1/agents', { body, ...options });
+  }
+
+  /**
+   * Get an agent
+   *
+   * @example
+   * ```ts
+   * const agent = await client.agents.retrieve('agentId');
+   * ```
+   */
+  retrieve(agentID: string, options?: RequestOptions): APIPromise<AgentRetrieveResponse> {
+    return this._client.get(path`/v1/agents/${agentID}`, options);
+  }
+
+  /**
+   * Update an agent
+   *
+   * @example
+   * ```ts
+   * const agent = await client.agents.update('agentId');
+   * ```
+   */
+  update(
+    agentID: string,
+    body: AgentUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<AgentUpdateResponse> {
+    return this._client.patch(path`/v1/agents/${agentID}`, { body, ...options });
+  }
+
+  /**
+   * Every agent in the project, newest first — including agents that are not
+   * connected to any sender yet, which the sender-scoped routes cannot reach. Each
+   * item carries `senderIds`, the senders the agent answers on.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const agent of client.agents.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: AgentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AgentsCursor, AgentAPI.Agent> {
+    return this._client.getAPIList('/v1/agents', Cursor<AgentAPI.Agent>, { query, ...options });
+  }
+
+  /**
+   * Delete an agent
+   *
+   * @example
+   * ```ts
+   * await client.agents.delete('agentId');
+   * ```
+   */
+  delete(agentID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/agents/${agentID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * The voices an agent can speak with, for `voice.ttsVoiceId`. Filter by `language`
+   * to get the ones that speak it; a voice can still be used with `language: auto`,
+   * where the agent follows the caller and keeps the chosen voice.
+   *
+   * @example
+   * ```ts
+   * const response = await client.agents.listVoices();
+   * ```
+   */
+  listVoices(
+    query: AgentListVoicesParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AgentListVoicesResponse> {
+    return this._client.get('/v1/agents/voices', { query, ...options });
+  }
+
+  /**
+   * Run the agent's prompt, model and knowledge base against a message and return
+   * the reply instead of delivering it. Writes nothing and charges nothing, so it is
+   * safe to call repeatedly while iterating on a prompt.
+   *
+   * Note that a dry run never **executes** tools — running them would cause real
+   * side effects. Live conversations on every channel do call them. When the agent
+   * has enabled tools, that gap is reported in `warnings` rather than silently
+   * producing an answer that looks like a tool call happened.
+   *
+   * @example
+   * ```ts
+   * const response = await client.agents.test('agentId', {
+   *   message: 'Where is order ORD-12345?',
+   * });
+   * ```
+   */
+  test(agentID: string, body: AgentTestParams, options?: RequestOptions): APIPromise<AgentTestResponse> {
+    return this._client.post(path`/v1/agents/${agentID}/test`, { body, ...options });
+  }
+}
+
+export interface AgentCreateResponse {
+  /**
+   * AI Agent configuration for a sender.
+   */
+  agent: AgentAPI.Agent;
+}
+
+export interface AgentRetrieveResponse {
+  /**
+   * AI Agent configuration for a sender.
+   */
+  agent: AgentAPI.Agent;
+}
+
+export interface AgentUpdateResponse {
+  /**
+   * AI Agent configuration for a sender.
+   */
+  agent: AgentAPI.Agent;
+}
+
+export interface AgentListVoicesResponse {
+  items: Array<AgentListVoicesResponse.Item>;
+
+  /**
+   * Languages an agent can be pinned to. `auto` follows the caller.
+   */
+  languages: Array<string>;
+
+  /**
+   * Voices in the catalog, before filtering.
+   */
+  total?: number;
+}
+
+export namespace AgentListVoicesResponse {
+  export interface Item {
+    /**
+     * Value for `voice.ttsVoiceId`.
+     */
+    id: string;
+
+    language: string;
+
+    name: string;
+  }
+}
+
+export interface AgentTestResponse {
+  error: string | null;
+
+  inputTokens: number;
+
+  /**
+   * Knowledge-base chunks retrieved for this message. Zero means the answer was not
+   * grounded in your documents.
+   */
+  knowledgeChunksUsed: number;
+
+  latencyMs: number;
+
+  outputTokens: number;
+
+  success: boolean;
+
+  /**
+   * What the agent would reply.
+   */
+  text: string | null;
+
+  /**
+   * Things that are true of this agent but that a dry run cannot prove. Surfaced so
+   * a passing dry run is never mistaken for proof that the agent works live.
+   *
+   * - The agent being disabled.
+   * - Enabled tools that were **not offered to the model** here — the model never
+   *   saw them, so a reply that looks like a lookup was invented. Live conversations
+   *   on every channel do offer them; running them here would cause real side
+   *   effects.
+   * - An agent whose sender has none of the channels it triggers on, which answers
+   *   every dry run and no real message.
+   * - Contact metadata that exists on a real conversation but not here.
+   */
+  warnings: Array<string>;
+
+  /**
+   * Tools that actually ran, in order, when the request set `executeTools`. Empty on
+   * a normal dry run, where nothing is executed. An entry with `ok: false` means the
+   * agent saw an error and answered around it, which is what a customer would have
+   * received.
+   */
+  executedToolCalls?: Array<AgentTestResponse.ExecutedToolCall>;
+}
+
+export namespace AgentTestResponse {
+  export interface ExecutedToolCall {
+    name: string;
+
+    ok: boolean;
+
+    error?: string | null;
+  }
+}
+
+export interface AgentCreateParams {
+  model: string;
+
+  name: string;
+
+  /**
+   * LLM provider for the AI agent.
+   */
+  provider: AgentAPI.AgentProvider;
+
+  systemPrompt: string;
+
+  contextWindowMessages?: number;
+
+  includeContactMetadata?: boolean;
+
+  maxTokens?: number;
+
+  temperature?: number;
+
+  triggerOnChannels?: Array<string>;
+
+  triggerOnMessageTypes?: Array<string>;
+
+  /**
+   * Voice Agent configuration on a sender's AI agent. Controls how the agent behaves
+   * on inbound and outbound phone calls through Zavu's managed voice pipeline
+   * (speech recognition, the agent's LLM, and speech synthesis, with real-time
+   * interruption handling). Requires the Voice Agents feature to be enabled for your
+   * team.
+   */
+  voice?: AgentCreateParams.Voice;
+}
+
+export namespace AgentCreateParams {
+  /**
+   * Voice Agent configuration on a sender's AI agent. Controls how the agent behaves
+   * on inbound and outbound phone calls through Zavu's managed voice pipeline
+   * (speech recognition, the agent's LLM, and speech synthesis, with real-time
+   * interruption handling). Requires the Voice Agents feature to be enabled for your
+   * team.
+   */
+  export interface Voice {
+    /**
+     * Whether the agent handles voice calls. When false, the sender's number is not
+     * answered by the voice agent and outbound calls are rejected.
+     */
+    enabled: boolean;
+
+    /**
+     * Opening line the agent speaks when the call connects. If omitted, the agent
+     * waits for the caller to speak first.
+     */
+    greeting?: string;
+
+    /**
+     * Greeting per language, keyed by language code. Used when the caller's language
+     * differs from the one `greeting` is written in.
+     */
+    greetings?: { [key: string]: string };
+
+    /**
+     * Whether the caller can interrupt the agent while it is speaking (barge-in). When
+     * true, the agent stops talking as soon as the caller starts.
+     */
+    interruptible?: boolean;
+
+    /**
+     * BCP-47 language code used for both speech recognition and speech synthesis (e.g.
+     * `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
+     */
+    language?: string;
+
+    /**
+     * Hard limit on call length in minutes. The call ends automatically when reached.
+     */
+    maxCallDurationMinutes?: number;
+
+    /**
+     * How long the agent waits during silence before ending the call.
+     */
+    maxIdleSeconds?: number;
+
+    /**
+     * Model that runs the conversation, co-located in the voice network for lowest
+     * latency. Independent of the model used for text messaging. Derived from the
+     * agent's text model when omitted.
+     */
+    model?: string;
+
+    /**
+     * Whether the call audio is recorded.
+     */
+    recordCalls?: boolean;
+
+    /**
+     * Speech-recognition model. Uses the default when omitted.
+     */
+    sttModel?: string;
+
+    /**
+     * Speech-recognition provider. Uses the default when omitted.
+     */
+    sttProvider?: string;
+
+    /**
+     * E.164 phone number the agent can transfer the call to. When set, the agent is
+     * given a transfer tool it can use to hand the call to a human.
+     */
+    transferPhoneNumber?: string;
+
+    /**
+     * Speech-synthesis provider. Uses the default when omitted.
+     */
+    ttsProvider?: string;
+
+    /**
+     * Identifier of the synthesized voice that speaks. Choose from the voices
+     * available in the dashboard. Uses a neutral default when omitted.
+     */
+    ttsVoiceId?: string;
+
+    /**
+     * What the agent does when an answering machine or voicemail is detected on an
+     * outbound call.
+     */
+    voicemailAction?: 'hangup' | 'leave_message';
+
+    /**
+     * Message spoken when `voicemailAction` is `leave_message`. Falls back to
+     * `greeting` when omitted.
+     */
+    voicemailMessage?: string;
+
+    /**
+     * Speech rate. 1.0 is natural. Only honoured by voices that support rate control;
+     * ignored by the others.
+     */
+    voiceSpeed?: number;
+  }
+}
+
+export interface AgentUpdateParams {
+  apiKey?: string;
+
+  contextWindowMessages?: number;
+
+  enabled?: boolean;
+
+  includeContactMetadata?: boolean;
+
+  maxTokens?: number | null;
+
+  model?: string;
+
+  name?: string;
+
+  /**
+   * LLM provider for the AI agent.
+   */
+  provider?: AgentAPI.AgentProvider;
+
+  systemPrompt?: string;
+
+  temperature?: number | null;
+
+  triggerOnChannels?: Array<string>;
+
+  triggerOnMessageTypes?: Array<string>;
+
+  /**
+   * Voice Agent configuration. Patch this object to enable voice, change the
+   * greeting, or adjust call limits. Requires the Voice Agents feature to be enabled
+   * for your team.
+   */
+  voice?: AgentUpdateParams.Voice;
+}
+
+export namespace AgentUpdateParams {
+  /**
+   * Voice Agent configuration. Patch this object to enable voice, change the
+   * greeting, or adjust call limits. Requires the Voice Agents feature to be enabled
+   * for your team.
+   */
+  export interface Voice {
+    /**
+     * Whether the agent handles voice calls. When false, the sender's number is not
+     * answered by the voice agent and outbound calls are rejected.
+     */
+    enabled: boolean;
+
+    /**
+     * Opening line the agent speaks when the call connects. If omitted, the agent
+     * waits for the caller to speak first.
+     */
+    greeting?: string;
+
+    /**
+     * Greeting per language, keyed by language code. Used when the caller's language
+     * differs from the one `greeting` is written in.
+     */
+    greetings?: { [key: string]: string };
+
+    /**
+     * Whether the caller can interrupt the agent while it is speaking (barge-in). When
+     * true, the agent stops talking as soon as the caller starts.
+     */
+    interruptible?: boolean;
+
+    /**
+     * BCP-47 language code used for both speech recognition and speech synthesis (e.g.
+     * `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
+     */
+    language?: string;
+
+    /**
+     * Hard limit on call length in minutes. The call ends automatically when reached.
+     */
+    maxCallDurationMinutes?: number;
+
+    /**
+     * How long the agent waits during silence before ending the call.
+     */
+    maxIdleSeconds?: number;
+
+    /**
+     * Model that runs the conversation, co-located in the voice network for lowest
+     * latency. Independent of the model used for text messaging. Derived from the
+     * agent's text model when omitted.
+     */
+    model?: string;
+
+    /**
+     * Whether the call audio is recorded.
+     */
+    recordCalls?: boolean;
+
+    /**
+     * Speech-recognition model. Uses the default when omitted.
+     */
+    sttModel?: string;
+
+    /**
+     * Speech-recognition provider. Uses the default when omitted.
+     */
+    sttProvider?: string;
+
+    /**
+     * E.164 phone number the agent can transfer the call to. When set, the agent is
+     * given a transfer tool it can use to hand the call to a human.
+     */
+    transferPhoneNumber?: string;
+
+    /**
+     * Speech-synthesis provider. Uses the default when omitted.
+     */
+    ttsProvider?: string;
+
+    /**
+     * Identifier of the synthesized voice that speaks. Choose from the voices
+     * available in the dashboard. Uses a neutral default when omitted.
+     */
+    ttsVoiceId?: string;
+
+    /**
+     * What the agent does when an answering machine or voicemail is detected on an
+     * outbound call.
+     */
+    voicemailAction?: 'hangup' | 'leave_message';
+
+    /**
+     * Message spoken when `voicemailAction` is `leave_message`. Falls back to
+     * `greeting` when omitted.
+     */
+    voicemailMessage?: string;
+
+    /**
+     * Speech rate. 1.0 is natural. Only honoured by voices that support rate control;
+     * ignored by the others.
+     */
+    voiceSpeed?: number;
+  }
+}
+
+export interface AgentListParams extends CursorParams {}
+
+export interface AgentListVoicesParams {
+  /**
+   * BCP-47 tag (`en`, `es`, `pt-BR`). Omit, or pass `auto`, for every voice.
+   */
+  language?: string;
+}
+
+export interface AgentTestParams {
+  /**
+   * What to say to the agent.
+   */
+  message: string;
+
+  /**
+   * Run the tools the agent calls instead of reporting the choice and stopping.
+   *
+   * Off by default because a tool handler talks to the outside world: a rehearsal
+   * that charges a card is not a rehearsal. Turn it on to exercise the loop that
+   * actually matters — the model picks a tool, the handler answers, the model
+   * replies with the result — without sending a message to anyone. What ran comes
+   * back in `executedToolCalls`.
+   */
+  executeTools?: boolean;
+
+  /**
+   * Prior turns, oldest first, to exercise multi-turn behaviour without persisting a
+   * thread. Trimmed to the agent's context window.
+   */
+  history?: Array<AgentTestParams.History>;
+
+  /**
+   * Set false to skip retrieval and isolate prompt behaviour from the knowledge
+   * base.
+   */
+  useKnowledgeBase?: boolean;
+}
+
+export namespace AgentTestParams {
+  export interface History {
+    content: string;
+
+    role: 'user' | 'assistant';
+  }
+}
+
+Agents.Senders = Senders;
+
+export declare namespace Agents {
+  export {
+    type AgentCreateResponse as AgentCreateResponse,
+    type AgentRetrieveResponse as AgentRetrieveResponse,
+    type AgentUpdateResponse as AgentUpdateResponse,
+    type AgentListVoicesResponse as AgentListVoicesResponse,
+    type AgentTestResponse as AgentTestResponse,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
+    type AgentListVoicesParams as AgentListVoicesParams,
+    type AgentTestParams as AgentTestParams,
+  };
+
+  export {
+    Senders as Senders,
+    type SenderConnectResponse as SenderConnectResponse,
+    type SenderConnectParams as SenderConnectParams,
+    type SenderDisconnectParams as SenderDisconnectParams,
+  };
+}
+
+export { type AgentsCursor };

package/src/resources/agents/index.ts

@@ -0,0 +1,21 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Agents,
+  type AgentCreateResponse,
+  type AgentRetrieveResponse,
+  type AgentUpdateResponse,
+  type AgentListVoicesResponse,
+  type AgentTestResponse,
+  type AgentCreateParams,
+  type AgentUpdateParams,
+  type AgentListParams,
+  type AgentListVoicesParams,
+  type AgentTestParams,
+} from './agents';
+export {
+  Senders,
+  type SenderConnectResponse,
+  type SenderConnectParams,
+  type SenderDisconnectParams,
+} from './senders';

package/src/resources/agents/senders.ts

@@ -0,0 +1,79 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as AgentAPI from '../senders/agent/agent';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Senders extends APIResource {
+  /**
+   * Make the agent answer on this sender. An agent can serve several senders; a
+   * sender answers with at most one agent, so connecting one that is already in use
+   * returns `400` naming the agent that holds it.
+   *
+   * @example
+   * ```ts
+   * const response = await client.agents.senders.connect(
+   *   'agentId',
+   *   { senderId: 'senderId' },
+   * );
+   * ```
+   */
+  connect(
+    agentID: string,
+    body: SenderConnectParams,
+    options?: RequestOptions,
+  ): APIPromise<SenderConnectResponse> {
+    return this._client.post(path`/v1/agents/${agentID}/senders`, { body, ...options });
+  }
+
+  /**
+   * Stop the agent answering on this sender. The agent's primary sender is part of
+   * the agent itself and cannot be disconnected here.
+   *
+   * @example
+   * ```ts
+   * await client.agents.senders.disconnect('senderId', {
+   *   agentId: 'agentId',
+   * });
+   * ```
+   */
+  disconnect(senderID: string, params: SenderDisconnectParams, options?: RequestOptions): APIPromise<void> {
+    const { agentId } = params;
+    return this._client.delete(path`/v1/agents/${agentId}/senders/${senderID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface SenderConnectResponse {
+  /**
+   * AI Agent configuration for a sender.
+   */
+  agent: AgentAPI.Agent;
+}
+
+export interface SenderConnectParams {
+  /**
+   * Sender to connect.
+   */
+  senderId: string;
+}
+
+export interface SenderDisconnectParams {
+  /**
+   * Agent ID.
+   */
+  agentId: string;
+}
+
+export declare namespace Senders {
+  export {
+    type SenderConnectResponse as SenderConnectResponse,
+    type SenderConnectParams as SenderConnectParams,
+    type SenderDisconnectParams as SenderDisconnectParams,
+  };
+}

package/src/resources/agents.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './agents/index';