Composio는 에이전트가 GitHub, Slack, 캘린더 같은 외부 서비스를 호출하도록 도구 정의와 인증 흐름을 중개하는 통합 플랫폼입니다. OAuth 갱신과 API별 어댑터를 직접 만드는 일을 줄일 수 있지만, 에이전트가 어떤 사용자 권한으로 어떤 변경을 실행할지는 애플리케이션이 통제해야 합니다. 도입 전에는 지원 앱 수보다 최소 권한, 쓰기 승인, 토큰 보관, 실패 복구와 감사 로그를 검증해야 합니다.
Composio는 에이전트 인증을 얼마나 줄여 주나: 권한과 실행 검증
Composio는 직접 API 연동과 무엇이 다른가?
Composio는 AI 에이전트와 외부 애플리케이션(SaaS) 사이를 연결하는 통합 인프라입니다. 쉽게 말해, LLM(거대언어모델)에게 ‘손’과 ‘발’을 달아주는 플랫폼입니다.
직접 연동에서는 API schema, OAuth callback, token 갱신과 오류 처리를 앱마다 구현합니다. Composio는 선택한 integration의 action과 관리형 인증을 공통 인터페이스로 제공합니다. 관리형이라는 말은 권한 결정과 사용자 동의, 외부 서비스 정책 확인까지 대신한다는 뜻은 아닙니다.
어떤 기능이 연동 구현을 줄일까?
GitHub README와 공식 문서를 기반으로 분석한 Composio의 핵심 기능은 다음과 같습니다.
사전 구축된 도구
GitHub, Slack, Google Calendar, Jira, Notion, Discord 등 개발자와 비즈니스에 필요한 거의 모든 주요 SaaS가 이미 연동되어 있습니다. API 명세를 일일이 찾아볼 필요 없이, Composio가 제공하는 ‘Action’을 가져다 쓰기만 하면 됩니다.
관리형 인증
OAuth 2.0 흐름, 액세스 토큰 관리와 갱신을 중개합니다.
- User-Level Auth: 에이전트가 ‘내 계정’으로 로그인해서 동작하도록 만들 수 있습니다.
- 자격 증명 관리: 토큰 저장, 암호화, 폐기, 침해 대응 방식은 현재 보안 문서와 계약에서 확인해야 합니다.
프레임워크 연결
특정 라이브러리에 종속되지 않습니다. 현재 가장 인기 있는 AI 프레임워크들을 모두 지원합니다.
- LangChain
- AutoGen (Microsoft)
- CrewAI
- LlamaIndex
- OpenAI Assistant API
트리거와 액션
단순히 AI가 도구를 호출하는 것뿐만 아니라, 외부 이벤트(예: “새로운 GitHub 이슈가 등록되면”)를 감지하여 에이전트를 깨우는 트리거 기능도 지원합니다.
자연어 요청은 어떻게 실제 API 호출이 될까?
Composio의 작동 원리는 ‘Function Calling’의 중개자 역할로 이해하면 쉽습니다.
- 사용자/개발자: Composio 플랫폼에서 GitHub, Slack 등의 ‘Integration’을 활성화합니다.
- Composio SDK: 선택한 도구들의 API 명세(OpenAPI Spec)를 LLM이 이해할 수 있는 함수 정의(Function Definition) 형태로 변환하여 에이전트에게 전달합니다.
- LLM (Agent): 사용자의 명령(예: “이 repo에 스타 줘”)을 분석하고, Composio가 제공한 함수 중 적절한 것(
github_star_repo)을 선택합니다. - Composio 서버: 에이전트의 요청을 받아 관리 중인 인증 토큰으로 외부 API를 호출하고 결과를 반환합니다.
개발자는 인증 헤더와 갱신 구현을 줄일 수 있지만 action 선택, argument 검증, 사용자 승인과 결과 확인은 남습니다.
설치 예제에서 무엇을 현재 문서와 대조해야 하나?
아래 코드는 원문 시점의 Python 설치, 사용 스냅샷입니다. package 이름과 API, framework adapter, 인증 절차는 사용 시점의 문서에서 다시 확인해야 합니다.
1. 패키지 설치 핵심 코어 패키지를 설치합니다.
1
pip install composio-core
2. CLI 로그인 및 설정 터미널에서 Composio 계정에 로그인하고 필요한 도구를 추가합니다. 이 과정이 매우 직관적입니다.
1
2
3
4
5
6
7
8
# Composio 계정 로그인
composio login
# GitHub 도구 추가 (웹 브라우저가 열리며 인증 진행)
composio add github
# 현재 연동된 앱 확인
composio apps
예제 코드가 실제 변경을 만들기 전에 무엇을 막아야 할까?
가장 대중적인 OpenAI와 LangChain을 사용하여, “Composio GitHub 저장소에 스타(Star)를 누르는 에이전트”를 만들어 보겠습니다.
예제 1: OpenAI SDK와 직접 연동 (Raw Python)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import os
from openai import OpenAI
from composio import Composio, App
# 1. 클라이언트 초기화
openai_client = OpenAI(api_key="YOUR_OPENAI_KEY")
composio_client = Composio(api_key="YOUR_COMPOSIO_KEY")
# 2. GitHub 도구 가져오기
# 'github' 앱의 모든 기능을 가져오거나, 특정 기능만 골라올 수 있습니다.
tools = composio_client.get_tools(apps=[App.GITHUB])
# 3. 에이전트 실행 (도구 정보 주입)
instruction = "ComposioHQ/composio 저장소에 스타(Star)를 눌러줘."
response = openai_client.chat.completions.create(
model="gpt-4-turbo",
messages=[{"role": "user", "content": instruction}],
tools=tools, # Composio가 변환해준 도구 정의
tool_choice="auto"
)
# 4. 결과 실행 (Composio가 실제 API 호출 처리)
result = composio_client.handle_tool_calls(response)
print(result)
예제 2: LangChain과 연동 (더 간결함)
LangChain을 사용하면 도구 바인딩과 실행 과정을 더욱 추상화할 수 있습니다. (composio-langchain 설치 필요)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_functions_agent, AgentExecutor
from composio_langchain import ComposioToolSet, App
# 1. LLM 설정
llm = ChatOpenAI(model="gpt-4-turbo")
# 2. Composio 툴셋 설정
# 'github' 앱의 'star' 관련 액션만 콕 집어서 가져올 수도 있습니다.
toolset = ComposioToolSet()
tools = toolset.get_tools(apps=[App.GITHUB])
# 3. 에이전트 생성 및 실행
prompt = ... # (LangChain 기본 프롬프트 사용)
agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 4. 명령 수행
agent_executor.invoke(
{"input": "GitHub에서 ComposioHQ/composio 레포지토리에 스타를 눌러줘"}
)
이 예제는 실제 GitHub 계정의 상태를 바꾸는 action입니다. 시험 계정과 제한된 권한을 사용하고, 실행 전 대상 repository와 action argument를 사용자에게 보여 주는 편이 안전합니다.
어떤 자동화부터 제한적으로 시작할까?
- AI 코딩 어시스턴트 (SW Engineering Agent)
- GitHub Issues를 읽고 -> 코드를 수정하고 -> Pull Request를 생성하고 -> Slack으로 팀원에게 알림을 보냅니다. (Swe-agent와 유사)
- 개인 비서 (Personal Assistant)
- Google Calendar 일정을 확인하고 -> Gmail로 회의 초대장을 보내고 -> Notion에 회의록 초안을 생성합니다.
- 영업 자동화 (Sales Ops)
- 새로운 리드(Lead)가 들어오면 Salesforce에 등록하고 -> 관련 문서를 검색하여 -> 맞춤형 콜드 메일을 발송합니다.
관리형 연동의 장단점은 무엇인가?
장점 (Pros):
- 구현 단축 가능성: 지원 action에서는 인증과 API adapter 구현을 줄일 수 있습니다.
- 표준화된 인터페이스: Slack이든 Jira든 동일한 방식으로 도구를 호출할 수 있습니다.
- 자격 증명 위임: 로컬 키 저장을 줄일 수 있지만 외부 서비스에 맡기는 위험과 운영 절차를 검토해야 합니다.
단점 (Cons):
- 의존성: Composio 서버가 다운되면 에이전트의 외부 연동 기능도 멈출 수 있습니다. (물론 로컬 호스팅 옵션도 존재합니다).
- 커스텀 복잡도: 지원하지 않는 사내 자체 API(Private API)를 연동하려면 커스텀 툴 정의 과정을 거쳐야 합니다.
사용자별 권한과 실패 복구를 어떻게 시험할까?
두 개의 시험 사용자와 서로 다른 scope를 만들고, 읽기 전용 사용자가 쓰기 action을 호출하지 못하는지 확인합니다. action 목록에서 숨기는 것만으로 충분하지 않고 실제 실행 계층과 외부 서비스가 거부해야 합니다. 계정 연결을 해제한 직후 cache와 trigger가 이전 토큰으로 계속 실행되지 않는지도 봅니다.
LLM이 잘못된 저장소, 채널, 수신자를 선택하는 사례를 의도적으로 만듭니다. 변경 action에는 대상과 변경 내용을 구조화해 보여 주고 명시적 승인을 받은 뒤 실행하며, 같은 요청의 중복 실행을 막을 idempotency 기준이 필요합니다. 일부 단계만 성공한 다중 앱 workflow는 어느 단계부터 재시도할지도 정해야 합니다.
트리거가 외부 입력을 에이전트 prompt로 전달할 때는 prompt injection과 권한 상승을 시험합니다. GitHub 이슈나 이메일의 문구가 다른 app action을 지시해도 신뢰된 사용자 명령으로 취급하지 않아야 합니다. source content, trigger 규칙, agent instruction을 분리하고 허용된 action만 실행합니다.
감사 로그에는 사용자, 연결 계정, 선택한 action, 인수, 승인, 외부 응답과 오류를 남기되 token과 민감한 본문은 마스킹해야 합니다. 서비스 장애나 rate limit 때 안전하게 중단하고 수동 처리로 전환할 수 있을 때 관리형 연동을 운영 자동화로 확대할 수 있습니다.
직접 연동과 관리형 연동을 같은 조건에서 비교하려면
평가할 때는 서로 다른 데모를 비교하지 말고, 같은 시험 계정으로 동일한 업무를 두 번 구현합니다. 예를 들어 GitHub 이슈를 읽어 Slack의 지정 채널에 알리는 흐름을 직접 API 방식과 Composio 방식으로 각각 만들고, 최초 연결에 걸린 시간뿐 아니라 token 갱신, scope 변경, 연결 해제까지 수행합니다. 연결을 끊은 뒤 예약 trigger나 cache가 이전 권한으로 실행되지 않는지도 확인해야 인증 구현을 줄인 효과와 새로 생긴 의존성을 함께 볼 수 있습니다.
실패 시험도 같은 입력으로 맞춥니다. 잘못된 저장소, 존재하지 않는 채널, rate limit, 외부 API의 일시 오류를 넣고 재시도가 중복 이슈나 메시지를 만들지 않는지 기록합니다. 여러 앱을 잇는 workflow라면 앞 단계만 성공했을 때 자동으로 되돌릴지, 성공한 상태를 남기고 사람에게 넘길지 먼저 정합니다. 이 결정 없이 성공률만 비교하면 정상 데모에서는 보이지 않던 운영 비용을 놓치기 쉽습니다.
마지막으로 호출 수와 지연, 사람이 승인, 복구에 쓴 시간, 감사 로그에서 한 실행을 재구성할 수 있는지를 표로 남깁니다. 관리 계층이 중단됐을 때 읽기 전용 경로를 유지할 수 있는지와 연결 설정을 내보내 직접 연동으로 옮길 수 있는지도 시험합니다. 구현 시간이 줄면서도 최소 권한, 추적 가능성, 장애 복구가 직접 연동과 같거나 더 명확할 때 관리형 연동의 도입 근거가 생깁니다.
함께 읽으면 이해가 이어지는 글
- langchain-ai/openwiki: AI 코딩 에이전트 전용 저장소 위키가 필요한 이유와 작동 원리 — LangChain이 공개한 OpenWiki는 AI 코딩 에이전트가 코드베이스를 정확히 이해하도록 돕는 마크다운 위키 자동 생성 도구입니다. 이 글에서는 프롬프트 비대화와 RAG의 한계를 극복하는 ‘LLM 위키’ 패턴의 핵심 원리와…
- OpenOSINT: AI와 결합된 차세대 오픈소스 정보 수집 에이전트의 작동 원리와 실전 활용법 — 복잡한 명령어와 수동 데이터 연결의 피로도를 덜어주는 오픈소스 프로젝트 OpenOSINT의 내부 구조와 연동 기법을 깊이 있게 다룹니다.
- OpenAI 커스텀 GPT 공식 종료 발표, 플러그인 아키텍처 이전 마감 일정 정리 — OpenAI가 ChatGPT 커스텀 GPT를 단계적으로 종료하고 새로운 플러그인 아키텍처로 이전하는 계획을 공식 발표했습니다. Enterprise 워크스페이스는 2026년 9월 25일 신규 생성이 멈추고 2026년 12월 11일…
표지 1 —
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.