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. 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.

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. 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 section.

Supported Languages​

TypeScript/JavaScript (Recommended) Agents are primarily written in TypeScript/JavaScript using shade-agent-js, which integrates seamlessly with chainsig.js 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. 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.

Architecture Overview​

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.

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.

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.

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 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.

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 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.

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.

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.

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 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 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 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. 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, here are some great sections to explore next:

  1. Framework components: API, CLI, and Environment Variables
  2. Custom Contracts - build specialized agent contracts
  3. Plugins - extend your agent's capabilities
  4. Tutorials and Templates - get up and running with different Shade Agent architectures, and use cases as quickly as possible and learn how to build apps in full
  5. 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