First Real Model Run

June 8, 2026 ยท View on GitHub

This guide continues from the Quickstart.

The quickstart proved that AgentForge can load .agentforge/, render hello_agent, and return a debug response without credentials.

This step turns debug mode off so the same direct Agent calls a real model provider.

Start From The Quickstart Project

Use the same project that already has:

  • .agentforge/
  • .agentforge/prompts/hello_agent.yaml
  • run_hello_agent.py

The script stays the same:

from agentforge.agent import Agent

result = Agent("hello_agent").run(user_input="AgentForge")
print(result)

Turn Debug Mode Off

Open .agentforge/settings/system.yaml and set debug.mode to false:

debug:
  mode: false

When debug mode is off, AgentForge calls the provider selected in .agentforge/settings/models.yaml.

Default Real Provider: Codex OAuth

The shipped scaffold starts with Codex as the default real model path:

default_model:
  api: openai_api
  model: codex_gpt55

This selects the packaged model_library.openai_api.Codex.models.codex_gpt55 entry. Leave the existing model_library entry in place.

Codex uses OAuth instead of OPENAI_API_KEY.

Verify whether OAuth credentials are already available:

python -m agentforge.init_codex_oauth --check

If the check says credentials are missing, run the interactive login:

python -m agentforge.init_codex_oauth

Run the same script:

python run_hello_agent.py

The output is generated by the model, so the wording will vary.

It should be a real greeting to AgentForge. It should NOT be the exact debug response:

Hello from AgentForge debug mode.

If Codex authentication fails before sending a request, run python -m agentforge.init_codex_oauth --check.

Short Provider Alternatives

Use one of these alternatives only after the debug smoke test works.

For detailed model configuration, see Model Settings. When an example changes only default_model, it assumes the selected model key already exists in the packaged model_library. Do not remove the api -> class -> models -> identifier structure.

OpenAI API Key Models

Set OPENAI_API_KEY, then edit .agentforge/settings/models.yaml:

default_model:
  api: openai_api
  model: gpt4o_model

The packaged gpt4o_model entry points at OpenAI's gpt-4o model. Keep the existing model_library.openai_api.GPT.models.gpt4o_model entry unless you are deliberately changing the provider identifier or parameters.

Gemini

Set GOOGLE_API_KEY, then edit .agentforge/settings/models.yaml:

default_model:
  api: gemini_api
  model: gemini_flash

On macOS or Linux:

export GOOGLE_API_KEY="your-google-api-key"

On Windows PowerShell:

$env:GOOGLE_API_KEY="your-google-api-key"

If GOOGLE_API_KEY is missing, the Gemini call cannot run. The packaged gemini_flash entry lives under model_library.gemini_api.Gemini.models.

Ollama

Ollama does not need a cloud API key, but the Ollama service must be running and the model must be installed.

Check your local models:

ollama list

Edit .agentforge/settings/models.yaml:

default_model:
  api: ollama_api
  model: local_ollama

model_library:
  ollama_api:
    Ollama:
      models:
        local_ollama:
          identifier: qwen3.5:9b

Replace qwen3.5:9b with a model name from your own ollama list.

Keep the existing surrounding model_library entries and the Ollama params block in models.yaml; only the model key and model_library.ollama_api.Ollama.models.<model_key>.identifier need to match your local model.

LM Studio

LM Studio does not need a cloud API key, but its local server must be running.

Start the LM Studio server, load a chat model, then edit .agentforge/settings/models.yaml:

default_model:
  api: lm_studio_api
  model: llama3_8b

model_library:
  lm_studio_api:
    LMStudio:
      models:
        llama3_8b:
          identifier: lmstudio-community/Meta-Llama-3-8B-Instruct-GGUF

If your loaded model uses a different identifier, update the matching model_library.lm_studio_api.LMStudio.models.<model_key>.identifier entry so it matches the model served by LM Studio. For image-capable local models, use the vision class bucket, such as model_library.lm_studio_api.LMStudioVision.models, instead of flattening the model under lm_studio_api. The same pattern applies to vision provider classes such as GeminiVision.

Troubleshooting The First Real Call

  • If you see the debug response, debug.mode is still true.
  • If Codex fails before sending a request, run python -m agentforge.init_codex_oauth --check.
  • If OpenAI API-key models fail before sending a request, check OPENAI_API_KEY.
  • If Gemini fails before sending a request, check GOOGLE_API_KEY.
  • If Ollama or LM Studio fails, make sure the local service is running and the configured model identifier matches an available model.