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¶

• NEAR Account
• NEAR AI CLI

Installing NEAR AI CLI¶

python3 -m pip install nearai

git clone git@github.com:nearai/nearai.git
cd nearai
pip install -e .

pyenv install 3.11
pyenv local 3.11 # or use global

conda create -n myenv python=3.11
conda activate myenv

Login to NEAR AI¶

To create a new agent, first login with a NEAR Account:

nearai login

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.

### Login with NEAR Account ID Only
nearai login --accountId name.near

### Login with Account ID and Private Key
nearai login --accountId name.near --privateKey key

### Login Remotely (only displays the login URL)
nearai login --remote

Create an Agent¶

After logging in, you can create a new agent by running the following command:

nearai agent create

1. The name of your agent.
2. A short description of your agent.
3. 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:

1. Where the agent was created:

   /home_directory/.nearai/regisitry/<your-account.near>/<agent-name>/0.0.1

2. Useful commands to get started interacting with it:

   # Run agent locally
   nearai agent interactive <path-to-agent> --local
   
   # Select from a list of agents you created to run locally
   nearai agent interactive --local
   
   # Upload agent to NEAR AI's public registry
   nearai registry upload <path-to-agent>
   

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:

1. metadata.json: Contains information / configuration about your agent.
2. 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.