에이전트를 활용한 비동기 애플리케이션

이 가이드는 smolagents 라이브러리의 동기 에이전트를 Starlette 기반의 비동기 Python 웹 애플리케이션에 통합하는 방법을 설명합니다. 비동기 Python과 에이전트 통합을 처음 접하는 사용자들이 동기 에이전트 로직과 비동기 웹 서버를 효과적으로 결합하는 모범 사례를 익힐 수 있도록 구성했습니다.

개요

Starlette: Python에서 비동기 웹 애플리케이션을 구축하기 위한 경량 ASGI 프레임워크입니다.
anyio.to_thread.run_sync: 블로킹(동기) 코드를 백그라운드 스레드에서 실행하여 비동기 이벤트 루프를 차단하지 않도록 하는 유틸리티입니다.
CodeAgent: 프로그래밍 방식으로 작업을 해결할 수 있는 smolagents 라이브러리의 에이전트입니다.

백그라운드 스레드를 사용하는 이유는?

CodeAgent.run()은 Python 코드를 동기적으로 실행합니다. 비동기 엔드포인트에서 직접 호출하면 Starlette의 이벤트 루프를 차단하여 성능과 확장성이 저하됩니다. anyio.to_thread.run_sync로 이 작업을 백그라운드 스레드로 위임하면 높은 동시성에서도 앱의 응답성과 효율성을 유지할 수 있습니다.

예시 워크플로우

Starlette 앱은 task 문자열이 포함된 JSON 페이로드를 받는 /run-agent 엔드포인트를 노출합니다.
요청이 수신되면 anyio.to_thread.run_sync를 사용하여 백그라운드 스레드에서 에이전트가 실행됩니다.
결과는 JSON 응답으로 반환됩니다.

CodeAgent를 활용한 Starlette 앱 구축

1. 의존성 설치

pip install smolagents starlette anyio uvicorn

2. 애플리케이션 코드 ( main.py )

import anyio.to_thread
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route

from smolagents import CodeAgent, InferenceClientModel

agent = CodeAgent(
    model=InferenceClientModel(model_id="Qwen/Qwen3-Next-80B-A3B-Thinking"),
    tools=[],
)

async def run_agent(request: Request):
    data = await request.json()
    task = data.get("task", "")
    # Run the agent synchronously in a background thread
    result = await anyio.to_thread.run_sync(agent.run, task)
    return JSONResponse({"result": result})

app = Starlette(routes=[
    Route("/run-agent", run_agent, methods=["POST"]),
])

3. 앱 실행

uvicorn async_agent.main:app --reload

4. 엔드포인트 테스트

curl -X POST http://localhost:8000/run-agent -H 'Content-Type: application/json' -d '{"task": "What is 2+2?"}'

예상 응답:

{"result": "4"}

추가 자료

전체 코드는 examples/async_agent를 참고하세요.

Update on GitHub