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)
Phase 2: Initial Providers (parallel after Phase 1)
Phase 3: Agent Integration
Phase 4: Additional Providers (parallel after Phase 3)
Phase 5: Go SDK (separate branch, post-merge)
Compliance & Docs
Stretch
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
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-v2Design document:
docs/design/harness-v2-design.mdDeveloper Experience
Architecture
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)
Phase 2: Initial Providers (parallel after Phase 1)
Phase 3: Agent Integration
Phase 4: Additional Providers (parallel after Phase 3)
Phase 5: Go SDK (separate branch, post-merge)
Compliance & Docs
Stretch
Dependency Graph
Key Design Decisions
.ai()DX exactlyCompletion Criteria
pytestpasses for Python SDKruff check,eslint)feat/harness-v2→mainapproved and merged