Skip to content

Quickstart

Install and run your first agent

By the end of this page you will have a registered Replicate agent answering a real prompt through the framework's routing and resilience layer — verified by the built-in diagnostics command.

Who this is for: Python developers with a Replicate account.
What you'll accomplish: A working llama_chat agent invoked through AgentExecutor, plus a clean replicate-agent doctor report.
Prerequisites: Python 3.10+, pip, and a Replicate API token.
Estimated time: 10 minutes.

Steps

  1. Install the package

    The core install is dependency-light; extras like OpenTelemetry are opt-in.

  2. Set your token and run the doctor

    doctor checks the token, Python version, dependencies, and API connectivity before you write any code.

  3. Register and run an agent

    One decorator registers the agent; AgentExecutor streams the result.

1. Install the package

Install from PyPI 
pip install replicate-mcp-agents

Expected output (tail)

Successfully installed replicate-mcp-agents-0.8.0 replicate-2.x mcp-1.x ...

If you want the full bundle — OpenTelemetry export, HTTP transports, and Latitude integration — install pip install "replicate-mcp-agents[all]" instead. The optional extras matter later, not for this page.

2. Set your token and run the doctor

Export the token, then verify the environment 
export REPLICATE_API_TOKEN=r8_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
replicate-agent doctor

Expected output

✓ REPLICATE_API_TOKEN detected (masked: r8_x...xxxx)
✓ Python 3.10+ available
✓ Required dependencies importable
✓ Replicate API reachable
✓ Config directory writable (~/.replicate)
All checks passed.

If it fails

# "REPLICATE_API_TOKEN is not set" → re-export in THIS shell, then re-run:
env | grep REPLICATE

You now have a verified environment. Everything that follows assumes doctor is green — if a later step fails, re-run it first; a missing token is the single most common failure mode (it is Failure #1 in the runbook).

3. Register and run an agent

An agent is just a function that builds the payload for a Replicate model, plus metadata the framework uses for routing and MCP tool definitions. Save this as first_agent.py:

import asyncio
from replicate_mcp import agent
from replicate_mcp.agents.execution import AgentExecutor

@agent(
    model="meta/meta-llama-3-8b-instruct",
    description="Fast chat model for general queries",
    tags=["chat", "fast"],
    estimated_cost=0.002,
)
def llama_chat(prompt: str) -> dict:
    return {"prompt": prompt}

async def main():
    executor = AgentExecutor(max_concurrency=5)
    async for chunk in executor.run("llama_chat", {"prompt": "Say hello in 5 words"}):
        print(chunk)

asyncio.run(main())
Run it 
python first_agent.py

Expected output

{'output': 'Hello there, nice to meet!', 'model': 'meta/meta-llama-3-8b-instruct', 'latency_ms': 812}

That call already went through the production layer: a per-model circuit breaker (trips after 5 consecutive failures), retry with decorrelated jitter (2 retries, 0.5 s base delay), and concurrency capping at 5 — all defaults you can tune later.

Verification

You're done when

  • replicate-agent doctor reports all checks passed.
  • python first_agent.py prints at least one chunk containing an output key.
  • No traceback mentioning AuthenticationError or CircuitOpenError.

Common mistakes

SymptomCauseFix
{"error": "REPLICATE_API_TOKEN is not set"} Token exported in a different shell, or not at all export REPLICATE_API_TOKEN=... in the same shell, confirm with env | grep REPLICATE
AgentNotFoundError: llama_chat The module defining the @agent was never imported before executor.run() Keep registration and execution in the same module, or import the agents module first
429 Too Many Requests in logs Concurrency too high for your Replicate rate limit Lower max_concurrency or attach a TokenBucket — see Resilience & caching

Next steps