# Get an agent

> GET /v1/agents/{agentId}

`GET https://api.zavu.dev/v1/agents/{agentId}`

## Parameters

- `agentId` (path, string, required): Agent ID.

## Responses

### 200

Agent details.

- `agent` (object, required): AI Agent configuration for a sender.
  - `id` (string, required)
  - `senderId` (string): The sender the agent was created on, its primary. Absent on an agent created with `POST /v1/agents`, which has no primary even after senders are connected to it. `senderIds` lists every sender the agent answers on.
  - `name` (string, required)
  - `enabled` (boolean, required): Whether the agent is active.
  - `provider` (string, required): LLM provider for the AI agent. One of: `openai`, `anthropic`, `google`, `mistral`, `zavu`.
  - `model` (string, required): Model ID (e.g., gpt-4o-mini, claude-3-5-sonnet).
  - `systemPrompt` (string, required): System prompt for the agent.
  - `contextWindowMessages` (integer): Number of previous messages to include as context.
  - `includeContactMetadata` (boolean): Whether to include contact metadata in context.
  - `maxTokens` (integer, nullable): Maximum tokens for LLM response.
  - `temperature` (number, nullable): LLM temperature (0-2).
  - `triggerOnChannels` (string[]): Channels that trigger the agent.
  - `triggerOnMessageTypes` (string[]): Message types that trigger the agent.
  - `stats` (object)
    - `totalInvocations` (integer)
    - `totalTokensUsed` (integer)
    - `totalCost` (number): Total cost in USD.
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>, required)
  - `voice` (object): Voice Agent configuration. When present and enabled, the agent can answer inbound phone calls and place outbound calls with Zavu's managed voice pipeline.
    - `enabled` (boolean, required): Whether the agent handles voice calls. When false, the sender's number is not answered by the voice agent and outbound calls are rejected.
    - `greeting` (string): Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.
    - `greetings` (object): Greeting per language, keyed by language code. Used when the caller's language differs from the one `greeting` is written in.
      - `{key}` (string)
    - `language` (string): 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.
    - `model` (string): 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.
    - `sttProvider` (string): Speech-recognition provider. Uses the default when omitted.
    - `sttModel` (string): Speech-recognition model. Uses the default when omitted.
    - `ttsProvider` (string): Speech-synthesis provider. Uses the default when omitted.
    - `ttsVoiceId` (string): Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.
    - `voiceSpeed` (number): Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.
    - `interruptible` (boolean): 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.
    - `maxCallDurationMinutes` (integer): Hard limit on call length in minutes. The call ends automatically when reached.
    - `maxIdleSeconds` (integer): How long the agent waits during silence before ending the call.
    - `recordCalls` (boolean): Whether the call audio is recorded.
    - `voicemailAction` (string): What the agent does when an answering machine or voicemail is detected on an outbound call. One of: `hangup`, `leave_message`.
    - `voicemailMessage` (string): Message spoken when `voicemailAction` is `leave_message`. Falls back to `greeting` when omitted.
    - `transferPhoneNumber` (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.
  - `senderIds` (string[]): Senders this agent answers on. An agent can serve several; `senderId` remains the primary one, for compatibility.

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 404

Agent not found.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X GET "https://api.zavu.dev/v1/agents/agent_abc123" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.agents.retrieve("agent_abc123");

console.log(result);
```