관리 API

에이전트가 실행 중일 때 Agent Card URL 변경, 메모리 설정 변경, 세션 조회/삭제 등을 재시작 없이 수행할 수 있는 관리 API입니다.

사전 요건

AGENT_ID: 에이전트 식별자 (CLI scaffold 시 자동 설정, .env에서 변경 가능)
INTERNAL_RUNTIME_CONTROL_ENABLED=true: Registry 관리 API(/api/v1/registry/*) 활성화에 필요
메모리 관리 API(/api/v1/memory/*)는 INTERNAL_RUNTIME_CONTROL_ENABLED와 무관하게 항상 등록됩니다

공통 응답 형식

모든 엔드포인트는 동일한 envelope 구조를 사용합니다.

// 성공
{"success": true, "data": {...}, "error": null}

// 에러
{"success": false, "data": null, "error": {"code": "...", "message": "...", ...}}

HTTP 상태 코드: 200 성공, 400 잘못된 요청, 403 권한 없음, 404 리소스 없음, 409 충돌, 422 처리 불가.

엔드포인트

상태 조회

GET /api/v1/status

MCP/A2A 연결 상태와 에이전트 ID를 조회합니다.

curl http://localhost:8000/api/v1/status

{"success": true, "data": {"agent_id": "my-agent", "mcp": {}, "a2a": {}}, "error": null}

하위 호환 경로: GET /status

Agent Card

GET /api/v1/card/url

현재 agent-card에 설정된 공개 URL을 조회합니다.

curl http://localhost:8000/api/v1/card/url

{"success": true, "data": {"url": "http://10.10.20.22:24002/admin/a2a/my-agent"}, "error": null}

PATCH /api/v1/card/url

agent-card의 공개 URL을 런타임에 변경합니다. 프록시/게이트웨이 주소가 변경되었을 때 재시작 없이 즉시 반영합니다.

필드	타입	필수	설명
`url`	string	필수	새 공개 URL

curl -X PATCH http://localhost:8000/api/v1/card/url \
  -H "Content-Type: application/json" \
  -d '{"url": "http://new-proxy:8080/admin/a2a/my-agent"}'

{
  "success": true,
  "data": {
    "url": "http://new-proxy:8080/admin/a2a/my-agent",
    "previous_url": "http://10.10.20.22:24002/admin/a2a/my-agent",
    "persisted": true
  },
  "error": null
}

응답 필드	설명
`url`	변경된 URL
`previous_url`	변경 전 URL
`persisted`	`.env`에 `PUBLIC_AGENT_URL`이 동기화되었는지 여부. `false`이면 재시작 시 원복됩니다

메모리 설정

GET /api/v1/memory/config

현재 메모리 설정을 조회합니다.

curl http://localhost:8000/api/v1/memory/config

PATCH /api/v1/memory/config

런타임에 메모리 설정을 변경합니다. 에이전트 재시작 없이 즉시 반영됩니다.

필드	런타임 변경	설명
`summarize`	가능	장기 기억 요약 활성화
`window_size`	가능	LLM에 전달할 최근 메시지 수
`summarize_threshold`	가능	요약 트리거 메시지 수
`enabled`	불가	체크포인터/그래프 재빌드 필요
`backend`	불가	커넥션 풀 재생성 필요
`postgres_dsn`	불가	커넥션 풀 재생성 필요

curl -X PATCH http://localhost:8000/api/v1/memory/config \
  -H "Content-Type: application/json" \
  -d '{"summarize": true, "window_size": 10}'

세션 데이터 관리

모든 thread 관리 API는 AGENT_ID 기반 소유권 검증을 수행합니다. 다른 에이전트가 소유한 thread에 접근하면 FORBIDDEN (403) 에러가 반환됩니다.

GET /api/v1/memory/threads

자기 에이전트가 소유한 thread 목록을 반환합니다.

curl http://localhost:8000/api/v1/memory/threads

{"success": true, "data": {"agent_id": "my-agent", "threads": ["session-001", "session-002"]}, "error": null}

`GET /api/v1/memory/threads/{thread_id}/messages`

특정 세션의 채팅 기록을 조회합니다.

curl http://localhost:8000/api/v1/memory/threads/session-001/messages

{
  "success": true,
  "data": {
    "thread_id": "session-001",
    "messages": [
      {"role": "human", "content": "안녕"},
      {"role": "ai", "content": "안녕하세요!"}
    ]
  },
  "error": null
}

`DELETE /api/v1/memory/threads/{thread_id}`

특정 세션의 모든 데이터(checkpoint + persistent_memory)를 삭제합니다.

curl -X DELETE http://localhost:8000/api/v1/memory/threads/session-001

DELETE /api/v1/memory/threads?all=true

이 에이전트가 소유한 모든 thread를 삭제합니다. AGENT_ID 기반으로 자기 데이터만 삭제되므로 공유 DB에서도 안전합니다.

curl -X DELETE "http://localhost:8000/api/v1/memory/threads?all=true"

{"success": true, "data": {"agent_id": "my-agent", "deleted": {"checkpoints": 10, "checkpoint_blobs": 20, "persistent_memory": 5}}, "error": null}

POST /api/v1/memory/migrate-agent-id

AGENT_ID 변경 시 기존 thread의 소유권을 일괄 갱신합니다.

curl -X POST http://localhost:8000/api/v1/memory/migrate-agent-id \
  -H "Content-Type: application/json" \
  -d '{"old_id": "my-agent-old", "new_id": "my-agent"}'

{"success": true, "data": {"old_id": "my-agent-old", "new_id": "my-agent", "migrated_threads": 5}, "error": null}

Registry 관리

INTERNAL_RUNTIME_CONTROL_ENABLED=true 설정이 필요합니다.

GET /api/v1/registry/metadata

Registry 참조 목록과 generation을 조회합니다.

하위 호환 경로: GET /internal/runtime-metadata

POST /api/v1/registry/reload

변경된 Registry 컴포넌트를 핫리로드합니다.

하위 호환 경로: POST /internal/reload

에러 코드

코드	HTTP	설명
`MEMORY_DISABLED`	404	메모리가 활성화되어 있지 않음
`AGENT_ID_REQUIRED`	409	AGENT_ID 환경변수 미설정
`IMMUTABLE_FIELD`	422	런타임 변경 불가 필드 요청
`INVALID_BODY`	400	요청 본문이 유효한 JSON이 아님
`INVALID_PARAM`	400	필수 파라미터 누락 또는 잘못된 타입
`MISSING_THREAD_ID`	400	thread_id 누락
`THREAD_NOT_FOUND`	404	해당 thread_id 데이터 없음
`FORBIDDEN`	403	다른 에이전트 소유의 thread
`RUNTIME_UNAVAILABLE`	409	Registry 런타임을 사용할 수 없음