PydanticAI + Gonka — 저렴한 유형화된 AI 에이전트

먼저 키를 획득하세요: gate.joingonka.ai/register 에 가입하면 10M 무료 토큰을 드립니다. 이후 Dashboard의 API Keys에서 jg-xxx 키를 생성하세요.

설치:

pip install pydantic-ai
# 또는 OpenAI 의존성만 포함된 경량 버전:
# pip install "pydantic-ai-slim[openai]"

Gonka를 통한 최소한의 에이전트 예시입니다. PydanticAI는 OpenAIChatModel에 전달되는 OpenAIProvider(base_url=..., api_key=...)를 통해 커스텀 엔드포인트를 설정합니다:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-당신의-키",
    ),
)

agent = Agent(model)

result = agent.run_sync("PoUW가 무엇인지 두 문장으로 설명해줘")
print(result.output)

이것으로 끝입니다. PydanticAI 에이전트가 탈중앙화 네트워크 Gonka를 통해 저렴한 비용으로 작동합니다. run_sync 메서드는 스크립트에 적합하며, 비동기 코드에는 await agent.run(...)을 사용하세요.

모델 파라미터: 네트워크 모델의 컨텍스트 윈도우는 200K 토큰(200000)이며, Gateway를 통한 최대 응답 길이는 최대 8192 토큰입니다. 출력 제한은 모델 설정(OpenAIChatModelSettings(max_tokens=8192))을 통해 가능합니다. 또한 moonshotai/Kimi-K2.6과 MiniMaxAI/MiniMax-M2.7(각각 최대 8192 토큰 출력)도 사용할 수 있습니다. OpenAIChatModel의 첫 번째 인자에서 모델 이름만 바꾸면 됩니다.

PydanticAI를 선택하는 주된 이유는 structured output 때문입니다. 텍스트 응답을 정규식으로 파싱하는 대신, 결과를 Pydantic 모델로 정의하고 output_type 파라미터에 전달합니다. 프레임워크는 모델의 tool calling 기능을 사용하여 데이터가 스키마를 엄격히 준수하도록 강제하고, 검증한 뒤 result.output을 통해 준비된 객체를 반환합니다.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-당신의-키",
    ),
)


class Profile(BaseModel):
    name: str
    role: str
    skills: list[str]


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "데이터 추출: 안나는 백엔드 개발자이며 Python, Go, Postgres를 할 줄 압니다"
)
print(result.output)
# name='안나' role='백엔드 개발자' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — 텍스트가 아닌 list[str] 객체

두 Gonka 모델(Kimi K2.6 및 MiniMax M2.7) 모두 네이티브 tool calling을 지원하므로 가능합니다. PydanticAI는 이를 활용하여 올바른 JSON 구조를 반환합니다. 수동으로 파싱할 필요 없이 타입이 지정된 Python 객체를 얻게 됩니다. 데이터 추출, 분류, 양식 작성 및 결과가 엄격한 형식으로 코드 내에서 이동해야 하는 RAG 파이프라인에 이상적입니다.

PydanticAI는 데이터를 추출하고, 툴을 호출하며, 요청 스트림을 처리하는 등 지속적으로 작동하는 에이전트와 파이프라인을 위한 프레임워크입니다. 여기서는 토큰 비용이 프로젝트의 성공 여부를 결정합니다. 일반적인 부하를 비교해보겠습니다:

비용 차이는 수백에서 수천 배에 이릅니다. 프로토타입 단계에서는 10M 무료 토큰으로 에이전트를 수백 번 실행할 수 있습니다. 하루에 수십만 건의 요청을 처리하는 프로덕션 환경에서는 PydanticAI 코드는 그대로 둔 채 base_url만 변경하여 매달 수만 달러의 비용을 절감할 수 있습니다.

하나의 jg-xxx 키와 잔액으로 OpenAI 포맷(/v1) 및 Anthropic 포맷(/v1/messages)을 모두 사용할 수 있지만, PydanticAI의 경우 위에서 설명한 OpenAI 호환 엔드포인트만으로 충분합니다.

PydanticAI의 두 번째 핵심 기능은 도구입니다. 함수는 데코레이터 @agent.tool_plain (컨텍스트 없음) 또는 @agent.tool (RunContext 및 dependency injection에 액세스 가능)를 사용하여 등록할 수 있습니다. 모델은 도구를 호출할 시기를 스스로 결정하고 결과를 받은 뒤 추론을 계속합니다:

import random
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-당신의-키",
    ),
)

agent = Agent(
    model,
    instructions="당신은 어시스턴트입니다. 필요할 때 도구를 사용하세요.",
)


@agent.tool_plain
def roll_dice() -> str:
    """6면 주사위를 굴리고 결과를 반환합니다."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """수학 식을 계산합니다."""
    return str(eval(expression))


result = agent.run_sync("주사위를 굴리고 결과에 7을 곱하세요")
print(result.output)

Gonka는 tool calling이 네이티브이므로 텍스트 응답을 불안정하게 파싱할 필요 없이 도구가 안정적으로 호출됩니다. 전체 주기(요청 → tool 호출 → 최종 응답)의 비용은 OpenAI/Anthropic의 $0.04~$0.22 대비 Gonka를 통할 경우 약 $0.00007입니다.

모델 선택 가이드: moonshotai/Kimi-K2.6 — 코딩과 복잡한 추론에 강하며 최대 8192까지 출력 가능합니다. MiniMaxAI/MiniMax-M2.7 — 긴 대화와 균형 잡힌 작업에 적합하며 최대 8192까지 출력 가능합니다. 두 모델 모두 하나의 키로 즉시 사용할 수 있으며 모델 문자열만 변경하면 됩니다. 유용한 도구: 체인 및 RAG를 위한 LangChain, 데이터 색인화를 위한 LlamaIndex.