Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archal.ai/llms.txt

Use this file to discover all available pages before exploring further.

Archal’s harness is just a subprocess — any language that can read env vars and print to stdout works. This page shows the Python shape. For the full contract see Your first harness.

​
Minimal harness

agent.py
import json
import os
import sys

# 1. Preflight short-circuit.
#    archal runs the harness with ARCHAL_PREFLIGHT=1 before it provisions
#    twins, just to confirm the entrypoint exists.
if os.environ.get("ARCHAL_PREFLIGHT") == "1":
    print("OK")
    sys.exit(0)

# 2. Read the task.
task = os.environ.get("ARCHAL_ENGINE_TASK")
if not task:
    print("Missing ARCHAL_ENGINE_TASK", file=sys.stderr)
    sys.exit(1)

# 3. Call your real agent.
from my_package.agent import run_my_agent
result = run_my_agent(task=task)

# 4. Print the final answer to stdout. Send logs to stderr.
#    Archal prefers structured JSON — one object with a "text" or
#    "payloads" field is the simplest contract. See the TS harness
#    guide for the full extractor precedence order.
print(json.dumps({"text": result if isinstance(result, str) else json.dumps(result)}))

​
.archal.json

Point the agent field at whatever launcher your project uses: 
{
  "agent": "python agent.py",
  "twins": ["github"]
}
Or with uv: 
{
  "agent": "uv run agent.py",
  "twins": ["github"]
}
Or poetry / hatch / etc. — Archal just shells out to this command, so the exact launcher is up to you.

​
Calling services

Use the same service SDKs, domains, and normal credential env vars your agent would use outside Archal. The supervisor-owned proxy routes supported service traffic to the scenario twins. 
import requests

resp = requests.get(
    "https://api.github.com/repos/acme/webapp/issues",
    headers={"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"},
)
SDK clients work the same way. For example, stripe-python should use api.stripe.com and STRIPE_API_KEY; the proxy handles routing.

​
Sanity-check

ARCHAL_PREFLIGHT=1 ARCHAL_ENGINE_TASK="noop" python agent.py
# should print `OK` and exit 0