Skip to main content

Framework Overview

The Shade Agent Framework provides a suite of tools designed to simplify the development and deployment of Shade Agents. This framework abstracts away the complexities of the underlying infrastructure, allowing developers to focus on building their agent logic. In this section, we'll explore the tooling provided by the framework and examine the key components you need when building an agent.

Languages, Templates and Architecture​

When starting to build with the Shade Agent Framework, we recommend forking the quickstart Shade Agent Template. This template contains all the necessary files to build a Shade Agent (which we'll explore later on this page).

Since the agent is written in TypeScript and uses shade-agent-js, it integrates seamlessly with chainsig.js for building multichain transactions and deriving multichain accounts.

We also maintain a Python example that uses shade-agent-py, allowing you to develop agents in Python. However, note that we don't currently maintain tooling for building multichain transactions and deriving multichain accounts in Python, so additional development work will be required.

Agents can be written in any language as long as you can create a Docker image for it by using the API directly. You can learn more about this approach on the API page.

An Agent is essentially a backend service (or server) that uses the Shade Agent API and runs inside a Trusted Execution Environment (TEE) instead of on a centralized 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. If you're planning to develop Shade Agents seriously, we recommend having prior experience with creating backend services.

Shade Agent API​

The Shade Agent API abstracts away the complexity of the TEE and interacting with the agent contract. To learn more about how the API works and how to use it in different languages, please refer to the API page.

Shade Agent CLI​

The Shade Agent CLI abstracts away the complexity of deploying a Shade Agent. To learn more about how the CLI works and how to use it, please refer to the CLI page.

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.

Agent Contract​

By default the Shade Agent CLI will deploy a generic agent contract that implements the three methods, approve_codehash, register_agent, and request_signature, talked about 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.

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 guardrails that prevent malicious actions, even if the TEE is somehow compromised
  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.

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.

Once your agent is deployed, you can manage the deployment from the dashboard.

To deploy an agent to production, you'll need a Phala Cloud account. You can create one here.

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.

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 or 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 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 and Python agent.

You can learn more about the Dockerfile here

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 then pulls the specified images. 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. 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

Next Steps​

Now that you have an overview of the framework, we recommend exploring these sections next:

  1. Framework components: API, CLI, and Environment Variables
  2. Custom Contracts - build specialized agent contracts
  3. Plugins - extend your agent's capabilities
  4. Security Considerations - check your agent abides by best practices
Office Hours

Join our weekly 1-on-1, 15 minute sessions for personalized developer support and guidance for Chain Signatures and Shade Agents.

Book a Session
Developer Support Groups

Access async support and connect with other builders in our Telegram Communities.

Chain Signatures Group|Shade Agents Group
Reach Out

If your team is building or considering building a production application using Chain Signatures or Shade Agents, please fill our our interest form.

Chain Signatures Interest Form|Shade Agents Interest Form