Skip to main content

agentnode-sdk

Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents.

Installation

pip install agentnode-sdk

Quick Start — LLM Agent Runtime

Connect any LLM agent to AgentNode in three lines. The Runtime provides tool definitions, system prompt, and a tool-loop engine. Tested across 22 models — works with OpenAI, Anthropic, Gemini, Mistral, DeepSeek, Qwen, Llama, and more.

from agentnode_sdk import AgentNodeRuntime

runtime = AgentNodeRuntime()

# Get tools + system prompt for your provider
bundle = runtime.tool_bundle()
# → { "tools": [...], "system_prompt": "..." }

OpenAI

from openai import OpenAI
from agentnode_sdk import AgentNodeRuntime

runtime = AgentNodeRuntime()
client = OpenAI()

result = runtime.run(
    provider="openai",
    client=client,
    model="gpt-4o",
    messages=[{"role": "user", "content": "Count the words in 'Hello world'"}],
)
print(result.content)

Anthropic

from anthropic import Anthropic
from agentnode_sdk import AgentNodeRuntime

runtime = AgentNodeRuntime()
client = Anthropic()

result = runtime.run(
    provider="anthropic",
    client=client,
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Search for PDF tools on AgentNode"}],
)

Gemini

from google import genai
from agentnode_sdk import AgentNodeRuntime

runtime = AgentNodeRuntime()
client = genai.Client()

result = runtime.run(
    provider="gemini",
    client=client,
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "What AgentNode tools are available?"}],
)

OpenRouter (Mistral, DeepSeek, Qwen, Llama, and more)

Use any OpenAI-compatible provider by passing a custom base_url:

from openai import OpenAI
from agentnode_sdk import AgentNodeRuntime

runtime = AgentNodeRuntime()
client = OpenAI(
    api_key="sk-or-...",
    base_url="https://openrouter.ai/api/v1",
)

result = runtime.run(
    provider="openai",
    client=client,
    model="mistralai/mistral-large",  # or deepseek/deepseek-chat, qwen/qwen-plus, etc.
    messages=[{"role": "user", "content": "Find and install a PDF reader tool"}],
)

Generic / Manual Tool Calling

For any provider that supports tool calling, use handle() to dispatch calls manually:

runtime = AgentNodeRuntime()

# Get tool definitions in your provider's format
tools = runtime.as_openai_tools()   # OpenAI format
tools = runtime.as_anthropic_tools() # Anthropic format
tools = runtime.as_gemini_tools()    # Gemini format
tools = runtime.as_generic_tools()   # Generic format

# When the LLM makes a tool call, dispatch it:
result = runtime.handle("agentnode_search", {"query": "pdf extraction"})
# → {"success": true, "result": {"total": 5, "results": [...]}}

CLI

The agentnode CLI is the human interface. Single commands, multi-step tasks, diagnostics.

# Search & install
agentnode search "pdf extraction"
agentnode install pdf-reader-pack

# Run a single task (natural language)
agentnode run "extract text from report.pdf"

# Multi-step: pipe output between capabilities automatically
agentnode run "extract text from report.pdf then translate to german"

# Preview without executing
agentnode run "search for AI news then summarize" --dry-run

# Show reasoning
agentnode run "search for AI news" --explain

# Diagnostics
agentnode doctor              # detect missing capabilities, suggest packages
agentnode doctor --fix         # auto-install suggestions
agentnode recommend            # prioritized recommendations based on installed setup
agentnode audit                # recent policy decisions (allow/deny/prompt)
agentnode inspect pdf-reader-pack  # security report: trust, permissions, audit history

# Credentials & config
agentnode auth set openai
agentnode auth status
agentnode config list

All commands support --json for structured output.

Note: Multi-step runs respect your config:

  • install_confirmation: prompt will ask before installing missing packages
  • Low-confidence steps require confirmation (or abort in non-interactive mode)

Three Surfaces

CLI           → for humans (search, install, run, diagnose)
SDK / Client  → for programmatic access (search, resolve, install, run)
Runtime       → for LLM agents (tool registration, dispatch, auto-loop)

API Reference

AgentNodeRuntime

Zero-config LLM agent integration.

Method Description
tool_specs() Internal typed tool definitions (list[ToolSpec])
as_openai_tools() Tools in OpenAI function-calling format
as_anthropic_tools() Tools in Anthropic format
as_generic_tools() Tools in generic/baseline format
system_prompt() AgentNode system prompt block (append to yours)
tool_bundle() Combined {"tools": [...], "system_prompt": "..."}
handle(tool_name, arguments) Dispatch a tool call. Returns dict. Never throws.
run(provider, client, messages, model, ...) Auto-loop with tool dispatch. Never throws.

Constructor:

AgentNodeRuntime(
    client=None,                     # Optional AgentNodeClient
    api_key=None,                    # Optional API key
    minimum_trust_level="verified",  # "verified" | "trusted" | "curated"
)

5 Meta-Tools (automatically registered):

Tool Description
agentnode_capabilities List installed packages (local, no API call)
agentnode_search Search the registry (max 5 results)
agentnode_install Install a package by slug
agentnode_run Execute an installed tool
agentnode_acquire Search + install in one step

AgentNodeClient

The programmatic client with typed return models.

Method Description
search(query, ...) Search packages by keyword or capability
resolve(capabilities, ...) Resolve capability gaps to ranked packages
install(slug, ...) Download, verify, and install locally
resolve_and_install(capabilities, ...) Resolve + install in one call
run_tool(slug, tool_name=, ...) Run a tool with trust-aware isolation
smart_run(fn, ...) Wrap logic with auto-detect, install, retry
detect_and_install(error, ...) Detect capability gap and install

run_tool() (standalone)

Top-level function for running tools with process isolation.

from agentnode_sdk import run_tool

result = run_tool("pdf-reader-pack", mode="auto", file_path="report.pdf")
# result.success, result.result, result.error, result.mode_used, result.duration_ms
# result.policy  → {"action": "allow", "reason": "...", "source": "..."}
# result.to_dict()  → structured output for --json

Isolation contract. mode="auto" always resolves to subprocess, regardless of the package's trust level. This makes the isolation guarantee true by default. If you need in-process execution (for example, to share module-level state with the tool), pass mode="direct" explicitly — that is an opt-in performance trade-off, not a default.

get_risk_profile() (standalone)

Usage risk assessment for installed packages. Separate from verification — risk answers "how risky is the usage?" not "does it work reliably?"

from agentnode_sdk import get_risk_profile

profile = get_risk_profile("gmail-sender-pack")
# profile.risk_level   → "medium"
# profile.risk_score   → 45  (0-100, higher = riskier)
# profile.signals      → ["Uses external network access", "Requires credentials (oauth)"]
# profile.risk_flags   → ["external_write_capable"]

Returns None if the package is not installed.

Guard: Pre-Execution Policy Gateway

Guard classifies every tool call by action type and applies configurable policy before any code runs. 9 action types, 3 decisions (allow/prompt/deny), per-tool overrides, strict mode.

# Check what Guard would decide for a tool
agentnode guard check file-manager/delete_file
agentnode guard check web-scraper/fetch_page --json

# Show current policy
agentnode guard status

# Change policy for an action type
agentnode guard set delete deny           # block all deletes
agentnode guard set write_local allow      # allow local writes without prompt

# Per-tool override (granular escape hatch)
agentnode guard set delete allow --tool file-manager/delete_file

# Reset everything
agentnode guard reset

# Strict mode (CI / production)
export AGENTNODE_GUARD_STRICT=true

Default policy: read/compute/write_local/network_egress → allow. delete/write_external/execute/credential_use/unknown → prompt.

Strict mode: delete/write_external/execute/unknown → deny. write_local → prompt. Per-tool overrides ignored.

Critical risk (unverified + high-risk + secrets in env) → hard deny, no override possible.

Remote/connector hardening: Credentialed requests require HTTPS and explicit domain binding. Empty allowed_domains is denied — no open-proxy default. The remote runner additionally warns on method/action-type mismatches, oversized payloads, and scope/method inconsistencies (advisory only, never blocks).

See THREAT_MODEL.md for the full security model.

Supply-Chain Protection

Three layers of supply-chain protection:

Integrity (v0.7.0) — every installed package entry is sealed with a SHA-256 hash over security-critical fields. Post-install tampering is detected before any code executes.

Authenticity (v0.8.0) — publishers sign packages with Ed25519 keys. Install verifies the signature before writing the lockfile. Invalid signatures block install. Missing signatures warn but don't block (gradual adoption).

Registry Authenticity (v0.10.0) — trust-critical registry API responses are verified against pinned Ed25519 registry keys. Prevents a compromised registry from serving attacker-controlled metadata (public keys, trust levels, key status).

# Verify integrity + signatures (CI-friendly, exit code 1 on mismatch/invalid)
agentnode lock verify
agentnode lock verify --strict   # also fail on missing integrity
agentnode lock verify --json     # structured output with signature status

# Inspect a single package
agentnode inspect pdf-reader-pack
# → Integrity       verified
# → Signature       valid (key ed25519:a1b2c3d4e5f6)

# Seal entries after manual lockfile edits
agentnode lock seal

New installs are sealed and signature-verified automatically. In strict mode (AGENTNODE_GUARD_STRICT=true), tampered entries are denied at runtime. Invalid signatures always block install regardless of mode.

Risk Policies

Configure how the SDK reacts to computed risk flags. Uses the same allow | log | prompt | deny values as permission policies.

# Default: log (audit only, no blocking)
agentnode config get risk_policies.external_write_capable

# Require confirmation for packages that can send data externally
agentnode config set risk_policies.external_write_capable prompt

# Reset to audit-only
agentnode config set risk_policies.external_write_capable log

Risk policies only fire after the normal permission check passes. Hard policies (trust, permissions) always have priority.

Multi-step Planner

Decompose and execute multi-step tasks programmatically.

from agentnode_sdk.planner import plan_task, plan_and_run

# Plan without executing
plan = plan_task("extract text from report.pdf then summarize")
# plan.steps[0].capability == "pdf_extraction"
# plan.steps[1].capability == "text_summarization"
# plan.steps[1].uses_previous == True

# Plan and execute (each step runs through run_tool with full policy/audit)
result = plan_and_run("extract text from report.pdf then summarize")
# result.success, result.steps, result.duration_ms
# result.to_dict()  → structured output

Limitations: Max 3 steps. Rule-based splitting on connectors (then, and then, →) — no LLM decomposition.

License

MIT

Metadata

Release files for agentnode-sdk 0.25.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentnode-sdk 0.25.0
File Size Uploaded Provenance Actions
agentnode_sdk-0.25.0.tar.gz 3.3 MB Without provenance Details for agentnode_sdk-0.25.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentnode-sdk 0.25.0
File Interpreter ABI Platform Actions
agentnode_sdk-0.25.0-py3-none-any.whl Python 3 none any Details for agentnode_sdk-0.25.0-py3-none-any.whl

Total release size: 4.8 MB

Release files / agentnode_sdk-0.25.0.tar.gz

Download URL agentnode_sdk-0.25.0.tar.gz
Size 3.3 MB
Tags Source
SHA-256 checksum
How to use checksums
4c13635ffa7b16f459f1ed14883122d15b9501e3dbfcaa5c86c38ca2842e0116
BLAKE2b-256 checksum
How to use checksums
43c91ec0414df0ac3c099939b89470ea8d417a5eceea2c7c040a46ef0853eab8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / agentnode_sdk-0.25.0-py3-none-any.whl

Download URL agentnode_sdk-0.25.0-py3-none-any.whl
Size 1.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
e1c8af9b9805c41c551b211e6d9974be45a9147c756e7fe30820c311c7e9ffad
BLAKE2b-256 checksum
How to use checksums
ee3964d9923a3165ac0931a7bfbee72d069ee99b84a82c42532922f0a0517231
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for agentnode-sdk 0.25.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page