DEV Community

Cover image for 헤드리스 소프트웨어: API가 제품이 되다
Rihpig
Rihpig

Posted on • Originally published at apidog.com

헤드리스 소프트웨어: API가 제품이 되다

요약: AI 에이전트가 기업 소프트웨어에서 조용히 UI를 우회하고 있습니다. API와 MCP를 통해 노출되는 데이터 레이어가 새로운 제품 표면이 되고 있습니다. 이번 분기에 API 팀이 바로 실행해야 할 다섯 가지 변경 사항과 아직 표준화되지 않은 핵심 문제를 정리합니다.

사용자 인터페이스는 한때 B2B 소프트웨어의 가장 강한 해자였습니다. 영업 담당자는 Salesforce에서, 지원 팀은 Zendesk에서, 조달 팀은 SAP에서 일했습니다. 높은 접근 빈도, 근육 기억, 그리고 모든 입력을 양식으로 강제해 데이터 위생을 유지하는 방식이 제품 고착성을 만들었습니다. 데이터는 그 과정에서 저장되는 결과물이었습니다.

지금 Apidog을 사용해 보세요

이제 그 구조가 바뀌고 있습니다. AI 에이전트는 브라우저를 열지 않고도 API를 통해 기업 데이터를 직접 읽고 쓸 수 있습니다. Salesforce는 이미 데이터 레이어를 에이전트에 노출하는 헤드리스 제품을 발표했습니다. 다른 기록 시스템도 몇 년이 아니라 몇 주 단위로 따라올 가능성이 큽니다.

UI가 더 이상 유일한 진입점이 아니라면, API가 제품의 실제 진입점입니다. 따라서 API 팀은 “프론트엔드가 호출하는 내부 배관”이 아니라 “에이전트가 이해하고 선택하고 실행하는 제품 표면”으로 API를 설계해야 합니다.

실질적인 “헤드리스 소프트웨어”의 의미

헤드리스 소프트웨어는 에이전트가 직접 데이터를 읽고 쓸 수 있도록 API를 통해 데이터 레이어를 노출하는 기업 소프트웨어입니다. UI가 사라지는 것은 아닙니다. UI가 더 이상 유일한 문이 아니게 되는 것입니다.

이는 “API 우선(API-first)”이나 “헤드리스 CMS(headless CMS)”와 다릅니다.

  • API-first: 소프트웨어를 어떻게 설계할 것인가에 대한 방법론
  • Headless CMS: 콘텐츠를 어떻게 제공할 것인가에 대한 아키텍처
  • Headless software: 소프트웨어를 소비하는 주체가 인간 UI 사용자에서 에이전트로 바뀌는 현상

즉, 데이터를 읽고 쓰는 주체가 더 이상 브라우저를 사용하는 인간만이 아닙니다. MCP 접근 권한과 목표를 가진 에이전트입니다.

이 전환을 가능하게 만든 요인은 세 가지입니다.

  1. 도구를 계획하고 선택할 수 있는 LLM
  2. 에이전트가 외부 시스템을 발견하는 방식을 표준화하는 MCP
  3. API를 우회하거나 데이터 추출을 자동화하는 비용의 하락

따라서 API가 “개발자가 한 번 클라이언트를 작성하고 사람이 매일 사용하는 것”이라는 전제로 설계되어 있다면, 지금 구조를 점검해야 합니다.

더 이상 유효하지 않은 다섯 가지 고착 요인

기존 기업 시스템은 보통 다섯 가지 요소로 사용자를 묶어 두었습니다. 에이전트 관점에서 보면 대부분 약해집니다.

1. 접근 빈도

사용자는 매일 같은 UI에 로그인하면서 습관을 형성했습니다. 영업 담당자는 Salesforce를 하루에 여러 번 열었습니다.

에이전트에는 근육 기억이 없습니다. 도구를 바꾸는 비용은 대개 구성 파일을 수정하는 비용에 가깝습니다.

tools:
  crm:
    provider: salesforce
    endpoint: https://api.example.com
Enter fullscreen mode Exit fullscreen mode

이 구성이 다른 CRM으로 바뀌어도 계약이 안정적이면 에이전트 입장에서는 큰 차이가 없습니다.

2. 읽기-쓰기 워크플로

기존에는 데이터가 계속 이동 중이었기 때문에 마이그레이션이 위험했습니다. 그러나 에이전트는 기계 속도로 읽고 씁니다. API 계약이 안정적이라면 뒤쪽 데이터베이스가 무엇인지는 상대적으로 덜 중요합니다.

3. 문서화되지 않은 SOP

“10만 달러가 넘는 거래는 VP 승인이 필요하다” 같은 규칙은 조직 내부에만 존재하는 경우가 많습니다. 이는 여전히 기존 기업에 방어력을 줍니다.

하지만 에이전트가 워크플로를 반복 실행하면, 이 규칙은 결국 정책, 프롬프트, 설정 파일, 테스트 케이스 중 어딘가에 명시적으로 인코딩됩니다.

4. 내부 습관 루프

팀의 일상 업무가 특정 UI 주변에서 형성되면 제품 고착성이 생깁니다. 하지만 업무 흐름이 에이전트를 통해 실행되기 시작하면, 특정 UI를 중심으로 형성된 습관 루프는 약해집니다.

5. 규정 준수 중요성

규정 준수는 여전히 유효합니다. 데이터 이동 주체가 인간이든 에이전트든 감사 추적은 필요합니다.

오히려 이 지점이 새로운 방어력의 핵심이 됩니다. API는 호출을 처리하는 것뿐 아니라 “누가, 어떤 에이전트를 통해, 어떤 정책 아래, 무엇을 실행했는지”를 기록해야 합니다.

이번 분기에 API 팀이 변경해야 할 다섯 가지 사항

API가 새로운 제품 표면이라면, 이번 분기에 다음 다섯 가지를 실행해야 합니다.

1. API를 배관이 아닌 제품 표면으로 다루기

프론트엔드가 호출하기 위해 만든 REST 엔드포인트와 에이전트가 스스로 추론하고 선택해야 하는 REST 엔드포인트는 요구사항이 다릅니다.

에이전트가 API를 호출하려면 계약 자체가 명확해야 합니다.

점검할 항목

  • 엔드포인트 이름이 동작을 설명하는가?
  • 필드 이름이 일관적인가?
  • 동일한 필드가 컨텍스트마다 다른 의미를 갖지 않는가?
  • 오류 응답이 다음 액션을 설명하는가?
  • OpenAPI 스펙만 보고 호출 방법을 이해할 수 있는가?

나쁜 예:

{
  "error": "400 Bad Request"
}
Enter fullscreen mode Exit fullscreen mode

좋은 예:

{
  "error": {
    "code": "missing_required_field",
    "message": "필수 필드 customer_id가 누락되었습니다.",
    "action": "이 인보이스가 속한 고객의 ID를 customer_id로 전달하십시오."
  }
}
Enter fullscreen mode Exit fullscreen mode

AI 에이전트를 위한 API를 설계할 때는 계약이 곧 인터페이스입니다.

리트머스 테스트는 간단합니다.

유능한 에이전트가 OpenAPI 사양과 필드 설명만으로 API를 올바르게 호출할 수 있는가?

엔드포인트의 의미를 이해하려면 오래된 UI 소스 코드를 읽어야 한다면, 그 API는 아직 제품 표면이 아니라 내부 배관입니다.

2. REST 및 GraphQL과 함께 MCP 제공하기

REST는 에이전트가 API의 존재를 알고 있을 때 호출하는 방식입니다. MCP는 에이전트가 “무엇을 할 수 있는지” 발견하는 방식입니다.

MCP 서버가 없는 REST API는 robots.txt와 사이트맵이 없는 웹사이트와 비슷합니다. 기술적으로는 접근 가능하지만, 자동화된 시스템에게는 잘 보이지 않습니다.

기존 API를 버릴 필요는 없습니다.

  • REST 유지
  • GraphQL이 있다면 유지
  • MCP를 세 번째 진입점으로 추가

예시 구조:

/api/v1/customers        -> REST
/graphql                 -> GraphQL
/mcp                     -> MCP server
Enter fullscreen mode Exit fullscreen mode

MCP 서버는 에이전트가 사용할 수 있는 도구, 입력 스키마, 설명을 제공해야 합니다.

{
  "name": "create_invoice",
  "description": "고객 ID와 항목 목록을 받아 인보이스를 생성합니다.",
  "inputSchema": {
    "type": "object",
    "required": ["customer_id", "items"],
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "인보이스가 연결될 고객 ID"
      },
      "items": {
        "type": "array",
        "description": "청구 항목 목록"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Anthropic MCP 사양은 계약을 정의합니다. Apidog은 그 주변의 테스트와 문서화 작업을 처리하는 데 사용할 수 있습니다.

MCP가 무엇이고 API 팀에 왜 중요한지 알고 싶다면 저희 심층 분석을 참고하십시오.

3. CRUD 객체가 아닌 의도와 결과 중심으로 스키마 설계하기

기존 SaaS 데이터 모델은 대개 명사 중심입니다.

  • Opportunities
  • Leads
  • Accounts
  • Contacts
  • Tickets
  • Invoices

하지만 에이전트는 명사보다 목표로 생각합니다.

  • “이탈 위험이 있는 계정을 찾아라”
  • “어제 마감된 거래에 대한 제안서 초안을 작성하라”
  • “밤새 P0 티켓을 연 계정을 에스컬레이션하라”

따라서 차세대 API는 CRUD 객체만 노출하는 대신 의도 기반 엔드포인트를 제공해야 합니다.

기존 방식:

POST /opportunities
POST /activities
POST /tasks
Enter fullscreen mode Exit fullscreen mode

의도 기반 방식:

POST /intents/capture-buying-signal
Enter fullscreen mode Exit fullscreen mode

요청 예시:

{
  "lead_id": "lead_123",
  "signal": "pricing_page_visited",
  "source": "website",
  "observed_at": "2026-05-01T09:30:00Z"
}
Enter fullscreen mode Exit fullscreen mode

응답 예시:

{
  "intent_id": "intent_789",
  "created_records": {
    "opportunity_id": "opp_456",
    "activity_id": "act_321",
    "task_id": "task_654"
  },
  "next_action": "sales_rep_follow_up"
}
Enter fullscreen mode Exit fullscreen mode

이 방식에서는 CRUD가 사라지는 것이 아닙니다. CRUD는 구현 세부 사항이 되고, 에이전트는 비즈니스 의도를 호출합니다.

AI 에이전트를 위한 API 준비에 대한 안내서에서 이러한 패턴을 더 자세히 다룹니다.

4. 에이전트 ID와 범위 지정 권한 분리하기

모든 에이전트 호출은 사용자의 호출과 구분되어야 합니다.

문제는 다음 두 이벤트가 같은 로그로 기록되면 안 된다는 점입니다.

Alice가 버튼을 클릭했다.
Alice의 에이전트가 새벽 3시에 Alice를 대신해 버튼을 클릭했다.
Enter fullscreen mode Exit fullscreen mode

API는 최소한 다음 정보를 구분해야 합니다.

  • 실제 사용자 ID
  • 에이전트 ID
  • 에이전트 버전
  • 위임 범위
  • 실행된 정책
  • 요청 입력과 출력

권장 헤더 예시:

X-Acting-On-Behalf-Of: user_123
X-Agent-Identity: support-agent@1.4.2
X-Agent-Run-Id: run_789
X-Policy-Version: support-refund-policy@2026-05-01
Enter fullscreen mode Exit fullscreen mode

현재 패턴은 MCP 보안 정책을 참고하십시오.

5. 감사 추적과 폐쇄 루프 피드백으로 액션 레이어 구축하기

새로운 방어력은 데이터를 저장하는 데 있지 않습니다. 행동을 실행하고, 결과를 관찰하고, 그 피드백으로 다음 결정을 개선하는 데 있습니다.

API 팀은 액션 엔드포인트에 다음 세 가지를 추가해야 합니다.

1. 결과 콜백 또는 웹훅

에이전트는 실행 결과를 학습해야 합니다.

POST /webhooks/action-results
Enter fullscreen mode Exit fullscreen mode 
{
  "action_id": "act_123",
  "status": "completed",
  "outcome": "customer_replied",
  "metadata": {
    "reply_sentiment": "positive"
  }
}
Enter fullscreen mode Exit fullscreen mode

2. 재현 가능한 실행 기록

에이전트가 무엇을 했는지 디버그하려면 입력, 출력, 도구 호출 순서를 재현할 수 있어야 합니다.

{
  "run_id": "run_789",
  "agent": "support-agent@1.4.2",
  "input": {},
  "tool_calls": [],
  "output": {},
  "created_at": "2026-05-01T09:30:00Z"
}
Enter fullscreen mode Exit fullscreen mode

3. 감사 행

모든 액션은 감사 로그에 남아야 합니다.

CREATE TABLE agent_audit_logs (
  id TEXT PRIMARY KEY,
  agent_identity TEXT NOT NULL,
  acting_on_behalf_of TEXT NOT NULL,
  policy_version TEXT NOT NULL,
  action TEXT NOT NULL,
  input JSONB NOT NULL,
  output JSONB,
  created_at TIMESTAMP NOT NULL
);
Enter fullscreen mode Exit fullscreen mode

데이터 손실 없이 에이전트 워크플로 테스트는 이러한 변화를 운영 환경에 적용하는 방법을 다룹니다.

해결되지 않은 부분: 에이전트 권한 부여

에이전트 준비 소프트웨어에서 가장 덜 해결되었고 가장 중요한 문제는 권한 부여입니다.

핵심 질문은 다음과 같습니다.

어떤 에이전트가, 누구를 대신하여, 무엇을 할 수 있으며, 그 실행은 어떻게 감사 가능한가?

2026년 기준으로 이 문제를 완전히 해결한 표준은 아직 부족합니다.

  • OAuth는 위임된 사용자 접근을 위해 설계되었습니다.
  • RBAC는 인간 역할을 위해 설계되었습니다.
  • 기존 감사 로그는 사용자가 무엇을 했는지 추적하기 위해 설계되었습니다.

하지만 지금 바로 적용할 수 있는 네 가지 패턴은 있습니다.

1. 에이전트 ID별 범위 지정 토큰

사용자 세션 토큰을 에이전트에게 재사용하지 마십시오.

대신 에이전트별 토큰을 발급하고, 사용자 권한보다 좁은 범위를 부여하십시오.

{
  "token_type": "agent",
  "agent_id": "support-agent",
  "version": "1.4.2",
  "acting_on_behalf_of": "user_123",
  "scopes": [
    "invoice:read",
    "refund:create:max_50"
  ]
}
Enter fullscreen mode Exit fullscreen mode

토큰이 유출되면 사용자 전체 권한이 아니라 에이전트 권한만 취소할 수 있어야 합니다.

2. 모든 요청에 위임 메타데이터 포함

모든 API 호출에는 최소한 다음 메타데이터가 필요합니다.

X-Acting-On-Behalf-Of: user_123
X-Agent-Identity: billing-agent@2.1.0
Enter fullscreen mode Exit fullscreen mode

가능하면 다음도 추가하십시오.

X-Agent-Run-Id: run_abc123
X-Policy-Version: billing-policy@2026-05-01
Enter fullscreen mode Exit fullscreen mode

이 두세 개의 헤더만으로도 감사 품질이 크게 올라갑니다.

3. 에이전트 작업 전용 감사 로그

에이전트 작업은 사용자 작업과 같은 테이블에 섞지 않는 것이 좋습니다.

규정 준수 팀은 보통 다음 질문에 빠르게 답해야 합니다.

SELECT *
FROM agent_audit_logs
WHERE created_at >= now() - interval '7 days'
ORDER BY created_at DESC;
Enter fullscreen mode Exit fullscreen mode

즉, “이번 주에 에이전트가 무엇을 했는가?”를 인간 활동 로그를 뒤지지 않고 확인할 수 있어야 합니다.

4. 정책을 코드로 관리

에이전트 권한 정책은 위키 문서가 아니라 버전 관리되는 빌드 아티팩트여야 합니다.

예시:

agents:
  support-agent:
    allowed:
      - invoice:read
      - ticket:read
      - refund:create
    constraints:
      refund:create:
        max_amount: 50
    denied:
      - account:delete
      - payment_method:update
Enter fullscreen mode Exit fullscreen mode

이 정책은 다음 작업에 포함되어야 합니다.

  • 코드 리뷰
  • CI 테스트
  • 배포 diff 확인
  • 감사 로그의 정책 버전 기록

이 방식은 완성된 표준은 아니지만, 지금 배포 가능합니다.

Apidog이 적합한 곳

API를 제품으로 취급하려면 설계, 계약, 모킹, MCP, 테스트, 감사를 한 곳에서 처리할 수 있는 작업대가 필요합니다. 그래서 Apidog을 구축했습니다.

위에서 다룬 다섯 가지 변경 사항은 Apidog의 주요 워크플로와 연결됩니다.

  • 변화 1: API를 제품으로 다루기

    스키마 우선 설계와 자동 문서화를 통해 계약을 에이전트가 읽는 단일 진실 공급원으로 만들 수 있습니다.

  • 변화 2: REST와 함께 MCP 제공

    전용 MCP 서버 테스트 도구를 사용해 MCP 서버를 배포 전에 검증할 수 있습니다.

  • 변화 3: 의도 중심 API 설계

    동적 응답을 활용한 모킹으로 백엔드 구현 전에도 의도 기반 엔드포인트를 프로토타입화하고 에이전트 클라이언트 호출을 테스트할 수 있습니다.

  • 변화 4: 권한 부여 분리

    환경 관리를 통해 에이전트 토큰과 사용자 토큰을 분리하고, 어설션 테스트로 정책 적용 여부를 확인할 수 있습니다.

  • 변화 5: 액션 레이어와 감사

    4월에 출시된 AI 에이전트 디버거 및 A2A 디버거를 통해 에이전트 기반 API 호출을 추적, 재현, 확인할 수 있습니다.

아직 사용해 보지 않았다면 Apidog을 다운로드하여 기존 OpenAPI 사양으로 실행해 보십시오. 모의 서버만으로도 일반적으로 마이그레이션 비용을 상쇄할 수 있습니다.

핵심

API 팀이 지금 주목해야 할 점은 간단합니다.

API 자체가 제품입니다.

API가 내부 배관이라면 쉽게 대체됩니다. 하지만 에이전트가 추론하고, 선택하고, 신뢰하고, 행동하는 표면이라면 그것은 새로운 해자가 됩니다.

이번 분기에 실행할 작업은 명확합니다.

  1. OpenAPI 계약을 에이전트가 읽을 수 있게 정리하기
  2. REST 및 GraphQL 옆에 MCP 제공하기
  3. CRUD만이 아니라 의도 기반 엔드포인트 추가하기
  4. 사용자 ID와 에이전트 ID를 분리하기
  5. 모든 에이전트 액션을 감사 가능하게 만들기

지금 시작하는 팀은 몇 년 뒤 완전히 다른 API 표면을 갖게 됩니다. 기다리는 팀은 고객이 “왜 에이전트 통합이 제대로 작동하지 않느냐”고 묻기 시작한 뒤, 마감 압박 속에서 API를 다시 작성하게 될 것입니다.

Top comments (0)