# 에이전트 조회 (/docs/api/agents/getAgent)
**GET /v1/accounts/{accountId}/agents/{agentId}**
```json
{
  "operationId": "getAgent",
  "summary": "에이전트 조회",
  "tags": [
    "Agents"
  ],
  "responses": {
    "200": {
      "description": "조회 성공",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "agentId",
              "name",
              "instructions",
              "greeting",
              "language",
              "maxDurationSeconds",
              "beginMessageDelayMs",
              "liveEvents",
              "model",
              "voice",
              "voiceProvider",
              "voiceModel",
              "configuration",
              "phoneNumbers",
              "dateCreated",
              "dateUpdated"
            ],
            "properties": {
              "agentId": {
                "type": "string",
                "example": "cmagent123",
                "description": "에이전트 ID"
              },
              "name": {
                "type": "string",
                "example": "고객 지원 에이전트"
              },
              "instructions": {
                "type": "string",
                "example": "당신은 친절하고 유능한 한국어 음성 에이전트입니다. 사용자의 요청을 주의 깊게 듣고 정확하고 간결하게 답하세요.",
                "description": "에이전트 시스템 프롬프트"
              },
              "greeting": {
                "type": "boolean",
                "example": true,
                "description": "통화 연결 직후 에이전트가 먼저 인사할지 여부"
              },
              "language": {
                "type": "string",
                "example": "ko",
                "description": "에이전트 기본 언어"
              },
              "maxDurationSeconds": {
                "type": "integer",
                "nullable": true,
                "minimum": 10,
                "maximum": 7200,
                "example": null,
                "description": "통화가 연결된 뒤 이 시간(초)이 지나면 통화를 끊습니다. 수신은 받은 순간, 발신은 상대가 받은 순간부터 잽니다. null 이면 제한 없음입니다. 시간이 되면 대화 중이어도 끊으며, 끊기 전 안내 멘트는 나가지 않습니다."
              },
              "beginMessageDelayMs": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000,
                "example": 0,
                "description": "발신 통화에서 상대가 받은 뒤 첫 인사를 시작하기 전에 기다리는 시간(밀리초)입니다. 0 이면 바로 인사합니다. greeting 이 true 일 때만 적용되며, 수신 통화에는 적용되지 않습니다."
              },
              "liveEvents": {
                "type": "object",
                "description": "통화 중 이벤트(실시간 전사·키패드) 설정. 받을 이벤트를 `events` 에 고르면 이 에이전트의 통화 이벤트를\n`GET /v1/accounts/{accountId}/calls/{callId}/live-events`(·`/stream`) 로 받습니다. 추가 요금은 없습니다.\n",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "type": "array",
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "enum": [
                        "transcript.final",
                        "transcript.partial",
                        "dtmf.received",
                        "dtmf.sent"
                      ]
                    },
                    "description": "받을 이벤트. 비우면 꺼집니다(새 에이전트 기본값). 수정할 때는 보낸 목록으로 통째로 바뀝니다.\n하나라도 고르면 `stream.started`·`stream.ended` 가 함께 옵니다.\n- `transcript.final`: 한 발화의 확정 텍스트\n- `transcript.partial`: 말하는 도중의 텍스트\n- `dtmf.sent`: AI가 통화 미디어 연결로 보낸 키 하나. 상대 시스템의 수신 완료를 보장하지 않습니다.\n- `dtmf.received`: 상대가 누른 키 하나\n",
                    "example": [
                      "transcript.final",
                      "dtmf.received"
                    ]
                  }
                }
              },
              "model": {
                "type": "string",
                "example": "gpt-realtime-2.1-mini",
                "description": "현재 에이전트가 사용하는 LLM 모델"
              },
              "voice": {
                "type": "string",
                "nullable": true,
                "example": "7706804e-ea85-443a-968a-b9bf363bdde8",
                "description": "현재 음성 ID"
              },
              "voiceProvider": {
                "type": "string",
                "nullable": true,
                "example": "cartesia",
                "description": "음성 출력 제공자"
              },
              "voiceModel": {
                "type": "string",
                "nullable": true,
                "example": "sonic-3.5",
                "description": "외부 TTS 모델. 모델 내장 음성에서는 null입니다."
              },
              "configuration": {
                "type": "object",
                "required": [
                  "outputMode",
                  "language",
                  "knowledge",
                  "stt",
                  "llm",
                  "tts",
                  "vad",
                  "session"
                ],
                "properties": {
                  "outputMode": {
                    "type": "string",
                    "enum": [
                      "realtime_voice",
                      "external_tts",
                      "pipeline",
                      "live",
                      "grok",
                      "elevenlabs"
                    ]
                  },
                  "language": {
                    "type": "string"
                  },
                  "knowledge": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "enabled",
                      "topK"
                    ],
                    "properties": {
                      "enabled": {
                        "type": "boolean"
                      },
                      "topK": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10
                      }
                    }
                  },
                  "stt": {
                    "type": "object",
                    "allOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "provider",
                          "model"
                        ],
                        "properties": {
                          "provider": {
                            "type": "string",
                            "enum": [
                              "openai"
                            ]
                          },
                          "model": {
                            "type": "string",
                            "enum": [
                              "gpt-4o-transcribe",
                              "gpt-4o-mini-transcribe",
                              "whisper-1"
                            ]
                          },
                          "language": {
                            "type": "string",
                            "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다."
                          },
                          "prompt": {
                            "type": "string"
                          },
                          "temperature": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "detect_language": {
                            "type": "boolean"
                          },
                          "noise_reduction_type": {
                            "type": "string",
                            "enum": [
                              "near_field",
                              "far_field"
                            ]
                          },
                          "use_realtime": {
                            "type": "boolean"
                          }
                        }
                      }
                    ],
                    "nullable": true
                  },
                  "llm": {
                    "type": "object",
                    "additionalProperties": {
                      "oneOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean"
                        }
                      ]
                    },
                    "required": [
                      "provider",
                      "model"
                    ],
                    "properties": {
                      "provider": {
                        "type": "string"
                      },
                      "model": {
                        "type": "string"
                      },
                      "voice": {
                        "type": "string"
                      }
                    }
                  },
                  "tts": {
                    "type": "object",
                    "allOf": [
                      {
                        "discriminator": {
                          "propertyName": "provider"
                        },
                        "oneOf": [
                          {
                            "title": "Cartesia",
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "provider",
                              "model",
                              "voice"
                            ],
                            "properties": {
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "cartesia"
                                ]
                              },
                              "model": {
                                "type": "string",
                                "enum": [
                                  "sonic-3.5",
                                  "sonic-3.6"
                                ]
                              },
                              "voice": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "language": {
                                "type": "string",
                                "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다."
                              },
                              "speed": {
                                "type": "number",
                                "minimum": 0.6,
                                "maximum": 1.5
                              },
                              "volume": {
                                "type": "number",
                                "minimum": 0.5,
                                "maximum": 1.5
                              }
                            }
                          },
                          {
                            "title": "xAI",
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "provider",
                              "model",
                              "voice"
                            ],
                            "properties": {
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "xai"
                                ]
                              },
                              "model": {
                                "type": "string",
                                "enum": [
                                  "tts-1"
                                ]
                              },
                              "voice": {
                                "type": "string",
                                "minLength": 1
                              },
                              "language": {
                                "type": "string",
                                "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다."
                              }
                            }
                          },
                          {
                            "title": "Google",
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "provider",
                              "model",
                              "voice"
                            ],
                            "properties": {
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "google"
                                ]
                              },
                              "model": {
                                "type": "string",
                                "enum": [
                                  "chirp_3"
                                ]
                              },
                              "voice": {
                                "type": "string",
                                "description": "Chirp 3 HD 음성명입니다(예 `ko-KR-Chirp3-HD-Aoede`).",
                                "pattern": "^[a-z]{2,3}-[A-Z]{2}-Chirp3-HD-[A-Za-z]+$"
                              },
                              "language": {
                                "type": "string",
                                "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다."
                              },
                              "speed": {
                                "type": "number",
                                "minimum": 0.6,
                                "maximum": 1.5
                              }
                            }
                          },
                          {
                            "title": "ElevenLabs",
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "provider",
                              "model",
                              "voice"
                            ],
                            "properties": {
                              "provider": {
                                "type": "string",
                                "enum": [
                                  "elevenlabs"
                                ]
                              },
                              "model": {
                                "type": "string",
                                "description": "eleven_flash_v2_5(빠름) 또는 eleven_multilingual_v2(고품질, 글자당 요금 2배)",
                                "enum": [
                                  "eleven_flash_v2_5",
                                  "eleven_multilingual_v2"
                                ]
                              },
                              "voice": {
                                "type": "string",
                                "description": "ElevenLabs 음성 id(20자 영숫자). provider가 elevenlabs인 내 복제 음성도 쓸 수 있습니다.",
                                "pattern": "^[A-Za-z0-9]{20}$"
                              },
                              "language": {
                                "type": "string",
                                "description": "생략하면 에이전트 언어(configuration.language)를 따릅니다."
                              },
                              "speed": {
                                "type": "number",
                                "minimum": 0.7,
                                "maximum": 1.2
                              }
                            }
                          }
                        ]
                      }
                    ],
                    "nullable": true
                  },
                  "vad": {
                    "type": "object",
                    "allOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "required": [
                          "provider"
                        ],
                        "properties": {
                          "provider": {
                            "type": "string",
                            "enum": [
                              "silero"
                            ]
                          },
                          "min_silence_duration": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 3
                          },
                          "min_speech_duration": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "prefix_padding_duration": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 2
                          },
                          "max_buffered_speech": {
                            "type": "number",
                            "minimum": 1,
                            "maximum": 120
                          },
                          "activation_threshold": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "sample_rate": {
                            "type": "integer",
                            "enum": [
                              16000,
                              8000
                            ]
                          },
                          "force_cpu": {
                            "type": "boolean"
                          }
                        }
                      }
                    ],
                    "nullable": true
                  },
                  "session": {
                    "type": "object",
                    "allOf": [
                      {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "turn_detection": {
                            "type": "string",
                            "enum": [
                              "vad",
                              "stt"
                            ]
                          },
                          "allow_interruptions": {
                            "type": "boolean"
                          },
                          "min_endpointing_delay": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 5
                          },
                          "max_endpointing_delay": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 15
                          },
                          "min_interruption_duration": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 2
                          }
                        }
                      }
                    ],
                    "nullable": true
                  }
                }
              },
              "phoneNumbers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "07012340001"
                ],
                "description": "이 에이전트에 착신 연결된 전화번호"
              },
              "dateCreated": {
                "type": "string",
                "format": "date-time"
              },
              "dateUpdated": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "인증 실패",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "에이전트를 찾을 수 없음",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```