![](./public/AI-Agent-Contract.jpg)
Host your AI Agent Contract on Phala's decentralized serverless cloud.
Explore the docs »
View Demo
·
Report Bug
·
Discord
![](./public/ai-agent-architecture.jpg)
The AI Agent Contract Tools template is a MINIMAL template to build an AI Agent that can be hosted on Phala Network's decentralized hosting protocol. Unlike Vercel or other FaaS, it allows you to publish your AI Agent compiled code to IPFS and hosts it on a fully decentralized FaaS cloud with the following benefits:
- 💨 Ship Fast: Build and ship with familiar toolchain in minutes
- ⛑️ Secure: Execution guarded by rock solid TEE / Intel SGX
- 🔒 Private: Host API keys and user privacy at ease
- 💎 Unstoppable: Powered by IPFS and Phala's 35k+ decentralized TEE workers
Install dependencies
npm install
Create .env
file
cp .env.example .env
In .env
file replace SECRET_SALT
with your own secret salt
SECRET_SALT="SECRET_SALT"
Build your Agent
npm run build
Test your Agent locally
npm run test
Expected Test Results
> [email protected] test
> tsx src/test.ts
NOTE: Signing data must be tested in Sidevm Playground. Use this as the arg value to test
- args: {"method":"GET","path":"/ipfs/QmVHbLYhhYA5z6yKpQr4JWr3D54EhbSsh7e7BFAAyrkkMf","queries":{"data":["Hello MOON!"],"type":["sign"]},"secret":{"secretSalt":"SALTY"},"headers":{}}
To test in the SideVM playground go to https://phat.phala.network/contracts/view/0xf0a398600f02ea9b47a86c59aed61387e450e2a99cb8b921cd1d46f734e45409
Connect you polkadot.js account and select 'run_js' with the parameters:
- engine: SidevmQuickJSWithPolyfill
- js_code: Source code text of dist/index.ts
- args: {"method":"GET","path":"/ipfs/QmVHbLYhhYA5z6yKpQr4JWr3D54EhbSsh7e7BFAAyrkkMf","queries":{},"secret":{"secretSalt":"SALTY"},"headers":{}}
Watch video here for to see the visual steps of testing in Sidevm playground: https://www.youtube.com/watch?v=fNqNeLfFFME
Make sure to replace queries and secret with your values compatible with your AI Agent Contract.
NOTE:
Signing data must be tested in Sidevm Playground. Use this as the arg value to test
- args: {"method":"GET","path":"/ipfs/QmVHbLYhhYA5z6yKpQr4JWr3D54EhbSsh7e7BFAAyrkkMf","queries":{"data":["Hello MOON!"],"type":["sign"]},"secret":{"secretSalt":"SALTY"},"headers":{}}
NOTE:
Verifying data must be tested in Sidevm Playground. Use this as the arg value to test
- args: {"method":"GET","path":"/ipfs/QmVHbLYhhYA5z6yKpQr4JWr3D54EhbSsh7e7BFAAyrkkMf","queries":{"data":["Hello MOON!"],"signature":["REPLACE_WITH_SIGNATURE"],"type":["verify"]},"secret":{"secretSalt":"SALTY"},"headers":{}}
Upload your compiled AI Agent code to IPFS.
npm run publish-agent
Upon a successful upload, the command should show the URL to access your AI Agent.
✓ Compiled successfully.
69.43 KB dist/index.js
Running command: npx thirdweb upload dist/index.js
This may require you to log into thirdweb and will take some time to publish to IPFS...
$$\ $$\ $$\ $$\ $$\
$$ | $$ | \__| $$ | $$ |
$$$$$$\ $$$$$$$\ $$\ $$$$$$\ $$$$$$$ |$$\ $$\ $$\ $$$$$$\ $$$$$$$\
\_$$ _| $$ __$$\ $$ |$$ __$$\ $$ __$$ |$$ | $$ | $$ |$$ __$$\ $$ __$$\
$$ | $$ | $$ |$$ |$$ | \__|$$ / $$ |$$ | $$ | $$ |$$$$$$$$ |$$ | $$ |
$$ |$$\ $$ | $$ |$$ |$$ | $$ | $$ |$$ | $$ | $$ |$$ ____|$$ | $$ |
\$$$$ |$$ | $$ |$$ |$$ | \$$$$$$$ |\$$$$$\$$$$ |\$$$$$$$\ $$$$$$$ |
\____/ \__| \__|\__|\__| \_______| \_____\____/ \_______|\_______/
💎 thirdweb v0.14.12 💎
- Uploading file to IPFS. This may take a while depending on file sizes.
✔ Successfully uploaded file to IPFS.
✔ Files stored at the following IPFS URI: ipfs://QmNrprJ7GBmYcHYtPXvc9Xp6tZE2Z3CgNi1TW2scTvcpCY
✔ Open this link to view your upload: https://bafybeiahxlsblg3nwyrziavih7ziviherm7zph5atxxxvdyv3pnao7tzae.ipfs.cf-ipfs.com/
AI Agent Contract deployed at: https://agents.phala.network/ipfs/QmNrprJ7GBmYcHYtPXvc9Xp6tZE2Z3CgNi1TW2scTvcpCY
Make sure to add your secrets to ensure your AI-Agent works properly. Use syntax:
curl https://agents.phala.network/vaults -H 'Content-Type: application/json' -d '{"cid": "QmNrprJ7GBmYcHYtPXvc9Xp6tZE2Z3CgNi1TW2scTvcpCY", "data": {"secretSalt": "SECRET_SALT"}}'
New to thirdweb?
We use thirdweb Storage to host IPFS contents. If you are new to thirdweb, the command will guide you to create your account or login to your existing account from the browser. (You may need to forward port 8976 if you are accessing a remote console via SSH.)Did thirdweb fail to publish?
If thirdweb takes too long to install or fails to publish, use the following command:curl -F file=@./dist/index.js https://agents.phala.network/ipfs
Once published, your AI Agent is available at the URL: https://agents.phala.network/ipfs/<your-cid>
. You can get it from the "Publish to IPFS" step.
You can test it with curl
.
curl https://agents.phala.network/ipfs/<your-cid>
By default, all the compiled JS code is visible for anyone to view if they look at IPFS CID. This makes private info like API keys, signer keys, etc. vulnerable to be stolen. To protect devs from leaking keys, we have added a field called secret
in the Request
object. It allows you to store secrets in a vault for your AI Agent to access.
How to Add Secrets
The steps to add a secret
is simple. We will add the Anthropic API Key in this example by creating a secret JSON object with the anthropicApiKey
:
{"secretSalt": "<SECRET_SALT>"}
Then in your frame code, you will be able to access the secret key via req.secret
object:
async function GET(req: Request): Promise<Response> {
const secretSalt = req.secret?.secretSalt
}
Note: Before continuing, make sure to publish your compiled AI Agent JS code, so you can add secrets to the CID.
Open terminal
Use curl
to POST
your secrets to https://agents.phala.network/vaults
. Replace IPFS_CID
with the CID to the compile JS code in IPFS, and replace <ANTHROPIC_API_KEY>
with your Anthropic API key. Note that you can name the secret field name something other than anthropicApiKey
, but you will need to access the key in your index.ts
file with the syntax req.secret?.<your-secret-field-name> as string
The command will look like this:
curl https://agents.phala.network/vaults -H 'Content-Type: application/json' -d '{"cid": "IPFS_CID", "data": {"secretSalt": "<SECRET_SALT>"}}'
# Output:
# {"token":"e85ae53d2ba4ca8d","key":"e781ef31210e0362","succeed":true}
The API returns a token
and a key
. The key
is the id of your secret. It can be used to specify which secret you are going to pass to your frame. The token
can be used by the developer to access the raw secret. You should never leak the token
.
To verify the secret, run the following command where key
and token
are replaced with the values from adding your secret
to the vault.
curl https://agents.phala.network/vaults/<key>/<token>
Expected output:
{"data":{"secretSalt":"<SECRET_SALT>"},"succeed":true}
If you are using secrets, make sure that your URL is set in the following syntax where cid
is the IPFS CID of your compiled JS file and key
is the key
from adding secrets to your vault.
https://agents.phala.network/ipfs/<cid>?key=<key>
- Derived ECDSA Key: https://agents.phala.network/ipfs/QmNrprJ7GBmYcHYtPXvc9Xp6tZE2Z3CgNi1TW2scTvcpCY?key=e29161406e3e6bcb
- Sign 'Hello MOON!': https://agents.phala.network/ipfs/QmNrprJ7GBmYcHYtPXvc9Xp6tZE2Z3CgNi1TW2scTvcpCY?key=e29161406e3e6bcb&type=sign&data=Hello%20Moon%21
- Verify Signature: https://agents.phala.network/ipfs/QmNrprJ7GBmYcHYtPXvc9Xp6tZE2Z3CgNi1TW2scTvcpCY?key=e29161406e3e6bcb&type=verify&data=Hello%20Moon!&signature=0x372f08f2efebcff0ac8f9ae0dcc6662bf5aeb9e54cf40e86043cc71bb18fd806688f6956b8a31774ef5249d9bea878905c616c117fc27d15b1a2340d10ba90df1c
To help create custom logic, we have an array variable named queries
that can be accessed in the Request
class. To access the queries
array variable type
value at index 0
, the syntax will look as follows:
const type = req.queries.type[0] as string;
What packages can I use in the AI Agent server?
- Most of the npm packages are supported: viem, onchainkit, ….
- Some packages with some advanced features are not supported:
- Large code size. Compiled bundle should be less than 500kb.
- Large memory usage, like image generation
- Web Assembly
- Browser only features: local storage, service workers, etc
What’s the spec of the Javascript runtime?
- The code runs inside a tailored QuickJS engine
- Available features: ES2023, async, fetch, setTimeout, setInterval, bigint
- Resource limits
- Max execution time ~30s
- Max memory usage: 16 mb
- Max code size: 500 kb
- Limited CPU burst: CPU time between async calls is limited. e.g. Too complex for-loop may hit the burst limit.
Why is the serverless platform secure?
- Your AI Agent code on is fully secure, private, and permissionless. Nobody can manipulate your program, steal any data from it, or censor it.
- Security: The code is executed in the decentralized TEE network running on Phala Network. It runs code inside a secure blackbox (called enclave) created by the CPU. It generates cryptographic proofs verifiable on Phala blockchain. It proves that the hosted code is exactly the one you deployed.
- Privacy: You can safely put secrets like API keys or user privacy on Phala Network. The code runs inside TEE hardware blackboxs. The memory of the program is fully encrypted by the TEE. It blocks any unauthorized access to your data.
- Learn more at Phala Network Homepage