Skip to main content
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.

​
Supported languages

​
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 Reference page.

​
Shade Agent CLI

The Shade Agent CLI simplifies deploying a Shade Agent. The CLI automates:
  • Building your Docker image
  • Deploying the agent contract
  • Approving the code hash
  • Uploading your agent to Phala Cloud
  • Managing environment variables securely

CLI Reference

Learn more about how the CLI works and how to use it

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

Environment Variables

Learn more about configuring environment variables in your project

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

Custom Agent Contract

Learn how to build specialized agent contracts

​
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. 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 the 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
  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:

API Reference

Learn how to use the Shade Agent API across different languages

Security Considerations

Check your agent abides by best practices

Custom Contracts

Build specialized agent contracts

Plugins

Extend your agent’s capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us