Skip to content

agent-developers.md

Latest commit

 

History

History
292 lines (217 loc) · 8.08 KB

agent-developers.md

File metadata and controls

292 lines (217 loc) · 8.08 KB
Raw
title Agent Developers
description Build AI agents that pay for their own intelligence — 71 models via x402 micropayments. Use Franklin, the SDKs, or the MCP; integrate with frameworks if you already use one.

Agent Developers

Build AI agents that pay for their own intelligence.

This guide is for agent developers. The primary paths are Franklin (our autonomous agent), the SDKs, and the BlockRun MCP — all on one wallet, 71 models via x402 micropayments. Already using a framework (ElizaOS, AgentKit, GOAT, LangChain)? See Community integrations.

:::tip{title="Fastest path: Franklin"} Want an agent that already spends autonomously? Franklin is one install (npm install -g @blockrun/franklin) and runs free out of the box — fund a wallet to unlock everything. :::

Why BlockRun for Agents?

Traditional With BlockRun
Manage API keys for each provider One wallet for all models
Prepaid credits or subscriptions Pay-per-request
Credential rotation headaches Just fund and go
Complex billing reconciliation On-chain transparency

Quick Start

Install the SDK for your language:

::::tabs :::tab{label="Python"}

pip install blockrun-llm

::: :::tab{label="TypeScript"}

npm install @blockrun/llm

::: ::::

Then set up a wallet and make your first call:

::::steps

:::step{title="Set up the wallet"}

from blockrun_llm import LLMClient

client = LLMClient()  # Creates wallet if none exists
print(f"Wallet address: {client.get_address()}")

Fund this address with USDC on Base network. :::

:::step{title="Use any model"}

# OpenAI
response = client.chat("openai/gpt-5.4", "Analyze this market data...")

# Anthropic
response = client.chat("anthropic/claude-sonnet-4.6", "Review this code...")

# DeepSeek (50x cheaper)
response = client.chat("deepseek/deepseek-chat", "Summarize these documents...")

:::

::::

Framework Integrations

Framework Status Guide
ElizaOS Released Full plugin
AgentKit Compatible SDK integration
GOAT SDK In Review Planned plugin
LangChain Planned Custom LLM class

Architecture

┌─────────────────────────────────────────────────┐
│              Your Agent Framework               │
│         (ElizaOS, AgentKit, LangChain)          │
├─────────────────────────────────────────────────┤
│               BlockRun SDK                       │
│         (Handles x402 payments)                 │
├─────────────────────────────────────────────────┤
│               BlockRun API                       │
│         (Routes to providers)                   │
├─────────────────────────────────────────────────┤
│            AI Providers                          │
│   OpenAI • Anthropic • Google • DeepSeek • ...  │
└─────────────────────────────────────────────────┘

Common Patterns

Multi-Model Decision Making

Get multiple perspectives on important decisions:

def get_consensus(question: str) -> str:
    models = [
        "openai/gpt-5.4",
        "anthropic/claude-sonnet-4.6",
        "deepseek/deepseek-chat"
    ]

    opinions = []
    for model in models:
        response = client.chat(model, question)
        opinions.append(f"{model}: {response}")

    # Synthesize
    return client.chat(
        "openai/gpt-5.4",
        f"Synthesize these opinions:\n{chr(10).join(opinions)}"
    )

Cost-Optimized Routing

Use cheap models for routine tasks, premium for important ones:

def smart_route(task: str, importance: str) -> str:
    if importance == "high":
        model = "openai/gpt-5.4"  # $2.50/M
    elif importance == "medium":
        model = "anthropic/claude-haiku-4.5"  # $1.00/M
    else:
        model = "deepseek/deepseek-chat"  # $0.14/M

    return client.chat(model, task)

Session Budgets

Limit spending per agent session:

client = LLMClient(session_budget=10.00)  # Max $10

try:
    response = client.chat("openai/o1", expensive_prompt)
except InsufficientBudgetError:
    # Fallback to cheaper model
    response = client.chat("deepseek/deepseek-chat", expensive_prompt)

Async Operations

For high-throughput agents:

import asyncio

async def process_batch(items: list) -> list:
    tasks = [
        client.achat("deepseek/deepseek-chat", f"Process: {item}")
        for item in items
    ]
    return await asyncio.gather(*tasks)

results = asyncio.run(process_batch(my_items))

Available Models

Speed-Optimized

  • google/gemini-3-flash-preview — Fastest with thinking mode
  • google/gemini-3.1-flash-lite — Ultra-fast and cheapest
  • anthropic/claude-haiku-4.5 — Fast, good quality

Cost-Optimized

  • google/gemini-2.5-flash-lite — Best value ($0.10/$0.40 per 1M)
  • deepseek/deepseek-chat — Great value ($0.14/$0.28 per 1M)
  • nvidia/gpt-oss-120b — Free (NVIDIA-hosted)

Quality-Optimized

  • openai/gpt-5.4 — Best all-around
  • anthropic/claude-opus-4.6 — Best for nuanced tasks

Reasoning

  • openai/o3 — Advanced reasoning
  • openai/o1 — Complex logic
  • deepseek/deepseek-reasoner — Cheaper reasoning

Full list: Models Reference

Pricing

Pay only for what you use:

Your cost = Provider cost + 5%

Example costs per 1M tokens:

Model Input Output
DeepSeek Chat $0.29 $0.44
GPT-5.4 $2.63 $15.75
Claude Opus 4.6 $5.25 $26.25

Full pricing: Intelligence Pricing

Wallet Management

Environment Variable

export BLOCKRUN_WALLET_KEY=0x...

Programmatic

# Create new
client = LLMClient()  # Auto-generates if none exists

# Use existing
client = LLMClient(private_key="0x...")

# Check balance
balance = client.get_balance()
print(f"${balance} USDC")

# Get address to fund
print(client.get_address())

Security

  • Private key stored locally (~/.blockrun/wallet.json)
  • Only signatures sent to API
  • All payments verifiable on Basescan

:::warning Never commit BLOCKRUN_WALLET_KEY to git or share your private key. Use a dedicated agent wallet funded with only what the session needs. :::

Error Handling

from blockrun_llm import (
    LLMClient,
    InsufficientBalanceError,
    ModelNotFoundError,
    RateLimitError
)

try:
    response = client.chat(model, prompt)
except InsufficientBalanceError:
    print("Need to fund wallet")
except ModelNotFoundError:
    print("Invalid model ID")
except RateLimitError:
    print("Too many requests, backing off")

Best Practices

  1. Start with cheap models — Test with DeepSeek before using GPT-4o
  2. Set session budgets — Prevent runaway spending
  3. Use async for batch operations — Better throughput
  4. Monitor balance — Set up alerts when low
  5. Log model usage — Track costs per task type

What's next?

::::cards

:::card{title="ElizaOS Integration" href="../frameworks/elizaos.md" icon="Boxes"} Drop the BlockRun plugin into an ElizaOS agent. :::

:::card{title="SDK reference" href="sdk-developers.md" icon="Code"} Full Python, TypeScript, and Go SDK APIs, config, and error handling. :::

:::card{title="Set up your wallet" href="wallet-setup.md" icon="Wallet"} Fund on Base or Solana, manage budgets, and understand settlement. :::

::::