The .harness() method dispatches coding tasks to external coding agent providers. Each provider has its own authentication requirements, subscription levels, and Terms of Service. This guide covers what you need to know before using each provider.

How Credentials Work

When you call .harness(), AgentField passes your credentials to the provider through environment variables or SDK configuration. Credentials are:

• Never stored by the harness module
• Never logged in any harness output or logs
• Never proxied through AgentField servers
• Forwarded directly to the provider's own SDK or CLI process

You supply credentials via the env parameter on HarnessConfig or per-call, or by setting the appropriate environment variables in your runtime environment.

from agentfield import Agent, HarnessConfig

# Option 1: Credentials already in your shell environment
app = Agent(
    node_id="my-agent",
    harness_config=HarnessConfig(provider="claude-code"),
)

# Option 2: Pass credentials explicitly
app = Agent(
    node_id="my-agent",
    harness_config=HarnessConfig(
        provider="gemini",
        env={"GEMINI_API_KEY": "your-key-here"},
    ),
)

Provider Reference

Claude Code

Provider name: "claude-code"

Integration method: Native Python SDK (claude_agent_sdk)

Authentication:

• Requires an Anthropic API key (ANTHROPIC_API_KEY environment variable)
• Users must use API key authentication — Anthropic does not allow third-party developers to offer claude.ai login or rate limits for their products
• No API key resale permitted

Subscription requirements:

• Active Anthropic API account with billing enabled
• API usage billed per-token by Anthropic

Headless mode:

• The claude_agent_sdk is explicitly designed for programmatic/embedding use
• AgentField uses the SDK's query() function with streaming message collection
• Supported flags: model, cwd, max_turns, allowed_tools, system_prompt, max_budget_usd, permission_mode, env

Terms of Service:

• Governed by the Anthropic Commercial Terms
• Branding: Cannot name your product "Claude Code" — use "Powered by Claude" or similar if referencing the underlying model

Codex CLI

Provider name: "codex"

Integration method: CLI subprocess (codex exec --json)

Authentication:

• Requires a ChatGPT subscription (Plus, Pro, Business, Edu, or Enterprise) or a CODEX_API_KEY
• Each user must bring their own credentials — no API key resale

Subscription requirements:

• ChatGPT Plus ($20/mo), Pro ($200/mo), Business, Edu, or Enterprise plan
• Or a standalone CODEX_API_KEY with active billing

Headless mode:

• codex exec is officially designed for programmatic use (CI/CD, scripts, embedding)
• AgentField uses --json for structured JSONL output and --full-auto for unattended execution
• Git repo required by default — use --skip-git-repo-check for non-repo directories

Terms of Service:

• Governed by the OpenAI Services Agreement

Gemini CLI

Provider name: "gemini"

Integration method: CLI subprocess (gemini)

Authentication:

• Requires a Gemini API key (GEMINI_API_KEY environment variable)
• Get your key at Google AI Studio

Subscription requirements:

• Free tier available with rate limits
• Paid tier for higher throughput

Headless mode:

• Gemini CLI auto-triggers headless mode in non-TTY environments or with positional arguments
• The CLI itself is Apache 2.0 licensed — freely wrappable
• AgentField invokes it with -p for prompt input and -m for model selection

Terms of Service:

• CLI is Apache 2.0 (open source)
• API usage governed by the Google Gemini API Terms of Service

OpenCode

Provider name: "opencode"

Integration method: CLI subprocess (opencode run)

Authentication:

• OpenCode itself is MIT licensed — no restrictions on programmatic use
• Authentication depends on the underlying LLM provider the user configures in OpenCode (e.g., Anthropic, OpenAI, Google)
• Set up your provider credentials in OpenCode's configuration

Subscription requirements:

• OpenCode is free and open source
• Costs depend on the LLM provider configured within OpenCode

Headless mode:

• Multiple programmatic interfaces: opencode run (CLI), opencode serve (HTTP), @opencode-ai/sdk (Node.js), ACP protocol
• AgentField uses opencode run with --model and --dir flags
• Concurrency is managed by AgentField (default: 3 concurrent processes, configurable via OPENCODE_MAX_CONCURRENT)

Terms of Service:

• OpenCode itself: MIT License — zero restrictions
• Underlying provider ToS applies based on configured model

Quick Reference

Error Messages & Troubleshooting

When a provider fails, AgentField returns structured error messages. Common issues:

Security Best Practices

1. Use environment variables for API keys — never hardcode them in source files
2. Use secret managers (AWS Secrets Manager, HashiCorp Vault, etc.) in production
3. Rotate keys regularly according to each provider's recommendations
4. Scope permissions — use API keys with minimum required permissions
5. Monitor usage — set up billing alerts with each provider to catch unexpected costs