Agents

AgentNode agents are installable packages that declare their goal, behavior, tools, and limits in a manifest. How an agent runs depends on trust: by default only trusted and curated agents execute — on the host — while community agents are refused unless you opt into the agent sandbox. LLM access is always mediated host-side.

What is an AgentNode agent?

An agent is a package whose agent: manifest section declares a goal, optional system prompt, an LLM requirement, allowed tools, and run limits. Unlike a tool pack (a single capability) or an MCP server (an external tool process), an agent orchestrates an LLM and tools toward a goal, and runs through its own agent runner.

Agents are installed and inspected like any other package. They are not autonomous by magic: every run is bounded by declared limits, trust policy, and Guard.

Capability tiers

The tier describes what an agent needs. It is independent of the trust level, which decides how the agent is executed (next section).

Execution & trust

An agent's own orchestration code runs on the host (a thread by default, or a child process), not inside the container sandbox. Because of that, the trust gate is what keeps untrusted agent code off your machine:

• Trusted / curated agents run on the host with full host environment access and a bound LLM client. They are policy-checked, not OS-sandboxed.
• Community agents (verified / unverified / unknown) are refused by default — execution requires trust ≥ trusted. They run only if you opt into the agent sandbox, and then sandbox-or-fail-closed (never on the host).
• An agent's tool calls re-enter the normal run_tool gate, so each tool is subject to its own trust, Guard, and sandbox rules — independent of the agent.

Agent sandbox

The agent sandbox is off by default. Enable it to let community agents run, isolated, instead of being refused:

$ agentnode config set agent_sandbox.enabled true
# or, per shell:  export AGENTNODE_AGENT_SANDBOX=1

• When enabled, verified and unverified agents run sandbox-or-fail-closed in the hardened container — if no runtime or image is available, they are blocked, never downgraded to the host.
• LLM calls go through a host-side broker: the provider key stays on the host and never enters the container, audit records, manifests, or lockfiles.
• Trusted and curated agents are unaffected — they continue to run on the host.

Container hardening and the fail-closed model are documented in Execution Sandbox.

llm_access

llm_access governs whether a sandboxed community agent may borrow the host's LLM through the broker. It is default-deny and does not apply to trusted/curated host agents, which use a bound client directly.

The host configuration ceiling (agent_sandbox.llm) always wins: it can lower any cap or force-disable access, and a higher manifest value is clamped to it. Refusals come back as structured per-call errors, never a host fallback.

Tools & policies

• An agent may call only the packs in tool_access.allowed_packages. Omit or null means the full registry; an empty list means no tools (e.g. an llm_only agent).
• Every tool call re-enters run_tool, so trust gating, Guard action policy, input inspection, rate limits, and (for community tools) the sandbox all apply per call.
• The loop is bounded by limits — iterations, tool calls, and wall-clock seconds — so a run always terminates.

The agent manifest

All fields below live under the agent: section and are visible on the package detail page.

agent:
  entrypoint: my_agent.run:run        # module:function
  tier: llm_plus_tools                # llm_only | llm_plus_tools | llm_plus_credentials
  goal: Summarize a PDF and extract action items
  system_prompt: You are a careful research assistant.
  llm:
    required: true
  tool_access:
    allowed_packages:                 # omit/null = full registry; [] = no tools
      - pdf-reader-pack
  limits:
    max_iterations: 12
    max_tool_calls: 40
    max_runtime_seconds: 180
  isolation: thread                   # thread (default) | process

Sandboxed community agents additionally read an llm_access block (above). Optional termination, error_handling.retry, and orchestration blocks tune stopping and retries.

Install, inspect & run

Agents use the same commands as any package. Inspect before running to see trust, permissions, and the policy preview.

$ agentnode install deep-research-agent
$ agentnode inspect deep-research-agent   # trust, permissions, risk, policy preview

from agentnode_sdk import run_tool

result = run_tool(
    "deep-research-agent",
    goal="Compare React vs Vue adoption in 2026",
)
print(result.result)

Honest limits

• Not every agent is sandboxed. The agent sandbox is off by default.
• Trusted and curated agents run on the host with full environment access — policy-checked, not OS-sandboxed.
• The sandbox does not grant arbitrary internet or secrets; it isolates, it does not entitle.
• llm_access, limits, and Guard constrain behavior — they do not make an agent "safe" by themselves. Review the agent and its trust level too.
• When an agent uses a hosted model, that provider still receives the prompts and returns the responses for those calls.

Troubleshooting

Related

• Execution Sandbox — container hardening and the fail-closed model.
• Security Model — what is enforced per trust tier.
• LLM Runtime — how LLM agents register tools and run the tool loop.
• LLM Providers — providers and the host-side binding.
• Credentials & Connectors — where keys live and how the broker uses them.
• AgentNode Guard — per-action policy applied to tool calls.
• Browse the registry — find agents to install.