# 에이전트 API

> 그 에이전트로 제한된 키로 HTTP 호출을 보냅니다 — 단발 요청, 또는 호출 사이에 맥락을 잇는 세션.

**API** 섹션은 Endue 밖의 무언가가 이 에이전트를 부를 수 있는 키를 발급합니다. [대화](/ko/docs/work/conversations/)·[채널](/ko/docs/automate/channels/)에 이은 세 번째 진입로이고, 이쪽은 프로그램용입니다.

## 언제 쓰는가

부르는 쪽이 코드일 때입니다. 매일 요약을 남기는 스크립트, 분류를 맡기는 백엔드, CI 에서 도는 잡 같은 것들이죠. 부르는 쪽이 사람이라면 채널이 낫습니다 — 실과 질문과 승인을 함께 주니까요.

## 키 발급

<Steps>

1. **[에이전트 빌더](/ko/docs/build/agent-builder/)의 API 섹션**을 열고 키를 만듭니다.

2. **지금 복사하세요.** 키는 한 번만 보여줍니다. 잃어버리면 해지하고 새로 발급하면 됩니다.

3. **프로그램은 읽고 사람은 못 읽는 곳에 두세요** — 환경 변수나 시크릿 저장소에 두고, 저장소에는 절대 넣지 마세요.

</Steps>

여기서 만든 키는 **이 에이전트로 제한**됩니다. 다른 에이전트를 부르는 데 쓸 수 없습니다. 계정 전체 키는 **설정 → 계정**에서 따로 발급하는데, 가능하면 좁은 쪽을 쓰세요.

<Screenshot
  name="studio-api"
  alt="API 섹션 — 발급된 키가 접두사·마지막 사용 시각과 함께 나열되고, 그 위에 그대로 복사해 쓸 수 있는 호출 예시가 있다."
/>

## 에이전트 호출

키를 `Authorization: Bearer sk_…`(또는 `X-API-Key`)로 보내고, 시킬 일을 담아 요청합니다.

```http
POST /api/public/v1/agents/{agent_id}/invoke
Authorization: Bearer sk_...
Content-Type: application/json

{ "input": "어제 들어온 문의 요약해줘" }
```

응답에는 에이전트의 답과 함께 **세션 id** 가 담깁니다. 다음 호출에 그 id 를 돌려보내면 새로 시작하는 대신 같은 맥락 — 기록이 있는 같은 대화 — 에서 이어갑니다.

```json
{ "input": "이제 제품 영역별로 묶어줘", "session_id": "..." }
```

`"stream": true` 를 주면 실행이 끝나기를 기다리지 않고 생성되는 대로 답을 받습니다.

<Aside type="note" title="세션은 곧 대화입니다">
  세션은 따로 관리할 무언가가 아닙니다. 각각이 Endue 에서 열어볼 수 있는 대화이고, 사이드바의
  에이전트 API 그룹에서 무엇을 물었고 무엇을 답했는지 읽을 수 있습니다.
</Aside>

## API 호출이 갖지 못하는 것

API 호출자는 대화 앞에 앉아 있지 않으므로 [지켜보는 사람이 없는 실행](/ko/docs/automate/routines/#승인할-사람이-아무도-없다)으로 취급됩니다.

- 바깥으로 보내거나 지우는 행동은 승인을 기다리는 게 아니라 **거절**됩니다.
- 에이전트가 던지는 [질문](/ko/docs/work/questions/)에 답할 사람이 없습니다.

판단이 필요 없을 만큼 요청을 정확히 쓰고, 발송이 아니라 초안을 기대하세요.

## 한계

- 세션당 한 번에 실행 하나. 그 세션에서 실행이 도는 중에 다시 부르면 대기가 아니라 거절됩니다.
- 키는 한 번만 보여주고 복구할 수 없습니다 — 해지 후 재발급하세요.
- 에이전트로 제한된 키는 그 에이전트에만 통합니다. 다른 에이전트에 대해서는 없음으로 응답합니다.
- 키 해지는 즉시 적용됩니다.

## 관련 문서

<CardGrid>
  <LinkCard
    title="채널"
    href="/ko/docs/automate/channels/"
    description="프로그램이 아니라 사람을 위한 진입로."
  />
  <LinkCard
    title="승인"
    href="/ko/docs/work/approvals/"
    description="API 호출이 스스로 메일을 보내지 못하는 이유."
  />
  <LinkCard
    title="보안과 권한"
    href="/ko/docs/account/security/"
    description="키가 닿는 범위와 거두는 법."
  />
</CardGrid>