Update Shade Agent docs after shade-agent-framework 2.0 release

blog/2026-02-23.md

@@ -0,0 +1,127 @@
+---
+title: Shade Agent Framework 2.0
+authors: [pivortex]
+slug: shade-agent-framework-2.0
+tags: [updates, ai, shade-agents]
+hide_table_of_contents: true
+---
+
+The biggest update to the Shade Agent Framework has been released since launch. It aims to enable more production-ready builds and a more flexible developer experience and it comes with significant architectural, and breaking changes.
+
+:::danger Upgrade immediately
+The previous version of the Shade Agent Framework has **known critical vulnerabilities**. You should upgrade your agent to 2.0 as soon as possible.
+:::
+
+<!-- truncate -->
+
+## 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 made 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 one config file and built-in credential management, so 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):
+
+```ts
+import { agentAccountId, agent, agentCall, agentView } from '@neardefi/shade-agent-js';
+// API assumed to be running (Docker / localhost:3140); env vars for config
+```
+
+**After (2.0):** One client, created once with your config:
+
+```ts
+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.
+```
+
+**Account ID:** Same idea, different shape, you now use the client instance and get the value directly (no response object).
+
+```ts
+// Before: const res = await agentAccountId(); const accountId = res.accountId
+const accountId = agent.accountId();
+```
+
+**Balance:** Balance is now a method on the client and returns human-readable NEAR (e.g. `1` = one NEAR), not yoctoNEAR.
+
+```ts
+// Before: const res = await agent("getBalance"); const balance = res.balance  // yoctoNEAR
+const balance = await agent.balance();  // human-readable, e.g. 0.3
+```
+
+**Call and view:** Call and view have stayed the same but are accessible via the client instance instead of a standalone function.
+
+```ts
+// 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" },
+});
+```
+
+**Request signature:** The old API had a dedicated `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:
+
+```ts
+// Before: requestSignature({ path, payload, keyType })
+const result = await agent.call({
+  methodName: "request_signature",
+  args: { path, payload, key_type },
+  deposit: "1",
+});
+```
+
+New methods include `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](/ai/shade-agents/reference/api)**.
+
+---
+
+## Shade Agent CLI
+
+The Shade Agent CLI has 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](/ai/shade-agents/reference/cli)**.
+
+---
+
+## 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](https://github.com/NearDeFi/shade-agent-framework/tree/main/shade-attestation)). 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](/ai/shade-agents/reference/agent-contract)**.
+
+---
+
+## Next Steps
+
+Start your migration by **cloning the template** in the [quickstart](/ai/shade-agents/getting-started/quickstart/deploying) to explore the new setup.

docs/ai/shade-agents/concepts/framework-overview.md

@@ -7,126 +7,43 @@ description: "Learn about the core components of the Shade Agent Framework with
 
 import { SigsSupport } from '@site/src/components/sigsSupport';
 
-The Shade Agent Framework provides a suite of tools designed to simplify the development and deployment of Shade Agents. The framework abstracts away the complexities of the underlying infrastructure, allowing developers to focus on building their agent logic. In this section, you'll explore the tooling provided by the framework and examine the key components you need when building an agent.
+The **Shade Agent Framework** is a platform for creating Web3 agents and off-chain services that are **verifiable**, **trust-minimized**, and **decentralized**. It leverages **on-chain signing** to allow agents to hold assets and sign transactions on most blockchains and implement strict **guardrails** to prevent unauthorized actions.
 
----
-
-## Templates, Languages, and Architecture 
-
-### Templates
-
-When starting to build with the Shade Agent Framework, it's recommended to start by forking the [Quickstart Shade Agent Template](https://github.com/NearDeFi/shade-agent-template). This template contains all the necessary files to build a Shade Agent and provides the fastest starting path.
-
-Additional templates can be found in our [Tutorials and Templates](../tutorials/tutorials-overview.md) section.
+It includes the **Shade Agent API**, the **Shade Agent CLI**, and an **agent contract reference implementation**. The framework aims to abstract most of the underlying TEE and blockchain interactions so you can focus on building your application.
 
-### Supported Languages
-
-**TypeScript/JavaScript (Recommended)**
-Agents are primarily written in TypeScript/JavaScript using `shade-agent-js`, which integrates seamlessly with [chainsig.js](../../../chain-abstraction/chain-signatures/implementation.md) for building multichain transactions and deriving multichain accounts.
-
-**Python**
-The framework also supports `shade-agent-py`, which allows you to develop agents in Python. Here is an [example](https://github.com/NearDeFi/shade-python-example/tree/main). However, note that tooling for building multichain transactions and deriving multichain accounts is not currently available in Python, so additional development work will be required for multichain use cases.
+---
 
-**Other Languages**
-Agents can be written in any language, provided you can create a Docker image for the agent. To build a Shade Agent in other languages, you can use the API directly. Learn more about this approach on the [API page](../reference/api.md).
+## Architecture Overview
 
-### Architecture Overview
+A **Shade Agent** has two main parts: the **agent** (off-chain) and the **agent contract** (on-chain). The agent is a backend service that runs in a TEE (or locally in dev) and holds your business logic; it uses the Shade Agent API to register and interact with the agent contract. The agent contract is a NEAR smart contract that decides who can act as an agent (via attestations, approved measurements, and PPIDs), enforces guardrails, and gives valid agents access to on-chain signing via chain signatures (MPC signing). One agent contract can have many registered agents - for example, several instances running the same code for redundancy, or different agents for different tasks.
 
-A Shade Agent is essentially a `backend service` that uses the Shade Agent API and runs inside a Trusted Execution Environment (TEE) instead of on a classic server. You can develop using any backend framework you prefer, expose API routes, run cron jobs, or index events and respond to them with actions. 
+By default, agents are deployed to Phala Cloud, but you can deploy them to other TEE providers that support Dstack.
 
 ---
 
 ## Shade Agent API
 
-The Shade Agent API abstracts away the complexity of TEE operations and agent contract interactions. For detailed information on how the API works and how to use it across different languages, please refer to the [API page](../reference/api.md).
+The Shade Agent API is a **TypeScript/JavaScript** library that connects your agent to the Shade Agent Framework. It abstracts TEE complexity and simplifies calls to the agent contract. You can learn more about the Shade Agent API on the [API page](../reference/api.md).
 
 ---
 
 ## Shade Agent CLI
 
-The Shade Agent CLI simplifies deploying a Shade Agent. To learn more about how the CLI works and how to use it, please refer to the [CLI page](../reference/cli.md).
-
----
-
-## Environment Variables
-
-Environment variables are a crucial component of the Shade Agent Framework. They configure your Shade Agent and are passed encrypted into your agent when it goes live. To learn more about configuring environment variables in your project, please refer to the [Environment Variables page](../reference/environment-variables.md).
+The Shade Agent CLI makes it easy to deploy a Shade Agent. Including building and deploying your agent contract, building and publishing your agent's Docker image, and deploying the agent to Phala Cloud. You can learn more about the Shade Agent CLI on the [CLI page](../reference/cli.md).
 
 ---
 
-## Agent Contract
-
-By default, the Shade Agent CLI will deploy a generic agent contract that implements the three core functions, `approve_codehash`, `register_agent`, and `request_signature`, discussed in the introduction. This generic agent contract works for many use cases since you can register any arbitrary agent and have it request signatures for any chain - it's very flexible. 
+## Agent Contract Reference Implementation
 
-There are also cases when you should develop your own `custom agent contract`. These include, but are not limited to:
-1) You want to implement strict `guard rails` that prevent malicious actions, even if the TEE is somehow compromised - Review our [security considerations](../concepts/security.md#restricting-actions) for more details
-2) You want to implement a custom agent registration or code hash upgradability mechanism
-3) You want to build an agent that just interacts with the NEAR blockchain
-
-Further documentation can be found in the [custom contract section](../reference/custom-agent-contract.md).
+A walkthrough of the agent contract reference implementation is available on the [Agent Contract Reference Implementation page](../reference/agent-contract.md). It contains the fundamental agent contract logic which you can use as a starting point for your own agent contract.
 
 ---
 
-## Phala Cloud
-
-Phala Cloud is a cloud solution that simplifies hosting applications and agents inside Trusted Execution Environments. The Shade Agent Framework uses Phala Cloud for agent deployment. You can deploy any standard Docker application to Phala. To learn more about Phala, visit their [documentation](https://docs.phala.network/phala-cloud/what-is/what-is-phala-cloud).
-
-Once your agent is deployed, you can manage the deployment from the [dashboard](https://cloud.phala.network/dashboard).
-
-To deploy an agent to production, you'll need a Phala Cloud account. You can create one [here](https://cloud.phala.network/register). 
-
-After deploying to Phala Cloud, monitor your deployments and delete unused ones to avoid unnecessary costs.
-
----
-
-## Docker
-
-Docker is a platform that allows you to package an application into a self-contained environment. By creating a Docker image, you can run your agent in the TEE. An agent typically consists of two Docker images (the application and the Shade Agent API), but it can include more. When building Shade Agents, it's helpful to understand how Docker works. If you're interested in learning more about Docker, please visit the [documentation](https://docs.docker.com/get-started/docker-overview/). 
-
-You'll need to set up Docker on your machine if you do not have it already, and create an account:
-- Install Docker for [Mac](https://docs.docker.com/desktop/setup/install/mac-install/) or [Linux](https://docs.docker.com/desktop/setup/install/linux/) and create an account.
-- Log in to Docker, using `docker login` for Mac or `sudo docker login` for Linux.
-
-There are two Docker-related files included in our project: the `Dockerfile` and the `Docker Compose` file. 
-
-### Dockerfile
-
-The Dockerfile tells Docker how to build and run your image. The Shade Agent CLI automatically builds your Docker image using the Dockerfile and pushes it to Docker Hub, making it accessible over the internet.
-
-A standard Dockerfile will:
-1. Start with a `base image`, which serves as the starting point for your application (e.g., Ubuntu, Alpine, Node.js, Python pre-installed)
-2. Set the working directory
-3. Install system dependencies
-4. Add relevant files from the project to the image (in our examples, everything within the `source folder` is included, along with the `manifest file` that lists your dependencies like the package.json or pyproject.toml)
-5. Install project dependencies
-6. Build the project
-7. Set the environment (production, development)
-8. Tell Docker how to start the application
-
-In most cases, you can use the Dockerfile already supplied in the template without modification.
-
-Here are example Dockerfiles for a [Typescript](https://github.com/NearDeFi/shade-agent-template/blob/main/Dockerfile) and [Python](https://github.com/NearDeFi/shade-python-example/blob/main/Dockerfile) agent.
-
-You can learn more about the Dockerfile [here](https://docs.docker.com/reference/dockerfile/)
-
-### Docker Compose
-
-The Docker Compose file (docker-compose.yaml) defines which Docker images will be included within your agent. This file is what is actually uploaded to Phala Cloud to run your agent, which pulls the specified images on boot. The compose file also specifies which environment variables are passed to the images, whether images are exposed on ports, and other configuration details.
-
-The images used are automatically configured when you run the Shade Agent CLI. In most cases, you can use the Docker Compose file already supplied [in the template](https://github.com/NearDeFi/shade-agent-template/blob/main/docker-compose.yaml). However, if you want to include additional Docker images in your agent or use additional environment variables for your application, you'll need to edit the Docker Compose file.
-
-You can learn more about the Docker Compose file [here](https://docs.docker.com/reference/compose-file/)
-
----
-
-## Next Steps
-
 Now that you have an overview of the framework, here are some great sections to explore next:
-1. Framework components: [API](../reference/api.md), [CLI](../reference/cli.md), and [Environment Variables](../reference/environment-variables.md)
-2. [Custom Contracts](../reference/custom-agent-contract.md) - build specialized agent contracts
-3. [Plugins](../reference/plugins.md) - extend your agent's capabilities
-4. [Tutorials and Templates](../tutorials/tutorials-overview.md) - get up and running with different Shade Agent architectures, and use cases as quickly as possible and learn how to build apps in full
-4. [Security Considerations](../concepts/security.md) - check your agent abides by best practices
-
+1. Framework components: [API](../reference/api.md), [CLI](../reference/cli.md), and [Agent Contract Reference Implementation](../reference/agent-contract.md).
+2. [Tutorials and Templates](../tutorials/tutorials-overview.md) - get up and running with different Shade Agent architectures and use cases as quickly as possible, and learn how to build apps in full.
+3. [What can you build?](../concepts/what-can-you-build.md) - learn about the different types of applications you can build with Shade Agents.
+4. [Terminology](../concepts/terminology.md) - learn the key terms and concepts used in the Shade Agent Framework.
+5. [Security Considerations](../concepts/security.md) - check your agent abides by best practices.
 
 <SigsSupport />