feat: CLI --agent mode for agent-optimized output

[santoshkumarradha]

feat: CLI --agent mode for agent-optimized output

Summary

Add af --agent <command> global flag that switches all CLI output to agent-optimized JSON — no ANSI colors, no tables, no interactive prompts. This is Phase 4 of the Agentic API Layer epic (#282).

Motivation

AI agents (Claude Code, Cursor, Codex, custom harnesses) need to operate the AgentField control plane programmatically. They may:

• Not have environment variables set in their sandbox
• Manage multiple control planes (dev/staging/prod)
• Need structured, parseable output with response schemas
• Need actionable error messages with self-correction hints

Global Flags (New)

Flag	Short	Type	Default	Description
--agent	—	bool	false	Enable agent mode (JSON output, no ANSI, no prompts)
--server	-s	string	http://localhost:8080	Control plane URL. Resolution: flag > AGENTFIELD_SERVER env > config > default
--api-key	-k	string	—	API key for authenticated endpoints. Resolution: flag > AGENTFIELD_API_KEY env > config
--output	-o	string	json	Output format: json (default in agent mode), compact, jsonl
--timeout	-t	duration	30s	Request timeout

Agent Subcommands

Command	Description	Key Flags
af --agent status	System health check	—
af --agent discover	Search API endpoints	--query/-q, --group/-g, --method
af --agent query	Query resources	--resource/-r, --status, --agent-id, --since, --until, --limit, --include
af --agent run --id <run_id>	Get run overview	--id (required)
af --agent kb topics	List KB topics	—
af --agent kb search --query <q>	Search KB articles	--query/-q
af --agent kb read --id <id>	Read KB article	--id (required)
af --agent kb guide --goal <goal>	Goal-oriented reading path	--goal (required)
af --agent batch --file <path>	Batch operations	--file/-f or stdin

DX Requirements

1. Structured JSON Help

When --agent is active, --help returns parseable JSON instead of cobra prose:

{
  "command": "af --agent",
  "description": "Agent-optimized CLI mode. All output is JSON.",
  "subcommands": [
    {
      "name": "discover",
      "description": "Search available API endpoints",
      "flags": [
        {"name": "--query", "short": "-q", "type": "string", "required": true}
      ],
      "example": "af --agent discover --query 'list agents'",
      "response_schema": {"ok": "bool", "data": {"endpoints": "[...]"}}
    }
  ],
  "global_flags": [
    {"name": "--server", "short": "-s", "type": "string", "default": "http://localhost:8080"}
  ]
}

2. Actionable Error Hints

Every error in agent mode includes a hint field for LLM self-correction:

{
  "ok": false,
  "error": {
    "code": "CONNECTION_REFUSED",
    "message": "Cannot reach control plane at http://localhost:8080",
    "hint": "Is the control plane running? Try: af server --port 8080",
    "retry": true
  }
}

3. Response Envelope

All responses use the existing AgenticResponse envelope:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "token_estimate": 450,
    "hint": "Use --include=tools for full agent details"
  }
}

4. Multi-Control-Plane Support

# Target different environments
af --server http://prod:8080 --api-key sk-prod --agent status
af --server http://staging:9090 --api-key sk-stg --agent query --resource agents
af -s http://localhost:8080 --agent discover --query "execute"

DX Fixes (included in this PR)

1. Fix af dev hardcoded port: startDevProcess() hardcodes AGENTFIELD_SERVER_URL=http://localhost:8080 — must read actual control plane port
2. Python SDK reads AGENTFIELD_SERVER env var: SDK should check env var as fallback when no explicit agentfield_server param is passed
3. Control plane port conflict detection: Use existing PortManager.IsPortAvailable() before binding

Files to Modify

• internal/cli/root.go — Add --agent, --server, --api-key, --output, --timeout persistent flags
• New: internal/cli/agent_commands.go — All agent subcommands
• New: internal/cli/agent_help.go — Structured JSON help renderer
• New: internal/cli/agent_errors.go — Agent-mode error handler
• internal/cli/dev.go — Fix hardcoded port in startDevProcess()
• sdk/python/src/agentfield/agent.py — Read AGENTFIELD_SERVER env var
• New: internal/cli/agent_commands_test.go — Tests

Acceptance Criteria

• af --agent status returns valid JSON with system health
• af --agent discover --query "execute" returns matching endpoints
• af --agent query --resource agents returns agent list
• af --agent kb guide --goal "submit a job" returns step-by-step with CLI commands
• af --agent --help returns structured JSON with all subcommands and response schemas
• af --server http://other:9090 --agent status targets the specified control plane
• af --api-key sk-xxx --agent query --resource runs authenticates via API key
• All errors in agent mode are structured JSON with hint field
• af dev reads actual control plane port (not hardcoded 8080)
• Python SDK reads AGENTFIELD_SERVER env var as fallback
• All existing tests pass
• New tests for agent commands pass

Dependencies

• ✅ Phase 1-3 (PR feat: Agentic API Layer — Smart 404, Discovery, Query, Knowledge Base #283) — Agentic API endpoints
• Closes feat: CLI --agent mode for agent-optimized output #281
• Part of epic EPIC: Agentic API Layer — Self-Documenting Control Plane for AI Agents #282

The "Agentic Handshake" — Expected First Contact Flow

# 1. Agent discovers what's available
af --agent status

# 2. Agent explores endpoints
af --agent discover --query ""

# 3. Agent reads relevant KB
af --agent kb guide --goal "submit and track an agent job"

# 4. Agent operates
af --server http://localhost:8080 --api-key sk-xxx --agent query --resource runs --status running