Skip to main content
Keep project and server settings together in config.yaml. The Agent Card owns public identity, and pyproject.toml owns dependencies.

​
Fix folder validation errors

Managed feature folders are configuration, not general storage. Harnest checks the files it finds there so that a misplaced file or unfinished declaration does not silently disappear from your agent. Validation errors identify the file and required repair. Prefix notes, backups, and unused examples with _, or move them outside discovery folders. An underscore prefix excludes entries from discovery but does not make invalid code usable. Follow each sample’s activation instructions. Shared Python belongs in lib/; underscore-prefixed modules in lib/ or models/ remain importable. Symlink restrictions still apply. See generated examples and Sandboxing for feature setup.

​
config.yaml

config.yaml selects the entrypoint, framework, authoring mode, Python runtime, environment, secret references, and permissions. harnest init never generates spec.resources or spec.scaling; existing blocks are silently ignored:
Use adk or langgraph. Managed mode is the portable default; advanced mode accepts a native framework target. See ADK and LangGraph. Unknown fields and invalid deployment values fail before authored Python loads. interfaces.cli: true explicitly enables harnest run and the compiled launcher’s run command. Omit it for a server-only artifact. Set CPU, memory, and replicas in harnest-deployment.yaml. Legacy spec.resources and spec.scaling are ignored. The development server does not provision infrastructure, scale replicas, resolve deployment secrets, or enforce network permissions.

Configure a model

Choose the model and endpoint, supply local or deployment credentials, and configure eval model reuse.

​
Retired resource and scaling fields

You can remove these ignored blocks from spec when cleaning up an existing project. Configure any limits you need explicitly: Remove ignored settings and configure only the limits you need. They neither block upgrades nor supply deployment defaults.

​
Server settings in config.yaml

The optional root server: section controls the standalone bind, remote-bind consent, request timeout, concurrency, request-size limit, and playground. Omit the section to use all defaults, or specify only what you want to change:
config.yaml
This enables WebSockets and changes the port. ${NAME} values resolve and undergo type checks at startup. See Server configuration for HTTP limits, defaults, and legacy server.yaml migration.

​
agent-card.yaml

The Agent Card supplies public discovery metadata and declared capabilities. Compilation validates and copies it into the artifact. The server exposes the card at /.well-known/agent-card.json and includes its identity and route links in GET /agent. Declare an A2A interface here when you want to serve the agent through A2A.

​
pyproject.toml and harnest-runtime.lock

Declare only agent-owned provider, tool, and ordinary Python dependencies in pyproject.toml. Do not declare Harnest, ADK, LangGraph, LangChain adapters, or other Harnest-owned framework packages. Each Harnest release supplies and checks a compatible framework version. Synchronize the project environment and commit the resulting lock:
The runtime profile writes hash-verified framework, project, extension, and transitive dependencies to harnest-runtime.lock. It excludes evaluation packages and adds MCP adapters only for active mcp/*.py files. Tests and evaluations use independent dependency profiles and locks:
Development adds pytest; eval adds pytest and ADK evaluation dependencies. Commit the corresponding locks used by CI. These locks are portable and excluded from deployment artifacts. Harnest manages separate environments for running the agent and for testing and evaluating it. When a command is using an interpreter, Harnest can install changed dependencies in an alternate directory for that profile. The running process keeps its original interpreter until it exits. If both directories are in use, stop a command before changing dependencies again. To add a package while harnest serve . --reload is running, use uv add --no-sync 'mcp>=1.26,<2'. This uses the MCP version range supported by Harnest’s adapters. It updates your project dependencies and lets Harnest install them for the new server process. Plain uv add mcp can sync directly into .venv, which may point at the running interpreter. With plain harnest serve, restart to use the new dependency. See development reload and editor setup. CI can require an unchanged committed lock:

​
harnest.lock

harnest.lock records the project schema and the exact framework distribution installed by harnest env sync. A new scaffold starts with the schema only; synchronization adds the resolved version:
harnest.lock
Commit this file alongside the profile locks used by the project. Later environment syncs install the exact resolution, and compilation rejects a different installed framework version before loading agent code. A frozen profile sync requires matching framework and profile locks and leaves them unchanged. It rejects changed dependency inputs before installation. To deliberately resolve a newer supported framework release, remove only the framework entry and run environment sync again, then review and commit the new pin. Changing the selected framework in config.yaml followed by normal sync records the new framework; frozen sync rejects that change. Project schema migrations use harnest upgrade and preserve the framework pin.