> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> Understand how Harnest turns agent source into a framework-specific, portable server.
Harnest validates your source, lowers it to ADK or LangGraph, and serves it through one neutral runtime.
## The path from source to server
```text theme={null}
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:
```yaml theme={null}
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.
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//plugin.json` | Agent Plugins 1.0 packages with optional skills and MCP servers |
| `extensions//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](/docs/harnest/runtime/serving/provisioning#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 |
Follow each source concept from authoring to discovery.
See the neutral API and production boundary.