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

먼저 키를 발급받으세요: gate.joingonka.ai/register에서 가입하면 무료 토큰 3M개를 드립니다. 가입 후 Dashboard → API Keys에서 jg-xxx 키를 생성하세요.

설치:

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# pip install "pydantic-ai-slim[openai]"

최소 예제 — Gonka를 통한 에이전트. PydanticAI는 OpenAIProvider(base_url=..., api_key=...)로 커스텀 엔드포인트를 지정하고 이를 OpenAIChatModel에 전달합니다:

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-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explain in two sentences what PoUW is")
print(result.output)

이게 전부입니다. 여러분의 PydanticAI 에이전트가 탈중앙화 네트워크 Gonka를 통해 푼돈으로 작동합니다. run_sync 메서드는 스크립트에 편리하고, async 코드에는 await agent.run(...)이 있습니다.

모델 파라미터: MiniMax M2.7의 컨텍스트 윈도우는 180K 토큰(180000), DeepSeek V4 Flash는 380K, GLM-5.3 Flash는 390K입니다. Gateway를 통한 최대 응답 길이는 MiniMax와 GLM-5.3 Flash가 8192 토큰, DeepSeek가 32768 토큰입니다. 출력은 모델 설정(OpenAIChatModelSettings(max_tokens=8192))으로 제한할 수 있습니다. MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash를 사용할 수 있으며, 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-your-key",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extract the data: Anna is a backend developer who knows Python, Go and Postgres"
)
print(result.output)
# name='Anna' role='backend developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — already a list[str], not text

이것이 작동하는 이유는 Gonka의 세 모델(MiniMax M2.7, DeepSeek V4 Flash, GLM-5.3 Flash)이 모두 네이티브 tool calling을 지원하기 때문입니다. PydanticAI는 이를 활용해 유효한 JSON 구조를 반환합니다. 결과로 얻는 것은 수동으로 파싱해야 하는 문자열이 아니라 타입이 지정된 Python 객체입니다. 데이터 추출, 분류, 폼 채우기, 그리고 결과가 엄격한 형식으로 코드에 전달되어야 하는 RAG 파이프라인에 완벽합니다.

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

차이는 수백에서 수천 배에 달합니다. 프로토타입의 경우 3M의 무료 토큰으로 에이전트 초기 구동을 충분히 수행할 수 있습니다. 매일 수십만 건의 요청을 처리하는 프로덕션 환경에서는 동일한 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-your-key",
    ),
)

agent = Agent(
    model,
    instructions="You are an assistant. Use the tools when needed.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Rolls a six-sided die and returns the result."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Evaluates a math expression."""
    return str(eval(expression))


result = agent.run_sync("Roll the die and multiply the result by 7")
print(result.output)

Gonka의 tool calling이 네이티브이기 때문에 도구 호출이 안정적으로 이루어집니다 — 깨지기 쉬운 텍스트 응답 파싱이 필요 없습니다. 전체 사이클(요청 → tool 호출 → 최종 응답)은 Gonka를 통해 약 $0.00007이며, OpenAI/Anthropic은 $0.04~0.22입니다.

어떤 모델을 선택할까: MiniMaxAI/MiniMax-M2.7 — 긴 대화와 균형 잡힌 작업용, 출력 최대 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — 네트워크에서 가장 긴 컨텍스트 중 하나(380K)와 저렴한 대용량 프롬프트, 출력 최대 32768. zai-org/GLM-5.3-Flash — 복잡한 추론을 위한 reasoning 모델이자 네트워크 최장 컨텍스트(390K), 출력 최대 8192; 추론이 max_tokens의 일부를 소비하므로 여유 있게 설정하세요(600 이상). 세 모델 모두 하나의 키로 지금 바로 사용 가능 — 모델 문자열만 바꾸면 됩니다. 관련 도구: 체인과 RAG에는 LangChain, 데이터 인덱싱에는 LlamaIndex.