[SDK] Wire .harness() into Agent class

[santoshkumarradha]

Overview

Wire the harness system into the Agent class: add harness_config constructor parameter, lazy AgentHarness handler, .harness() method, and public exports.

Branch: feat/harness-v2
Design doc: docs/design/harness-v2-design.md (Sections 2, 3.3)

Scope

Python

• sdk/python/agentfield/harness/_handler.py — AgentHarness class:
  • Takes agent_instance in constructor (mirrors AgentAI)
  • Accesses self.agent.harness_config
  • async run(prompt, *, schema, provider, model, ...) → delegates to HarnessRunner
  • Config resolution: harness_config defaults + per-call overrides
• sdk/python/agentfield/agent.py:
  • Add harness_config: Optional[HarnessConfig] = None to __init__ params
  • Store self.harness_config = harness_config
  • Add self._harness_handler: Optional[AgentHarness] = None (lazy)
  • Add harness_handler property (lazy init, mirrors ai_handler)
  • Add async def harness(self, prompt, *, schema=None, provider=None, ...) method
• sdk/python/agentfield/__init__.py — export HarnessConfig, HarnessResult
• Integration tests: full flow Agent → .harness() → mock provider → result

TypeScript

• sdk/typescript/src/harness/handler.ts — HarnessHandler class
• sdk/typescript/src/agent/Agent.ts:
  • Add harnessConfig to constructor options
  • Add .harness() method
• sdk/typescript/src/index.ts — export harness types
• Integration tests

Key Pattern (mirrors .ai())

# agent.py pattern:
@property
def harness_handler(self) -> AgentHarness:
    if self._harness_handler is None:
        from agentfield.harness import AgentHarness
        self._harness_handler = AgentHarness(self)
    return self._harness_handler

async def harness(self, prompt: str, *, schema=None, **kwargs):
    return await self.harness_handler.run(prompt, schema=schema, **kwargs)

Acceptance Criteria

• harness_config accepted in Agent constructor
• .harness() method works with and without constructor config
• Per-call overrides work correctly
• Raises clear error when no provider specified (no config + no per-call)
• Lazy handler only initialized on first .harness() call
• Types exported from package root
• Full integration test passes with mock provider

Dependencies

• Depends on: [SDK] Core types & provider interface for .harness() #199 (types), [SDK] Schema handling with universal file-write strategy for .harness() #200 (schema), [SDK] HarnessRunner with retry & schema orchestration for .harness() #201 (runner), [SDK] Claude Code provider for .harness() #202 (claude) or [SDK] Codex provider for .harness() #203 (codex) — needs at least one real provider
• Blocks: [SDK] Gemini CLI provider for .harness() #205, [SDK] OpenCode provider for .harness() #206

[github-actions]

Thanks for picking this up, @santoshkumarradha! 🎉

Here's what to expect:

• We'll check in after 7 days if we haven't heard an update
• After 14 days, we'll send a second reminder
• After 21 days without activity, we'll unassign to let others contribute

Tips for success:

• Drop a comment when you start working on it
• Share any blockers - we're here to help!
• Link your PR with Fixes #204 in the description

Happy coding! 🚀