딥 에이전트를 AG-UI로 노출하기
딥 에이전트를 AG-UI로 노출하기 (Agent User Interaction Protocol)
딥 에이전트(deep agent)를 Agent User Interaction Protocol(AG-UI)로 감싸면 실행되는 이벤트를 어떤 AG-UI 클라이언트나 프론트엔드로든 스트리밍할 수 있어요. AG-UI는 에이전트와 사용자용 앱을 잇는 방식을 표준화한, 가볍고 이벤트 기반의 오픈 프로토콜인데요. 딥 에이전트를 AG-UI로 노출하면 실행 과정이 메시지·툴 호출·추론·상태·생명주기를 담은 타입 있는 이벤트 스트림으로 바뀌어서, 프론트엔드를 LangGraph 내부 구조에 결합하지 않고도 구동할 수 있답니다.
출처: 공식문서
AG-UI와 다른 프로토콜의 차이
AG-UI는 에이전트 백엔드와 사용자 프론트엔드를 잇는, 에이전트-사용자 상호작용용 프로토콜이에요. Deep Agents의 다른 프로토콜과는 용도가 달라요.
- AG-UI: 딥 에이전트를 프론트엔드 앱에 연결 (이 페이지)
- ACP(Agent Client Protocol): 딥 에이전트를 코드 에디터·IDE에 연결
- MCP(Model Context Protocol): 딥 에이전트가 외부 서버에 호스팅된 툴을 호출
- A2A(Agent2Agent): 딥 에이전트를 다른 에이전트에 연결
퀵스타트
딥 에이전트를 LangGraph 그래프로 서빙한 다음, TypeScript @ag-ui/langgraph 어댑터를 연결하면 AG-UI 클라이언트가 그 그래프를 구동할 수 있어요.
의존성 설치
그래프를 서빙하려면 Deep Agents와 LangGraph CLI를 설치해요. 이후에 쓸 AG-UI 어댑터는 TypeScript(@ag-ui/langgraph)예요. 파이썬용 CopilotKit 또는 AG-UI FastAPI 브리지가 필요하다면 CopilotKit 문서를 참고하세요.
pip install deepagents "langgraph-cli[inmem]"
uv add deepagents "langgraph-cli[inmem]"
createDeepAgent(파이썬에서는 create_deep_agent)로 만든 딥 에이전트는 그 자체가 LangGraph 그래프예요. 이를 LangGraph 서버로 서빙한 뒤 AG-UI 어댑터를 그 서버에 연결하면 되어요.
딥 에이전트 만들기
에이전트를 정의하고 그래프를 export해서 LangGraph 서버가 로드할 수 있게 해요.
from deepagents import create_deep_agent
agent = create_deep_agent(
model="anthropic:claude-sonnet-4-6",
system_prompt="You are an expert researcher.",
)
에이전트 서빙하기
프로젝트 루트의 langgraph.json 파일에 그래프를 등록해요.
{
"dependencies": ["."],
"graphs": {
"deep_agent": "./agent.py:agent"
},
"env": ".env"
}
LangGraph 개발 서버를 시작하면 http://localhost:2024에서 그래프를 HTTP로 노출해요.
langgraph dev
AG-UI 어댑터 연결
TypeScript @ag-ui/langgraph 어댑터가 실행 중인 그래프를 AG-UI 에이전트로 감싸서 어떤 클라이언트든 구동할 수 있게 해줘요. LangGraph 서버 주소와 로드할 그래프 이름을 지정하면 되고, 그래프가 파이썬으로 작성됐든 TypeScript로 작성됐든 동작해요.
import { LangGraphAgent } from "@ag-ui/langgraph";
const agent = new LangGraphAgent({
graphId: "deep_agent",
deploymentUrl: "http://localhost:2024",
});
더 알아보기 (Learn more)
- AG-UI LangGraph 어댑터는 npm에서
@ag-ui/langgraph로 제공돼요. 파이썬 쪽 브리지가 필요하다면 CopilotKit 문서를 참고하세요.