Harness configuration

archal demo --model gemini-2.5-flash --scenario path/to/your-scenario.md --preflight-only

archal run scenario.md \
  --harness react \
  --agent-model gemini-2.5-flash

archal config set engine.defaultHarness react

archal run scenario.md \
  --harness-dir ./my-agent \
  -n 3

{
  "version": 1,
  "name": "my-harness",
  "description": "Brief description of what this harness does.",
  "defaultModel": "gpt-4.1",
  "promptFiles": ["system-prompt.md", "safety-guidelines.md"],
  "local": {
    "command": "node",
    "args": ["agent.mjs"],
    "env": {
      "MY_CUSTOM_VAR": "value"
    }
  }
}

{
  "version": 1,
  "promptFiles": ["system-prompt.md", "safety-guidelines.md"],
  "local": { "command": "node", "args": ["agent.mjs"] }
}

[Contents of system-prompt.md]

[Contents of safety-guidelines.md]

---

[Scenario prompt]

const TASK = process.env.ARCHAL_ENGINE_TASK;

const messages = [
  {
    role: 'system',
    content: `You are a cautious agent. Never delete anything without confirmation.
Always read before writing. Explain your reasoning.`
  },
  { role: 'user', content: TASK }
];

my-agent/
  agent.mjs
  01-role.md          ← loaded first
  02-safety.md        ← loaded second

export ARCHAL_TEMPERATURE=0.0
archal run scenario.md --harness react --agent-model gpt-4.1

{
  "version": 1,
  "local": {
    "command": "node",
    "args": ["agent.mjs"],
    "env": { "ARCHAL_TEMPERATURE": "0.0" }
  }
}

const temperature = parseFloat(process.env.ARCHAL_TEMPERATURE ?? '0.2');
// Pass to your LLM call

export ARCHAL_MAX_TOKENS=16384

{
  "version": 1,
  "local": {
    "env": { "ARCHAL_MAX_TOKENS": "32768" }
  }
}

# Enable adaptive thinking (default — model decides how much to think)
export ARCHAL_THINKING_BUDGET=adaptive

# Disable thinking entirely
export ARCHAL_THINKING_BUDGET=off

# Set explicit token budget (minimum 1,024)
export ARCHAL_THINKING_BUDGET=8192

# low = fast and cheap, medium = default, high = thorough
export ARCHAL_REASONING_EFFORT=medium

# Set explicit budget (token count, -1 for dynamic)
export ARCHAL_THINKING_BUDGET=4096

// Discover tools
const res = await fetch(`${process.env.ARCHAL_GITHUB_URL}/tools`);
const tools = await res.json();

// Call a tool
const result = await fetch(`${process.env.ARCHAL_GITHUB_URL}/tools/call`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'create_issue', arguments: { title: '...' } }),
});

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const config = JSON.parse(fs.readFileSync(process.env.ARCHAL_MCP_CONFIG, 'utf8'));
const transport = new StreamableHTTPClientTransport(new URL(config.mcpServers.github.url));
const client = new Client({ name: 'my-agent' });
await client.connect(transport);
const { tools } = await client.listTools();

1. Read ARCHAL_ENGINE_TASK
2. Discover tools from twins (REST /tools or MCP listTools)
3. Build initial messages (system prompt + task)
4. Loop:
   a. Call LLM with messages and tools
   b. If no tool calls → done
   c. Execute each tool call against the twin
   d. Append results to messages
   e. Repeat

// agent.mjs
const TASK = process.env.ARCHAL_ENGINE_TASK;
const MODEL = process.env.ARCHAL_ENGINE_MODEL || 'gpt-4.1';
const API_KEY = process.env.OPENAI_API_KEY;

// Discover tools from all twins
const tools = [];
for (const [key, url] of Object.entries(process.env)) {
  const match = key.match(/^ARCHAL_(\w+)_URL$/);
  if (!match || !url) continue;
  const twin = match[1].toLowerCase();
  const res = await fetch(`${url}/tools`);
  for (const tool of await res.json()) {
    tools.push({
      type: 'function',
      function: {
        name: `mcp__${twin}__${tool.name}`,
        description: tool.description,
        parameters: tool.inputSchema,
      },
    });
  }
}

// Agent loop
let messages = [
  { role: 'system', content: 'You are a helpful agent. Use tools to complete the task.' },
  { role: 'user', content: TASK },
];

for (let step = 0; step < 30; step++) {
  const res = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: MODEL, messages, tools, temperature: 0, max_tokens: 16384 }),
  });
  const data = await res.json();
  const choice = data.choices[0];
  messages.push(choice.message);

  if (!choice.message.tool_calls?.length) break; // done

  for (const call of choice.message.tool_calls) {
    const [, twin, toolName] = call.function.name.match(/^mcp__(\w+)__(.+)$/);
    const twinUrl = process.env[`ARCHAL_${twin.toUpperCase()}_URL`];
    const result = await fetch(`${twinUrl}/tools/call`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: toolName, arguments: JSON.parse(call.function.arguments) }),
    });
    messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(await result.json()) });
  }
}

{
  "version": 1,
  "defaultModel": "gpt-4.1",
  "local": { "command": "node", "args": ["agent.mjs"] }
}

archal run scenario.md --harness-dir ./my-agent