Configure a model

Generated agents, eval judges, and text simulators use an OpenAI-compatible API. Choose your own endpoint and model; all calls inherit the Harnest command’s environment.

Variable	Purpose	Default
`OPENAI_MODEL`	Model ID served by your endpoint, including any namespace	Required; no default
`OPENAI_BASE_URL`	OpenAI-compatible API URL, including the API prefix (commonly `/v1`)	Required; no default
`OPENAI_API_KEY`	Optional credential for a protected endpoint	None

Use the shared helper in managed ADK or LangGraph agents:

agent.py

from harnest.agent import Agent
from harnest.model import LiteLLMModel

root_agent = Agent(
    name="support",
    model=LiteLLMModel.from_openai_environment(),
)

Before calling the model, export OPENAI_MODEL and OPENAI_BASE_URL in the shell that runs Harnest, or replace the example values in config.yaml. For local commands, exported settings take precedence over the two generated example values. Explicit project values take precedence over shell settings. If a configured URL reports a connection error, check that the process running Harnest can reach the model server and that the URL includes its API base path. Select a tool-capable model for agents that use Agent Tools. Compilation and offline tests do not contact this endpoint.

OllamaModel has been removed. Replace its import and from_environment() call with LiteLLMModel.from_openai_environment(). Rename OLLAMA_MODEL, OLLAMA_BASE_URL, and any OLLAMA_API_KEY configuration to the OPENAI_ names above. Set the compatible API URL, not the native API root: for a local Ollama server, use http://localhost:11434/v1. Review explicit constructor options against your endpoint’s compatible API; native chat=False is not a compatible chat option. Existing agents require this explicit migration; Harnest does not guess a new endpoint or credential mapping.

After configuring the model and endpoint, run from your agent folder:

Local agent and evals

harnest test . --evals

Set non-secret model configuration in spec.environment or the process environment. spec.environment takes precedence. Harnest neither loads nor packages .env files; use your CI secret store for credentials. For a protected endpoint, export OPENAI_API_KEY before the command or inject it through the deployment engine. If omitted, Harnest sends the non-secret not-required SDK placeholder; this does not grant access to a protected server.

Never put a credential value in spec.environment, agent source, or evals/test_config.json. Those files are authored configuration and can be copied into artifacts or source control.

For a protected deployment endpoint, map the optional credential variable to an opaque secret reference:

config.yaml

spec:
  environment:
    OPENAI_MODEL: your-model
    OPENAI_BASE_URL: https://models.example.invalid/v1
  secrets:
    - environmentVariable: OPENAI_API_KEY
      secretRef: projects/example/secrets/model-api-key/latest

The deployment engine injects secretRef as OPENAI_API_KEY. Local commands require the variable in their process environment. Ensure the deployed agent can reach the endpoint; localhost means its own host or container.

Use explicit model configuration

You can also configure the compatible protocol directly:

import os
from harnest.model import LiteLLMModel

model = LiteLLMModel(
    "openai/team/your-model",
    api_base="https://models.example.invalid/v1",
    api_key=os.getenv("OPENAI_API_KEY") or "not-required",
)

The helper adds the openai/ prefix: team/your-model becomes openai/team/your-model. Explicit api_base and api_key override environment values. For other providers, use LiteLLMModel("provider/model", ...) with that provider’s configuration.

Reuse an agent’s model client

Compatible eval judges and text simulators reuse your LiteLLMModel transport, including lifecycle-owned clients, API URLs, credentials, TLS options, and headers. Generation settings remain independent. Judges and simulators keep their own generation settings. Reusing a transport does not copy the agent’s temperature, sampling, or output options over the authored eval settings. Choosing a transport does not change the eval model ID. For example, an explicitly configured openai/my-judge-model can use an agent’s custom OpenAI-compatible gateway while still requesting my-judge-model.

Available agent transports	Eval behavior
Exactly one binding for the eval’s complete model ID	Reuse that exact binding, even when other same-provider bindings exist
No exact match, but exactly one binding with the same provider prefix	Reuse that provider’s transport with the selected eval model ID
Multiple exact matches, or multiple same-provider matches without an exact match	Fail with an ambiguous-transport error instead of choosing a client
No compatible binding	Use the eval model provider’s normal configuration and credentials

Managed ADK and LangGraph expose these bindings automatically. Advanced ADK can expose Harnest-created bindings through its agent structure; clients hidden in advanced LangGraph closures are not discoverable. Borrowed clients retain their existing owner. Playground evaluations leave serving clients open; CLI evaluations close their own resources.

Eval model overrides and native services

Omitted judge and text-simulator model IDs use OPENAI_MODEL, OPENAI_BASE_URL, and optional OPENAI_API_KEY. Explicit IDs override them and use their selected provider’s credentials. For example, judgeModel: "gemini-2.5-flash" selects native Gemini. Vertex Gen AI evaluation metrics are a separate Google service, not calls to the configured judge model. The ADK evaluation facade uses GOOGLE_API_KEY when set. Otherwise, set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION and make Application Default Credentials available. The cloud_tts audio simulator also uses Application Default Credentials and treats GOOGLE_CLOUD_PROJECT as its quota project when present. OPENAI_API_KEY does not authenticate these native Google services. Keep model and metric selection in source or test_config.json; keep every credential in the process environment or deployment secret mapping.

API reference

Reference: harnest.agent.

Overview

Get started

Harnest Studio

Guides

API reference

Configure a model

Use explicit model configuration

Reuse an agent’s model client

Eval model overrides and native services

API reference

​Use explicit model configuration

​Reuse an agent’s model client

​Eval model overrides and native services

​API reference

Use explicit model configuration

Reuse an agent’s model client

Eval model overrides and native services

API reference