eat: first-class markdown/file-based agent package loading

[yu-iskw]

Problem Statement

The Antigravity SDK today requires imperative Python to construct LocalAgentConfig — wiring system_instructions, capabilities, MCP servers, policies, subagents, and custom tools by hand. That works for application developers, but it is a poor fit for teams who want to:

• Author agents as version-controlled files (instructions, skills, subagents, policies) reviewable in PRs
• Reuse Markdown-native patterns familiar from Claude Code, Cursor, and Agent Skills (SYSTEM.md, SKILL.md, subagents/*.md)
• Apply governance-as-code (default-deny policies, capability presets) before runtime
• Onboard non-Python contributors (security, compliance, domain experts) to agent behavior without touching SDK constructor code

A reference implementation exists in my personal project antigravity-agentkit, which compiles a declarative agent directory into LocalAgentConfig and runs via the SDK. That proves demand and a viable contract, but the SDK itself has no first-class “agent package” or file-native loading APIs — forcing every declarative layer to reimplement discovery, validation glue, and version-specific feature detection.

Example of the desired authoring model (already working in AgentKit):

my-agent/
├── agent.yaml           # typed manifest (runtime, model, asset pointers)
├── SYSTEM.md            # core system instructions
├── skills/*/SKILL.md    # skill packages (frontmatter + body)
├── subagents/*.md       # local subagent definitions
├── policies.yaml        # tool/MCP governance (allow/deny/ask_user)
└── mcp.json             # MCP server declarations (Claude/Cursor-style)

Minimal manifest:

apiVersion: antigravity-agentkit.dev/v1alpha1
kind: Agent
metadata:
  name: hello-world
spec:
  runtime:
    framework: antigravity
    model: gemini-3.1-flash-lite
  instructions:
    system: SYSTEM.md

Today this compiles to SDK config externally; the SDK does not define or load this package natively.

Proposed Solution

Add first-class, file-native agent authoring primitives to the SDK (runtime layer), with a documented agent package contract. Full packaging, deployment, and enterprise policy packs can remain in AgentKit or a separate companion package.

P0 — Core loaders (SDK)

• Agent.from_directory(path) or equivalent factory that loads a standard agent directory into LocalAgentConfig / Agent
• Markdown instruction loader — load SYSTEM.md (or path from manifest) into system_instructions
• Skill package support — discover skills/**/SKILL.md, map to skills_paths and/or native on-demand skill loading (reduce need for custom read_skill fallbacks)
• Subagent markdown → SubagentConfig — parse frontmatter (name, description, tools) + body as system_instructions
• Policy file loader — YAML/JSON → SDK deny / allow / ask_user policy objects (aligned with hooks docs)
• MCP config loader — accept Claude/Cursor-style mcp.json → McpStdioServer / HTTP MCP types

P1 — Contract & ergonomics

• Publish a stable agent package schema (manifest fields for runtime, capabilities, asset pointers) — can co-develop with AgentKit’s v1alpha1 schema
• Capability presets (restricted, locked, etc.) as documented SDK-level helpers
• Clear errors when SDK version lacks a feature (e.g. static subagents) instead of silent degradation

P2 — Ecosystem (optional / companion)

• Keep packaging, deployment, registry metadata, eval gates in AgentKit or a separate google-antigravity-agentkit package — not required inside core SDK
• Document AgentKit as reference implementation until/if an official companion exists

Success criteria

• A user can create an agent from files alone (no hand-written LocalAgentConfig boilerplate) using SDK APIs
• AgentKit’s compile_to_sdk_config path shrinks to schema validation + thin mapping (not reimplementing loaders)
• README “Quickstart” includes a file-based agent example alongside the current Python-only example

Alternatives Considered

1. Status quo — imperative Python only
   Simplest for SDK maintainers, but every team builds their own declarative layer; AgentKit remains the only structured option.

2. Official companion package only (no SDK changes)
   AgentKit (or a Google-published fork) owns all file loading; SDK stays unchanged.
   Downside: discoverability and long-term duplication of loader logic outside the SDK.

3. Single flat YAML/JSON config mirroring LocalAgentConfig kwargs
   Smaller change, but poor support for skills/subagents progressive disclosure and markdown authoring workflows.

4. Codegen CLI (antigravity init → generated Python)
   Helps bootstrapping but does not keep a single source of truth; generated code drifts from edited markdown.

5. Full declarative loader + ship tooling inside core SDK
   Best single-package DX, but blurs SDK runtime scope with Agent Platform deployment, registry upload, and eval harness concerns better handled by a companion layer.

Additional Context

• Reference implementation: yu-iskw/antigravity-agentkit — compiler/governance layer over this SDK
• AgentKit compile bridge: compile_to_sdk_config() maps declarative IR → LocalAgentConfig (MCP, policies, skills_paths, SubagentConfig, capabilities)
• Known gaps AgentKit works around today:
  • Dual skill loading (read_skill fallback + SDK skills_paths)
  • Subagent prompt injection when SDK lacks SubagentConfig
  • No SDK-native validation or agent directory concept
  • Schema fields for remote subagents / registry skills declared but not yet supported end-to-end
• Related ecosystem: Model Context Protocol, Agent Skills specification
• Non-goals for this request: Agent Platform deployment automation, container packaging, Skill Registry upload — those belong in AgentKit/ship tooling, not core SDK runtime

Happy to contribute schema examples, test fixtures, or a minimal PR against AgentKit’s compile output as a contract reference if helpful.