Architecture

Harnest validates your source, lowers it to ADK or LangGraph, and serves it through one neutral runtime.

The path from source to server

agent source → validate → compile for ADK or LangGraph → artifact → neutral server

Stage	Input	Output
Plan	`orchestrator.py`	Deployment plan JSON
Discover	Agent directories	Validated resources and source digest
Compile	Source plus framework selection	Self-contained artifact under `.harnest/`
Serve	Compiled artifact plus `server.yaml`	HTTP, SSE, WebSocket, and playground surfaces
Deploy	Deployment plan plus artifact	Engine-managed process

orchestrator.py is trusted project code. Rendering a plan imports it. In CI, you can inspect or store the JSON plan before deployment.

Ownership

Owner	What it controls
Your source	Agent behavior and capabilities
`config.yaml`	Framework, mode, entrypoint, runtime environment, and optional `server` overrides
`harnest-deployment.yaml`	Workload resource limits, replicas, backing services, and deployment environment
Compiled `server.yaml`	Generated operational copy of bind, limits, timeout, concurrency, and playground settings
Compiler	Validation, adapters, manifest, digest, and launchers
Runtime	Sessions, checkpoints, auth, telemetry, and transports
Deployment engine	Process lifecycle and deployment environment

Treat .harnest/ as generated output. Commit your source, harnest.lock, and harnest-runtime.lock; regenerate artifacts when the source, Harnest release, or selected framework changes.

Framework boundary

The framework choice is explicit:

spec:
  entrypoint: agent:root_agent
  framework:
    name: adk          # adk | langgraph
    mode: managed      # managed | advanced

Mode	Harnest owns	You own
Managed	Discovery, wiring, framework adapters, and portable runtime behavior	Agent intent and portable source
Advanced	Validation, packaging, and neutral serving	Native framework graph, middleware, state, and framework-specific behavior

The manifest records the framework, mode, versions, and source digest. The runtime rejects mismatches.

Compare ADK and LangGraph

See what moves between frameworks unchanged and what remains framework-native.

Filesystem composition

Harnest uses location to discover capabilities. Public filenames define Python resource identity; Agent Plugins use the name in plugin.json.

Source	Discovered as
`agent.py`	Root agent or graph
`tools/*.py`	Agent Tools
`tasks/*.py`	Queued application tasks
`subagents/`	SubAgents
`mcp/*.py`	MCP connections
`plugins/<folder>/plugin.json`	Agent Plugins 1.0 packages with optional skills and MCP servers
`extensions/<name>/extension.yaml`	Same-process Harnest Extensions
`skills/`	Agent Skills
`lifecycle/*/.py`	Lifecycle behavior
`models/`	Pydantic contracts
`lib/`	Shared Python
`evals/`, `tests/`	Tests and evals

Optional directories may be absent. Invalid or duplicate authored resources fail compilation. Portable Agent Plugins use component-level diagnostics so a bad skill or MCP entry does not disable valid siblings.

Runtime boundary

The neutral runtime keeps common product behavior consistent across ADK and LangGraph.

Concern	Neutral behavior
Identity	One agent card and stable route set
Sessions	User-scoped session state and transcript
Execution	JSON response, durable polling, SSE stream, and live WebSocket
Tools	Server tools, client-hosted tools, MCP tools, and approvals
Storage	Sessions, checkpoints, named assets, and domain repositories
Security	Request principal and invocation-scoped credentials
Observability	Structured logs, traces, and privacy-safe audit events

Use neutral routes for portable behavior. Native routes remain framework-owned.

Deployment plan

Deployment execution requires the process opt-in HARNEST_ENABLE_DEPLOYMENT=true; it is disabled by default. See Enable deployment. Rendering a plan remains available without the flag. An orchestrator selects agent folders and deployment settings. The Go engine receives the JSON plan, compiles each agent, and starts its artifact. The digest covers agent-owned inputs. A pre-rendered plan lets CI inspect the deployment without executing authored Python later.

Safety defaults

Default	Why it exists
Local-only server bind	Avoid accidental network exposure
Strict schemas and unknown-field rejection	Catch configuration drift early
Redacted diagnostics	Keep secrets and payloads out of errors
Bounded requests and pagination	Limit memory and transport abuse
Explicit approval suspension	Resume the exact operation without replaying earlier side effects
Content-free runtime telemetry	Keep prompts, responses, credentials, and raw identifiers out of default traces

Build an agent

Follow each source concept from authoring to discovery.

Serve an agent

See the neutral API and production boundary.

Overview

Get started

Guides

Architecture

The path from source to server

Ownership

Framework boundary

Compare ADK and LangGraph

Filesystem composition

Runtime boundary

Deployment plan

Safety defaults

Build an agent

Serve an agent

​The path from source to server

​Ownership

​Framework boundary

Compare ADK and LangGraph

​Filesystem composition

​Runtime boundary

​Deployment plan

​Safety defaults

Build an agent

Serve an agent

The path from source to server

Ownership

Framework boundary

Filesystem composition

Runtime boundary

Deployment plan

Safety defaults