Integrating NEAR AI Agents¶

Easily integrate your Agent or any NEAR AI Agent into an existing application. There are two main pathways to accomplish this:

• iFrame Agent Embedding - Simple high-level integration with just a few lines of code
• Agent API - Lower-level integration for use when orchestrating multiple agents

iFrame Agent Embedding¶

The quickest way to integrate a NEAR AI Agent into any existing website is with an iFrame. This allows users to interact with your agent without leaving your site.

Basic Embedding¶

To embed an agent, use the following iframe code replacing the src with the agent you want to embed.

Example:

<iframe 
  src="https://app.near.ai/embed/<your-account.near>/<your-agent-name>/latest" 
  sandbox="allow-scripts allow-popups allow-same-origin allow-forms"
  style="border: none; height: 100svh;">
</iframe>

Customizing the Embed¶

There are three ways to customize the appearance and behavior of your embedded agent:

1. Basic <iframe> attributes
2. URL parameters
3. metadata.json file

Light or Dark Theme¶

For light or dark themes, add a theme parameter to the embed src URL:

src="https://app.near.ai/embed/<your-account.near>/<your-agent-name>/latest?theme=dark"

Custom Logo¶

You can also add a custom logo to replace the default agent name in the upper left hand corner of your agent.

In your metadata.json file add an embed section under the agent details:

{
  "details": {
    "agent": {
      "embed": {
        "logo": "https://near.ai/logo-white.svg"
      }
    }
  }
}

Agent API Integration¶

NEAR AI Agents are compatible with the OpenAI Assistants API, making it easy to integrate powerful AI capabilities into your applications. The API enables NEAR AI agents to:

1. Call various models with specific instructions to customize personality and capabilities
2. Access multiple tools for enhanced functionality
3. Maintain persistent conversation Threads
4. Process files in several formats (as inputs or outputs)

See the complete NEAR AI OpenAPI specification.

Key Concepts¶

Implementation Guide¶

NEAR AI provides a powerful Assistant API that you can integrate into your applications by following these steps:

1. Authentication: Login to NEAR Account
2. Create a Thread
3. Add Messages to the Thread
4. Run the Assistant on the Thread
5. Process Assistant Responses

1. Authentication: Login to NEAR Account¶

async function login(wallet, message, nonce, recipient, callbackUrl) {
    const signedMessage = await wallet.signMessage({
        message,
        nonce,
        recipient,
        callbackUrl
    });
    return {
        signature: signedMessage.signature,
        accountId: signedMessage.accountId,
        publicKey: signedMessage.publicKey,
        message,
        nonce,
        recipient,
        callbackUrl
    };
}

// Generate nonce based on current time in milliseconds and
// pad it with zeros to ensure its exactly 32 bytes in length
const nonce = Buffer.from(Date.now().toString().padStart(32, '0'));
const recipient = YOUR_RECIPIENT_ADDRESS;
const callbackUrl = YOUR_CALLBACK_URL;

// Example usage of login function
const auth = await login(wallet, "Login to NEAR AI", nonce, recipient, callbackUrl);

nearai login

2. Create a Thread¶

A Thread represents a conversation between a user and one or many Assistants. You can create a Thread when a user (or your AI application) starts a conversation with your Assistant. For more information see Threads.

import OpenAI from "openai";
const openai = new OpenAI({
    baseURL: "https://api.near.ai/v1",
    apiKey: `Bearer ${JSON.stringify(auth)}`,
});

const thread = await openai.beta.threads.create();

import openai

client = openai.OpenAI(
    api_key="YOUR_NEARAI_SIGNATURE",
    base_url="https://api.near.ai/v1",
)

thread = client.beta.threads.create()

3. Add Messages to the Thread¶

The contents of the messages your users or applications create are added as Message objects to the Thread. Messages can contain both text and files. There is a limit of 100,000 Messages per Thread and we smartly truncate any context that does not fit into the model's context window.

const message = await openai.beta.threads.messages.create(
  thread.id,
  {
    role: "user",
    content: "Help me plan my trip to Tokyo"
  }
);

message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Help me plan my trip to Tokyo"
)

4. Run the Assistant on the Thread¶

Once all the user Messages have been added to the Thread, you can Run the Thread with any Assistant. Creating a Run uses the model and tools associated with the Assistant to generate a response. These responses are added to the Thread as assistant Messages.

Runs are asynchronous, which means you'll want to monitor their status by polling the Run object until a terminal status is reached. For convenience, the 'create and poll' SDK helpers assist both in creating the run and then polling for its completion.

const assistant_id = "near-ai-agents.near/assistant/latest"
let run = await openai.beta.threads.runs.createAndPoll(
  thread.id,
  { 
    assistant_id: assistant_id,
  }
);

assistant_id = "near-ai-agents.near/assistant/latest"
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant_id,
)

5. Process Assistant Responses¶

Once the Run completes, you can list the Messages added to the Thread by the Assistant.

if (run.status === 'completed') {
  const messages = await openai.beta.threads.messages.list(
    run.thread_id
  );
  for (const message of messages.data.reverse()) {
    console.log(`${message.role} > ${message.content[0].text.value}`);
  }
} else {
  console.log(run.status);
}

if run.status == 'completed':
    messages = client.beta.threads.messages.list(run.thread_id)
    for message in messages:
        print(f"{message.role} > {message.content[0].text.value}")
else:
    print(run.status)

You may also want to list the Run Steps of this Run if you'd like to look at any tool calls made during this Run.