Owen Hassall · February 23, 2026
The biggest update to the Shade Agent Framework has been released since launch. It aims to enable more production-ready builds, a more flexible developer experience, and it comes with significant architectural changes.
The previous version of the Shade Agent Framework has known critical vulnerabilities. You should upgrade your agent to 2.0 as soon as possible.
A Shift in Mental Model
Shade Agent 2.0 is not a small iteration. It reflects a different way of building and deploying Shade Agents.
Previously, the framework leaned on global, abstract agent contracts and a separate API service. That made early development straightforward but production use harder: you had less control over contract behavior, deployment was split across env vars and flags, and the API lived in its own Docker image.
In Shade Agent Framework 2.0, the Shade Agent API is a single TypeScript library that runs inside your agent’s codebase instead of a separate service. The agent contract is included in your repo so you can change and extend it for your use case. The CLI is built around a single config file and has built-in credential management, making deploy and whitelist flows are predictable and easier to script.
The result is a framework that’s easier to reason about, easier to customize, and better suited to production. Below is a summary of the main changes for the API, CLI, and agent contract, with links to the docs so you can get started.
Shade Agent API
The Shade Agent API no longer offers multi-language support. It has been consolidated into a single TypeScript/JavaScript library (@neardefi/shade-agent-js) that runs within your agent’s codebase instead of a separate Docker image.
How the API Has Changed
Previously, the API was a separate Docker image (and HTTP service); you called standalone functions that talked to that service. In 2.0, you create a client in your code and use it for everything. Registration and funding now explicit methods instead of automatic on boot.
Before (1.x): No client—you installed the package and called functions that hit the API internally (or HTTP in other languages):
import { agentAccountId, agent, agentCall, agentView } from '@neardefi/shade-agent-js';
// API assumed to be running (Docker / localhost:3140); env vars for config
import { ShadeClient } from "@neardefi/shade-agent-js";
const agent = await ShadeClient.create({
networkId: "testnet",
agentContractId: process.env.AGENT_CONTRACT_ID,
sponsor: { accountId: process.env.SPONSOR_ACCOUNT_ID, privateKey: process.env.SPONSOR_PRIVATE_KEY },
rpc: provider,
});
// Then: await agent.register(), await agent.fund(0.3), etc.
// Before: const res = await agentAccountId(); const accountId = res.accountId
const accountId = agent.accountId();
1 = one NEAR), not yoctoNEAR.
// Before: const res = await agent("getBalance"); const balance = res.balance // yoctoNEAR
const balance = await agent.balance(); // human-readable, e.g. 0.3
// Before: agentCall({ methodName, args, gas }) / agentView({ methodName, args })
const result = await agent.call({
methodName: "example_call_function",
args: { arg1: "value1", arg2: "value2" },
gas: BigInt("300000000000000"),
deposit: "0",
});
const viewResult = await agent.view({
methodName: "example_view_function",
args: { arg1: "value1" },
});
requestSignature({ path, payload, keyType }) helper. In 2.0, this has been deprecated, now if you want to call a function of the contract called request_signature, call it like any other function:
// Before: requestSignature({ path, payload, keyType })
const result = await agent.call({
methodName: "request_signature",
args: { path, payload, key_type },
deposit: "1",
});
agent.register(), agent.fund(), agent.isWhitelisted(), and agent.getAttestation() for explicit control over registration, funding, and attestation; see the API reference for details.
To learn how to install, configure, and use the API, see the Shade Agent API reference.
Shade Agent CLI
The Shade Agent CLI had a total revamp. Instead of being configured with a mix of environment variables and flags, it now centers on a single deployment.yaml file, with built-in credential management and command routing, taking inspiration from the NEAR CLI.
You run shade auth to configure NEAR and Phala credentials, then use the commands shade deploy to deploy your Shade Agent, shade plan to preview the deployment, and shade whitelist to whitelist an agent’s account ID. The deployment.yaml file drives contract deployment (including from source or WASM), measurement and PPID approval, Docker image build and publish, and deployment to Phala Cloud, so all deployment options live in one place.
To learn how to install the CLI, use each command, and configure deployment.yaml, see the Shade Agent CLI reference.
Agent Contract
Previously, the framework used global agent contracts that were abstract and easy to start with, but made production development and customization difficult. In 2.0, by default, a reference agent contract is included in the shade-agent-template repo, so you can edit and extend it to your needs (e.g. custom agent-gated functions, guardrails, and initialization).
The reference agent contract also now uses a more robust external library for attestation verification (the shade-attestation crate). Instead of approving the codehash of a single Docker image, the contract now requires you to approve a set of measurements for more in-depth verification and a list of PPIDs that set the physical hardware the agent can run on. Local mode now requires you to whitelist the account ID of the agent you want to run locally, blocking any other account ID from controlling the contract for more consistent behavior when testing.
To walk through the contract flow, initialization, attestation verification, and how to add your own agent-gated functions, see the Agent Contract reference.
Next Steps
Start your migration by cloning the template in the quickstart to explore the new setup. 
