Using AgentForge

This guide explains the setup boundaries AgentForge uses when your script runs.

Use it when you need to understand where .agentforge/ belongs, how AgentForge finds it, when debug mode is useful, and when provider setup begins.

For the recommended first-run order, start from the AgentForge Documentation hub.

Setup Boundary

AgentForge reads consumer-owned resources from a .agentforge/ directory.

Run the scaffold command from the root of the project that should own those resources:

python -m agentforge.init_agentforge

When AgentForge starts, it finds the active project root in this order:

An explicit Config(root_path=...) or Config.reset(root_path=...) call.
The AGENTFORGE_ROOT environment variable.
Auto-discovery walking upward from the running script until it finds .agentforge/.

Most beginners should scaffold .agentforge/ in the project root and run scripts from that project.

Use AGENTFORGE_ROOT=/path/to/project when your script lives somewhere else or you want the project root to be unambiguous.

Use explicit Config(root_path=...) or Config.reset(root_path=...) only when you are writing advanced setup code, tests, or deterministic tooling.

The first setup check should not require provider credentials.

AgentForge's debug mode returns a simulated response instead of calling a provider, so it is the right boundary for a smoke test.

Use debug mode to prove that Python imports, .agentforge/ discovery, prompt loading, and direct Agent execution all work.

Real provider calls require either Codex OAuth, API keys, or a running local model service.

The shipped scaffold's default real model path is:

default_model:
  api: openai_api
  model: codex_gpt55

Initialize Codex OAuth before using that default real-model path:

python -m agentforge.init_codex_oauth

Provider setup belongs in First Real Model Run, not in the no-credential quickstart.

The reference docs remain available for intentional extension points and advanced workflows.

Start from Advanced Reference when you are not sure which reference page you need:

Internal AgentForge development guidance is kept in dev-docs/, not in the public beginner path.