Agent로 시작하기

Hermes 또는 OpenCode를 K-EXAONE 2.5에 연결합니다. 설치부터 모델 설정, 실행까지 순서대로 안내합니다.

Agent 연결하기

K-EXAONE 2.5의 추론과 도구 호출을 agent에 연결하는 방법을 안내합니다. 준비사항을 확인한 뒤 사용할 agent를 선택하세요.

준비사항 · EXAONE API key · Authentication · 작업할 로컬 프로젝트

API key 환경변수 준비

Agent를 실행할 터미널에서, 발급받은 API key를 환경변수로 설정합니다.

export EXAONE_API_KEY="YOUR_API_KEY"

Hermes를 설치합니다.

Linux·macOS·WSL2의 터미널에서 공식 설치 명령을 실행합니다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

공식 설치 안내

EXAONE provider를 등록합니다.

~/.hermes/config.yaml 의 기존 설정에 아래 providers 와 agent 항목을 병합합니다. API key는 EXAONE_API_KEY 환경변수에서 읽습니다.

# 기존 config.yaml의 providers와 agent 항목에 병합합니다.
providers:
  exaone:
    api: https://api.exaone.ai/v1
    key_env: EXAONE_API_KEY
    transport: chat_completions
    default_model: k-exaone_v2.5
    extra_body:
      temperature: 1.0
      top_p: 0.95
agent:
  reasoning_effort: medium

추론 강도 · agent.reasoning_effort에서 low·medium·high·max 중 하나를 지정합니다. 위 예제는 medium을 사용합니다.

모델을 선택하고 Hermes를 실행합니다

hermes model 에서 등록한 exaone provider와 모델을 선택한 뒤, 프로젝트 디렉터리에서 Hermes를 실행합니다.

# 등록한 exaone provider와 모델을 선택합니다.
hermes model

# 작업할 프로젝트 디렉터리에서 시작합니다.
hermes

실행 중인 세션에서 모델 변경

/model custom:exaone:k-exaone_v2.5

간단히 실행해 보기 · 할 일 목록 만들기

입력 파일은 필요 없습니다. 위 모델 설정을 적용한 새 작업 폴더에서 실행합니다.

hermes chat -q \
  "할 일 리스트를 웹페이지로 만들어줘.
   각 할 일은 추가·완료·삭제할 수 있어야 해.
   CSS와 JavaScript를 포함하고, 외부 의존성 없이 브라우저에서 열리게 해줘."

생성된 HTML 파일을 브라우저에서 열어 추가·완료·삭제 기능을 확인합니다.

OpenCode를 설치합니다.

Node.js·npm을 사용할 수 있는 터미널에서 최신 OpenCode를 설치합니다.

npm install -g @opencode/cli

공식 설치 안내

프로젝트에 모델 설정을 추가합니다.

프로젝트의 opencode.json 에 아래 내용을 병합합니다. 연결 정보는 settings , 도구·추론 지원 선언은 capabilities , 모델에 전달할 인자는 body 에 둡니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "exaone/k-exaone_v2.5",
  "providers": {
    "exaone": {
      "package": "@opencode/ai/providers/openai-compatible",
      "name": "EXAONE",
      "settings": {
        "baseURL": "https://api.exaone.ai/v1",
        "apiKey": "{env:EXAONE_API_KEY}"
      },
      "models": {
        "k-exaone_v2.5": {
          "name": "K-EXAONE 2.5",
          "capabilities": {
            "tools": true,
            "input": [
              "text"
            ],
            "output": [
              "text"
            ],
            "temperature": true,
            "reasoning": {
              "supported": true
            }
          },
          "compatibility": {
            "reasoningField": "reasoning_content"
          },
          "body": {
            "reasoning_effort": "medium",
            "temperature": 1.0,
            "top_p": 0.95
          }
        }
      }
    }
  }
}

추론 이력 · compatibility.reasoningField는 스트리밍에서 읽고 다음 요청의 assistant 이력에 다시 담을 reasoning 필드를 지정합니다.

K-EXAONE으로 OpenCode를 실행합니다.

API key 환경변수를 설정한 터미널에서 프로젝트 디렉터리로 이동합니다. --standalone 으로 현재 터미널의 환경변수를 사용하는 서버와 함께 실행하며, 위 설정의 model 을 기본 모델로 사용합니다. 세션 안의 /models 에서도 모델을 선택할 수 있습니다.

opencode --standalone

간단히 실행해 보기 · 할 일 목록 만들기

입력 파일은 필요 없습니다. 위 모델 설정을 적용한 새 작업 폴더에서 실행합니다.

opencode run --standalone \
  --model exaone/k-exaone_v2.5 \
  "할 일 리스트를 웹페이지로 만들어줘.
   각 할 일은 추가·완료·삭제할 수 있어야 해.
   CSS와 JavaScript를 포함하고, 외부 의존성 없이 브라우저에서 열리게 해줘."

생성된 HTML 파일을 브라우저에서 열어 추가·완료·삭제 기능을 확인합니다.

Model Configuration(모델 설정)

reasoning_effort 는 답변을 생성할 때 사용할 추론의 강도를 지정합니다. low → medium → high → max 순으로 높아지며, 응답 시간과 토큰 사용량이 늘어날 수 있습니다.

값	추론 강도	선택 기준
`low`	낮음	간단한 요청에서 빠른 응답을 우선할 때 사용합니다.
`medium`	중간	일반적인 분석·코드 작성에서 응답 시간과 추론의 균형을 고려합니다.
`high`	높음	복잡한 문제 해결이나 디버깅에서 더 깊은 추론을 요청합니다.
`max`	가장 높음	시간보다 충분한 검토를 우선하는 어려운 작업에 사용합니다.

위 연결 예제는 medium 을 사용합니다. Hermes에서는 agent.reasoning_effort , OpenCode에서는 body.reasoning_effort 값을 바꿉니다.

추론 강도와 이력 전달을 구분합니다.

reasoning_effort 는 이번 응답의 추론 강도입니다. 이전 assistant의 reasoning과 tool 호출 이력을 다음 요청에 전달하는 것은 agent의 별도 동작입니다.

생성 설정을 함께 확인합니다.

temperature 와 top_p 는 토큰을 선택하는 sampling 설정입니다. 추론 강도와 구분하며, 대화 이력과 출력이 context 한도에 들어가는지도 고려합니다.

Agent Workflow: Reasoning, Tool calling and Streaming

Agent가 모델 추론, 도구 실행, 다음 요청을 하나의 흐름으로 연결합니다. 연동할 때는 아래 세 가지 흐름이 정상적으로 동작하는지 확인하세요.

Reasoning	`reasoning_effort` 로 추론 강도를 지정합니다. 추론 스트리밍과 다음 요청으로의 reasoning 이력 전달은 각각 확인합니다.
Tool calling	모델이 반환한 호출을 harness가 실행하고 결과를 다시 전달합니다. 도구를 한 번 호출한 뒤 최종 답변까지 이어지는지 확인합니다.
Streaming	텍스트·reasoning·tool calling delta를 harness가 처리합니다. tool 인자가 완성된 뒤 실행되는지, 다음 턴까지 이어지는지 확인합니다.

직접 API를 사용할 때는 stream: true 로 스트리밍을 요청합니다. Harness의 스트리밍은 해당 버전의 실행 경로에서 확인합니다.

이어서 살펴보기

OpenAI 호환 EXAONE API와 함께 사용할 수 있는 외부 agent는 다음과 같습니다.

Hermes · Custom provider ↗	provider 등록·추가 인자
OpenCode · Custom provider ↗	provider 등록·요청 body
OpenCode · Models & Reasoning ↗	모델 기능·추론 이력