If you are building AI agents that touch Solana, you need two skill sets that rarely live in the same tutorial:
- Agent harness discipline (tools, context, gates)
- Chain realities (RPC, accounts, fees, failure modes)
This is a beginner stack map for developers who want both without getting wrecked on mainnet.
Kill the default approach
Default: give the agent a funded key and a "trade / send" tool, then prompt harder when it fails.
What breaks first: fee storms, wrong accounts, mainnet IDs in a devnet session, secrets in journals.
By the end you will have
- Network and key rules that keep mainnet out of lab agents
- Agent + Solana minimum layers
- The Simulate-First Tool Ladder (magnet)
- A two-week learning path
- A disaster list with gates
Start on the right network
Devnet / local validator first. Always.
- Real keys and real funds stay on hardware wallets
- Lab keys are disposable
- Never paste seed phrases into agent context
If your agent needs "money," use play money until the loop is boringly reliable.
The agent side (minimum)
Same four layers as any production agent:
- Model
- Tools (RPC, wallet adapter with hard limits, simulators)
- Context (program IDs, account roles, last sim results)
- Harness (plan → simulate → gate → send → confirm)
Critical rule: simulate before send. If the agent cannot show a simulation receipt, it does not get broadcast rights.
The Solana side (minimum)
| Piece | Why agents care |
|---|---|
| RPC endpoint | Latency and rate limits shape tool reliability |
| Account model | Wrong account = silent logic bugs |
| Compute / fees | Loops can burn SOL on retries |
| Confirmation | "Sent" is not "done" |
For latency-sensitive systems, dedicated infra matters. Product path: rpc edge (off-site ARR). Learning path: public RPC is fine until you measure pain.
Suggested beginner architecture
agent harness
├─ skill: solana-sim-first
├─ tool: rpc_read (no keys)
├─ tool: simulate_tx
├─ tool: send_tx (gated)
└─ journal: tx signatures + errors
Permissions escalate only after dry runs look clean for a full session.
Magnet: Simulate-First Tool Ladder
Name: Simulate-First Tool Ladder
| Rung | Tools | Risk | Rule |
|---|---|---|---|
| 1 Read | getAccount, getBalance, logs | Low | Always available |
| 2 Simulate | build tx, simulate, return logs/errors | Medium | Required before any send |
| 3 Write | sign / send | High | Human gate or hard spend caps |
You should see: a simulation receipt (logs/errors) in the journal before any signature is allowed to broadcast.
Never give an open-ended "run any CLI" tool with a funded key in the same profile you use for experiments.
Context pack for Solana agents
Keep a short living doc in the repo:
- Program IDs (devnet vs mainnet marked)
- Expected account roles
- Known failure strings
- Last successful signature for the flow
Do not dump entire IDL blobs into every turn. Point to files; load what the step needs.
Testing pyramid for agent + chain
- Unit tests for pure logic
- Local validator integration
- Devnet canary with tiny amounts
- Mainnet only with runbooks and alerts
Agents skip steps when you let them. Your harness should refuse skips.
Failure modes
| Disaster | Gate that blocks it |
|---|---|
| Retry storms paying fees | Cap retries; require sim success |
| Wrong account meta "fix" | Account role checklist in context pack |
| Mainnet IDs in devnet session | Network marker on every program ID |
| Secrets in journal | Skill: never log seeds / key material |
Learning path (two weeks)
Week 1: Agent-only - skills, verify loop, no mainnet keys. Use AI-native developer guide.
Week 2: One Solana flow on local/devnet - create, simulate, confirm, journal. Then stop and write the handoff.
When not to use this stack
- Pure frontend with no chain writes (you may only need read tools)
- Mainnet production incident with an existing runbook (do not invent a new agent mid-fire)
- You have not secured keys offline (do not start)
Where nyk.dev helps
- Patterns and OSS: oss catalog
- Agent OS: checklist · packages
- Latency-sensitive infra: rpc edge (off-site product path)
Bottom line
Solana agents fail less from weak models than from weak harnesses and sloppy chain hygiene.
Your next action: install Simulate-First Tool Ladder - remove send rights until the agent can show a simulation receipt on your first lab flow.