직접 모델 연결 (Registry 외)

언제 사용하나

로컬 Ollama로 빠르게 실험할 때
Registry 없이 OpenAI/Anthropic API를 직접 호출해야 할 때
코드가 컴포넌트 ID와 endpoint의 SSOT여야 할 때
Registry HTTP·Kafka가 없는 배포 환경에서 실행할 때

Registry와 code-first Agent의 진입점 차이

Registry 기반 에이전트는 Registry client와 create_registry_runtime_agent() 조립을 거쳐 create_server()로 실행합니다. 코드로 직접 만든 에이전트는 Agent(...)가 모델과 도구를 바로 조립합니다. ID 기반 code-first가 필요하면 Components를 create_runtime_agent(components=...)에 명시적으로 주입합니다. 세 경로는 같은 실행 loop로 수렴하지만 Registry만 HTTP·Kafka hot reload를 사용합니다.

템플릿

uv run llamon agent my-agent --template agent-ollama --yes     # Ollama
uv run llamon agent my-agent --template agent-openai --yes     # OpenAI
uv run llamon agent my-agent --template agent-anthropic --yes  # Anthropic

# 같은 Code-first 템플릿을 명시적 Components catalog 방식으로 생성
uv run llamon agent my-agent --template agent-ollama \
  --runtime-source local --component-source components --yes

템플릿	provider	기본 모델	필수 환경변수
`agent-ollama`	`ollama`	`qwen3`	`OLLAMA_BASE_URL`
`agent-openai`	`openai`	`gpt-4o-mini`	`OPENAI_API_KEY`
`agent-anthropic`	`anthropic`	`claude-3-5-sonnet-latest`	`ANTHROPIC_API_KEY`

기존 agent-local과 agent-structured-local은 각각 agent-ollama와 agent-structured-ollama의 호환 alias로 계속 사용할 수 있습니다.

`app/config.py`

세 템플릿 모두 구조는 같습니다. model, provider, system_prompt만 바꾸면 됩니다.

from llamon_agent.agent import Agent
from app.tools import TOOLS

AGENT = Agent(
    model="qwen3",
    provider="ollama",
    # base_url="http://10.1.1.65:11434",
    system_prompt="당신은 간결하고 정확하게 답변하는 한국어 비서입니다.",
    tools=TOOLS,
)

Ollama 서버가 로컬 기본 주소(http://localhost:11434)가 아닌 원격에 있다면 base_url을 Agent 또는 LLMConfig에 지정합니다. Config와 Agent(...) 생성자 양쪽에 같은 direct 필드를 중복 지정하면 값이 같아도 오류입니다.

from llamon_agent.agent import Agent
from llamon_agent.config import LLMConfig


AGENT = Agent(
    llm=LLMConfig.direct(
        model="qwen3",
        provider="ollama",
        base_url="http://10.1.1.65:11434",
    ),
    system_prompt="당신은 간결하고 정확하게 답변하는 한국어 비서입니다.",
    tools=TOOLS,
)

vLLM 같은 OpenAI-compatible 서버에는 /v1 base URL과 provider="openai"를 명시합니다. 알려진 provider prefix(openai/ 등)만 제거되며, models/Qwen3와 /models/Qwen3 같은 endpoint 고유 모델 경로는 그대로 전달됩니다. 이런 경로 모델은 provider를 추론할 수 없으므로 provider=가 필수입니다.

AGENT = Agent(
    llm=LLMConfig.direct(
        model="/models/Qwen3",
        provider="openai",
        base_url="http://10.0.0.5:8000/v1",
        api_key_env="VLLM_API_KEY",
        provider_flavor="vllm",
    ),
    system_prompt="당신은 간결하고 정확하게 답변하는 한국어 비서입니다.",
    tools=TOOLS,
)

프롬프트 바인딩은 로컬 에이전트에선 Agent(system_prompt_bindings=...), Registry 에이전트에선 PromptConfig(bindings=...) 로 선언합니다 — {{변수}} 치환 문법과 동작은 Registry 기반 에이전트 구성의 bindings 와 동일하고, MCP 연결·도구 등록 패턴도 같습니다.

명시적 Components catalog

여러 Agent·Flow가 같은 ID 체계를 코드로 공유해야 하면 Components를 사용합니다. 파일 이름을 보고 자동 선택하지 않으며, components= 주입이 유일한 authority입니다.

from pathlib import Path

from llamon_agent import Components
from llamon_agent.config import ExtensionConfig, LLMConfig, PromptConfig, PromptSetConfig


COMPONENTS = Components(
    root=Path(__file__).parent,
    llms={
        "primary": LLMConfig.direct(
            model="gpt-4o-mini",
            provider="openai",
            base_url="https://api.openai.com/v1",
            api_key_env="OPENAI_API_KEY",
        ),
        # Anthropic은 provider="anthropic", api_key_env="ANTHROPIC_API_KEY" 사용
    },
    prompts={"system": PromptConfig.from_file("prompts/system.md")},
)

EXTENSION = ExtensionConfig(
    llm=LLMConfig.ref("primary"),
    prompts=PromptSetConfig(system=PromptConfig.ref("system")),
)

runtime_agent, container = await create_runtime_agent(
    extension=EXTENSION,
    components=COMPONENTS,
)
app = await create_server(..., agent=runtime_agent, container=container)

상대 prompt·guardrail 파일은 Components.root만 기준으로 해석됩니다. 기존 Agent(...)의 파일 Config에는 절대 경로만 허용됩니다. Components는 부팅할 때 불변 snapshot으로 복사되므로 파일이나 원본 mapping을 바꿔도 재시작 전에는 반영되지 않습니다.

Registry와 Components를 함께 주입하면 즉시 실패합니다. 선택한 Components mapping에 ref가 없을 때도 field path를 포함해 실패하며 Registry로 자동 fallback하지 않습니다. api_key literal은 Config에 넣을 수 없고 환경 변수 이름인 api_key_env만 사용합니다.

프롬프트: Registry ID vs code-first

Registry 에이전트는 PromptConfig(id="...") 로 Registry에서 본문을 조회합니다. direct Agent는 인라인·절대 파일을 사용하고, Components 경로는 같은 ref 문법을 명시적으로 주입한 mapping에서 해석합니다.

	Registry	direct `Agent`	Components
전역 프롬프트	`PromptConfig.ref("id")`	`Agent(system_prompt="...")`	`PromptConfig.ref("id")` + `Components.prompts`
파일 기준	Registry 저장본	절대 경로	`Components.root` 상대 경로
변경 반영	Registry hot reload	코드 재기동	부팅 snapshot, 재기동

{{변수}} 치환 문법과 bindings 동작은 공급원과 무관하게 같습니다. 자세한 규칙은 Registry 기반 에이전트 구성을 참고하세요.

`.env`

# Ollama
OLLAMA_BASE_URL=http://localhost:11434
# 원격 Ollama 서버를 쓰는 경우:
# OLLAMA_BASE_URL=http://10.1.1.65:11434

# OpenAI / Anthropic은 각각 OPENAI_API_KEY / ANTHROPIC_API_KEY 필요

HOST=0.0.0.0
PORT=8000
LOG_LEVEL=WARNING

전체 환경변수는 환경 설정 → 환경 변수 참조.

빠른 시작 (Ollama 한정)

agent-ollama는 생성부터 실행 확인까지 한 번에 할 수 있습니다.

uv run llamon agent my-agent --template agent-ollama --yes --quickstart

생성된 에이전트는 기본 모델로 qwen3를 씁니다. 첫 채팅 전에 모델이 로컬에 있는지 확인하거나, app/config.py에서 모델명을 바꾸세요.

ollama list
# 필요할 때만:
ollama pull qwen3