NEAR AI Development

Comprehensive guide for building AI agents and AI-powered applications on NEAR Protocol, including NEAR AI integration, agent workflows, and AI model deployment.

When to Apply

Reference these guidelines when:

• Building AI agents on NEAR
• Integrating AI models with NEAR smart contracts
• Creating agent-based workflows
• Implementing AI-powered dApps
• Using NEAR AI infrastructure
• Building with NEAR AI Assistant

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Agent Architecture	CRITICAL	arch-
2	AI Integration	HIGH	ai-
3	Agent Communication	HIGH	comm-
4	Model Deployment	MEDIUM-HIGH	model-
5	Agent Workflows	MEDIUM	workflow-
6	Security & Privacy	MEDIUM	security-
7	Best Practices	MEDIUM	best-

Quick Reference

1. Agent Architecture (CRITICAL)

• arch-agent-structure - Design modular agent architecture
• arch-state-management - Manage agent state on-chain vs off-chain
• arch-agent-registry - Register agents in NEAR AI registry
• arch-composability - Build composable agents
• arch-agent-capabilities - Define clear agent capabilities

2. AI Integration (HIGH)

• ai-model-selection - Choose appropriate AI models
• ai-inference-endpoints - Use NEAR AI inference endpoints
• ai-prompt-engineering - Design effective prompts for agents
• ai-context-management - Manage conversation context
• ai-response-validation - Validate and sanitize AI responses

3. Agent Communication (HIGH)

• comm-agent-protocol - Implement standard agent communication protocols
• comm-message-format - Use structured message formats
• comm-async-messaging - Handle asynchronous agent communication
• comm-multi-agent - Coordinate multiple agents
• comm-human-in-loop - Implement human-in-the-loop patterns

4. Model Deployment (MEDIUM-HIGH)

• model-hosting - Deploy models on NEAR AI infrastructure
• model-versioning - Version and update AI models
• model-optimization - Optimize models for inference
• model-monitoring - Monitor model performance
• model-fallbacks - Implement fallback strategies

5. Agent Workflows (MEDIUM)

• workflow-task-planning - Implement agent task planning
• workflow-execution - Execute multi-step workflows
• workflow-error-handling - Handle workflow errors gracefully
• workflow-state-persistence - Persist workflow state
• workflow-composability - Compose workflows from smaller tasks

6. Security & Privacy (MEDIUM)

• security-input-validation - Validate user inputs to agents
• security-output-sanitization - Sanitize agent outputs
• security-access-control - Implement agent access control
• security-data-privacy - Protect user data privacy
• security-prompt-injection - Prevent prompt injection attacks

7. Best Practices (MEDIUM)

• best-error-messages - Provide clear error messages
• best-logging - Log agent interactions for debugging
• best-testing - Test agent behavior comprehensively
• best-documentation - Document agent capabilities and APIs
• best-user-feedback - Collect and incorporate user feedback

How to Use

Read individual rule files for detailed explanations and code examples:

rules/arch-agent-structure.md
rules/ai-inference-endpoints.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and NEAR AI-specific patterns

NEAR AI Components

NEAR AI Hub

Central registry for AI agents, models, and datasets on NEAR.

NEAR AI Assistant

Infrastructure for building conversational AI agents.

Agent Registry

On-chain registry for discovering and interacting with agents.

Inference Endpoints

Decentralized inference infrastructure for AI models.

Resources

• NEAR AI Documentation: https://docs.near.ai/
• NEAR AI Hub: https://app.near.ai/
• NEAR AI GitHub: https://github.com/near/nearai
• Agent Examples: https://github.com/near/nearai/tree/main/examples
• NEAR AI Research: https://near.ai/research

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md