NEAR AI Quickstart¶
In this Quickstart you will learn how to setup NEAR AI and then use it to build & interact with an AI agent in less than one minute. 🏃♂️
NEAR AI Agents are programs that can act autonomously to solve a task, while adapting and reacting to their environment. These agents can use various AI models, store data to remember past interactions, communicate with other agents, use tools to interact with the environment, and much more.
Setup¶
Pre-Requisites¶
Installing NEAR AI CLI¶
Python Version
If you do not have python, or your version is not compatible, we recommend that you use miniconda or pyenv to manage your installations, as they both allow you to easily switch between python versions.
Login to NEAR AI¶
To create a new agent, first login with a NEAR Account:
Don't have a NEAR Account?
If you do not have a NEAR account, you can create one for free using wallets listed at wallet.near.org.
If you are unsure of which one to choose, try out Bitte or Meteor Wallet.
You'll be provided with a URL to login with your NEAR account.
Example:
$> nearai login
Please visit the following URL to complete the login process: https://auth.near.ai?message=Welcome+to+NEAR+AI&nonce=<xyzxyzxyzxyzx>&recipient=ai.near&callbackUrl=http%3A%2F%2Flocalhost%3A63130%2Fcapture
After successfully logging in, you will see a confirmation screen. Close it and return to your terminal.
Tip
If you have already logged in on near-cli
, you know your account's private key, or you have the credentials on another device, you can use the following commands to login:
Create an Agent¶
After logging in, you can create a new agent by running the following command:
You will then be prompted to provide a few details about your agent:- The name of your agent.
- A short description of your agent.
- Initial instructions for the agent (which can be edited later).
Once you have complete these three prompts, you'll see a summary to verify the information is correct:
If everything looks good, press y
to build your agent. Once complete, you should see a confirmation screen similar to this:
Here you will find:
-
Where the agent was created:
/home_directory/.nearai/regisitry/<your-account.near>/<agent-name>/0.0.1
-
Useful commands to get started interacting with it:
Success! You now have a new AI Agent ready to use!
Agent Files¶
During the agent creation process, nearai
builds your agent in your local AI registry located at:
/home_directory/.nearai/registry/<your-account.near>/<agent-name>/0.0.1
This folder contains two files that define your agent:
metadata.json
: Contains information / configuration about your agent.agent.py
: Python code that executes each time your agent receives a prompt.
metadata.json
¶
This file contains information about your agent including optional configuration for the model it will use, Llama 3.1 70B Instruct being the default. To use a different model, select one from app.near.ai/models and update your JSON file defaults. To use whichever model is the latest default model at app.near.ai, remove the model defaults from your metadata.json.
Additionally, you can fine tune and serve a model to fit your specific needs. (See Fine Tuning)
{
"name": "example-agent",
"version": "0.0.1",
"description": "NEAR AI docs example agent ;)",
"category": "agent",
"tags": [],
"details": {
"agent": {
"defaults": {
"model": "llama-v3p1-70b-instruct",
"model_provider": "fireworks",
"model_temperature": 1.0,
"model_max_tokens": 16384
}
}
},
"show_entry": true
}
agent.py
¶
This file contains the code that executes each time your agent receives a prompt. By default it will use simple instructions provided by the user during the creation process.
For more information on how to use the environment object, see The Agent Environment.
For additional examples, see the NEAR AI Official Agents or the NEAR AI Public Registry.
from nearai.agents.environment import Environment
def run(env: Environment):
# A system message guides an agent to solve specific tasks.
prompt = {"role": "system", "content": "You are a helpful agent that will educate users about NEAR AI."}
# Use the model set in the metadata to generate a response
result = env.completion([prompt] + env.list_messages())
# Store the result in the chat history
env.add_reply(result)
# Give the prompt back to the user
env.request_user_input()
run(env)
Next Steps¶
Now that you have the basics down, here are some key areas to focus on next that will help you better understand what is possible when building with NEAR AI:
Explore the Registry →¶
The NEAR AI Registry is your hub for agent discovery and collaboration. Browse community-created agents, learn from examples, and share your own creations with others.
Master Threads →¶
Threads power agent execution and interaction. Learn to structure conversations, manage file attachments, and create coordinated multi-agent interactions - all within organized conversation threads.
Explore the Environment →¶
The environment object unlocks NEAR AI's powerful features:
- Create natural conversations with advanced message handling
- Leverage AI models for intelligent decision-making
- Enable agent-to-agent communication
- Extend capabilities with custom tools
Learn About Secrets →¶
Keep your agent secure with proper secrets management. Store API keys safely and connect to external services with confidence.