[Epic] .harness() — First-class coding agent integration for AgentField SDKs #208
Description
Overview
Add .harness() as a first-class method on the Agent class — matching the DX of .ai() — enabling developers to dispatch multi-turn coding tasks to external coding agents (Claude Code, Codex, Gemini CLI, OpenCode) with schema-constrained structured output.
Feature branch: feat/harness-v2
Design document: docs/design/harness-v2-design.md
Developer Experience
from agentfield import Agent, HarnessConfig
from pydantic import BaseModel
class BugFix(BaseModel):
files_changed: list[str]
summary: str
tests_added: bool
app = Agent(
node_id="my-agent",
harness_config=HarnessConfig(provider="claude-code", model="sonnet"),
)
fix = await app.harness(
"Fix the auth bug and add tests",
schema=BugFix,
cwd="/my/project",
)
print(fix.files_changed) # ["src/auth.py", "tests/test_auth.py"]Architecture
Agent
├── .ai() → AIConfig → LiteLLM → LLM APIs (100+ providers)
└── .harness() → HarnessConfig → HarnessRunner → Provider → {Claude Code, Codex, Gemini, OpenCode}
Schema strategy: Universal file-write (agent writes JSON to {cwd}/.agentfield_output.json) with 4-layer recovery (parse → cosmetic repair → follow-up prompt → full retry).
Sub-Issues (Execution Order)
Phase 1: Core Foundation (sequential)
- [SDK] Core types & provider interface for .harness() #199 — Core types & provider interface (Python + TS)
- [SDK] Schema handling with universal file-write strategy for .harness() #200 — Schema handling with file-write strategy (Python + TS)
- [SDK] HarnessRunner with retry & schema orchestration for .harness() #201 — HarnessRunner with retry & schema orchestration (Python + TS)
Phase 2: Initial Providers (parallel after Phase 1)
- [SDK] Claude Code provider for .harness() #202 — Claude Code provider (Python SDK + TS SDK)
- [SDK] Codex provider for .harness() #203 — Codex provider (Python CLI + TS SDK)
Phase 3: Agent Integration
- [SDK] Wire .harness() into Agent class #204 — Wire .harness() into Agent class (Python + TS)
Phase 4: Additional Providers (parallel after Phase 3)
- [SDK] Gemini CLI provider for .harness() #205 — Gemini CLI provider (Python + TS)
- [SDK] OpenCode provider for .harness() #206 — OpenCode provider (Python + TS)
Phase 5: Go SDK (separate branch, post-merge)
- [Go SDK] Port .harness() to Go SDK #207 — Port .harness() to Go SDK
Compliance & Docs
- [SDK] TOS compliance & headless mode requirements for .harness() providers #209 — TOS compliance & headless mode requirements
- Documentation: Agent-Field/website-docs#32 (private repo)
Stretch
- Aider provider (pending research on headless mode)
Dependency Graph
#199 (types) ──┬──→ #200 (schema) ──→ #201 (runner) ──┬──→ #202 (claude) ──┐
│ └──→ #203 (codex) ──┤──→ #204 (agent wiring) ──┬──→ #205 (gemini)
│ │ └──→ #206 (opencode)
└────────────────────────────────────────────────────────────┘
#207 (Go SDK) ← after merge
Key Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Schema handling | Universal file-write | One code path for all 4 providers; large schemas can exceed response token limits |
| Provider requirement | Explicit (no default) | Prevents accidental billing; makes provider choice intentional |
| SDK vs CLI | SDK-first where available | In-process execution, better error handling, richer API |
| Config pattern | Constructor + per-call overrides | Matches .ai() DX exactly |
| Return type | Final result only | Simple DX; streaming can be added later |
Completion Criteria
- All Phase 1-4 sub-issues resolved
-
pytestpasses for Python SDK - TypeScript tests pass
- No lint errors (
ruff check,eslint) - Design doc updated and accurate
- PR from
feat/harness-v2→mainapproved and merged - Go SDK issue [Go SDK] Port .harness() to Go SDK #207 created and referenced