ModelConfig — 모델 연결

다른 이름: ModelConfig · apiKeySecret · OpenAI-compatible · LiteLLM baseUrl · apiKeyPassthrough

결론부터

ModelConfig는 “어느 provider의 어느 모델을 어느 key로 부를지”를 Agent와 따로 선언한 리소스다. Agent는 이름으로 참조만 한다.
사내 LiteLLM은 provider: OpenAI에 openAI.baseUrl을 주어 연결한다.
API key는 Secret 이름으로만 참조한다. Secret을 바꾸면 그 key를 쓰는 Agent가 자동으로 재시작된다.
gateway 뒤의 모델은 tool calling을 지원해야 한다. kagent는 모든 요청에 tool 목록을 실어 보낸다.

이 장에서 처음 나오는 말3개

providerModel Provider: 모델 API를 제공하는 쪽이다. OpenAI·Anthropic·Bedrock·Ollama 등이 있고 ModelConfig의 provider로 고른다.
OpenAI-compatibleOpenAI 호환 API: OpenAI의 요청·응답 형식을 그대로 받는 다른 서버다. LiteLLM·vLLM이 이 형식을 제공해서 kagent에서는 OpenAI provider로 연결한다.
tool calling: 모델이 "이 tool을 이 인자로 불러 달라"는 구조화된 응답을 돌려주는 기능이다. Agent가 tool을 쓰려면 모델이 지원해야 한다.

Agent마다 모델 주소와 key를 적으면, 모델을 바꾸거나 key를 교체할 때 Agent를 전부 고쳐야 한다. ModelConfig는 이 설정을 한 곳에 모으고 Agent가 modelConfig: <이름>으로 가리키게 한다. 플랫폼 팀이 ModelConfig를, Agent 작성자가 Agent를 소유하도록 나눌 수 있다는 점이 실용적인 이득이다.

사내 LiteLLM을 연결하는 모양

kagent가 직접 지원하는 provider는 Anthropic·OpenAI·AzureOpenAI·Ollama·Gemini·GeminiVertexAI·AnthropicVertexAI· Bedrock·SAPAICore·Foundry다(API reference). 사내 gateway는 이 중 OpenAI provider에 baseUrl을 바꿔 붙인다 (BYO OpenAI-compatible).

# 설명용 예제
apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: litellm-default
  namespace: agents
spec:
  provider: OpenAI
  model: gpt-oss-120b            # gateway가 routing에 쓰는 모델 식별자
  apiKeySecret: litellm-agent-key
  apiKeySecretKey: api-key
  openAI:
    baseUrl: https://litellm.example.com/v1

필드	뜻
`provider`	OpenAI 호환 서버는 `OpenAI`로 둔다
`model`	gateway가 받는 모델 이름. vLLM 내부 이름과 다를 수 있다
`apiKeySecret` · `apiKeySecretKey`	key가 든 Secret 이름과 그 안의 key. `ModelConfig`와 같은 namespace여야 한다
`openAI.baseUrl`	gateway 주소. LiteLLM은 보통 `/v1`까지 적는다

apiKeySecret에 넣는 값은 provider의 원본 key가 아니라 LiteLLM이 발급한 virtual key로 둔다. key별 예산과 모델 제한은 LiteLLM 덱의 범위다.

놓치기 쉬운 조건 두 가지

모델이 tool calling을 지원해야 한다

kagent runtime은 모든 Agent에 ask_user tool을 자동으로 붙인다. 그래서 tool을 하나도 선언하지 않은 Agent도 요청마다 tools 배열과 tool_choice: "auto"를 보낸다. gateway 뒤의 vLLM이 자동 tool 선택을 켜지 않았으면 모든 대화가 status 400으로 실패한다 (공식 문서의 vLLM 절). 증상이 Agent 쪽에서 보이지만 원인은 모델 서버 설정이다.

사내 CA는 `tls`로 준다

LiteLLM이 사내 CA로 서명한 인증서를 쓰면 Agent Pod가 인증서를 믿지 못해 연결이 실패한다. ModelConfig의 tls에 CA Secret을 지정한다. 이 설정은 OpenAI 호환 provider에서만 지원된다.

# 발췌
spec:
  tls:
    caCertSecretRef: corp-ca
    caCertSecretKey: ca.crt

disableVerify: true는 검증을 통째로 끄므로 운영에서 쓰지 않는다. disableSystemCAs: true는 지정한 CA만 믿게 한다. 같은 tls 구조를 RemoteMCPServer도 쓴다.

key 교체와 재시작

Secret의 값을 바꾸면 kagent가 그 Secret을 참조하는 Agent를 자동으로 재시작한다 (Operational considerations). ModelConfig가 참조하는 API key, TLS CA, Agent Deployment의 secretKeyRef 환경 변수가 대상이다. key를 회전할 때 Agent manifest를 건드릴 필요가 없다.

기본 ModelConfig는 chart가 만든다

Helm 설치는 providers.default로 고른 provider의 default-model-config와 Secret을 만든다. 이 값을 직접 고치면 다음 Helm upgrade에서 되돌아간다. ModelConfig를 Git으로 관리할 계획이면 chart가 만들지 않게 끈다 (Disable the default ModelConfig).

# kagent chart values
providers: null

임직원 토큰을 모델 key로 쓰는 선택지

apiKeyPassthrough: true는 A2A 요청에 실려 온 Bearer token을 모델 provider의 API key로 그대로 넘긴다. apiKeySecret과 함께 쓸 수 없다. 모델 gateway가 임직원 토큰을 직접 인증·과금 단위로 받을 때만 의미가 있다.

LiteLLM virtual key로 Agent 단위 예산을 관리하는 구성이라면 기본 선택은 apiKeySecret이다. 이 필드는 임직원 토큰 전파의 MCP 쪽 전파와는 별개 설정이라는 점만 기억한다.

이해 확인

agents namespace의 Agent가 kagent namespace의 ModelConfig를 참조할 수 있는가? → 없다. modelConfig는 Agent와 같은 namespace에서 찾는다. namespace마다 ModelConfig와 Secret을 둔다.
tool이 없는 Agent인데 첫 메시지부터 provider API error (status 400)이 난다. 어디를 보는가? → 모델 서버의 tool calling 설정. kagent는 ask_user 때문에 항상 tools를 보낸다.

Tool 연결 — MCP 서버와 다른 AgentAgent가 쓸 수 있는 tool을 어떤 리소스로 가리키고, 어떻게 좁히는지 본다.