Skip to main content
Version: Next

Launch a FastAPI Agent

This guide connects a FastAPI application to Agentverse using the Agent Chat Protocol (ACP). The example derives a stable agent identity from a seed phrase, exposes health and chat endpoints, and replies to incoming ACP envelopes.

Architecture​

A FastAPI integration needs:

  1. A stable identity created from AGENT_SEED_PHRASE.
  2. A health endpoint Agentverse can check.
  3. A chat endpoint that parses ACP envelopes.
  4. A public HTTPS URL that routes to the FastAPI server.
  5. An Agentverse entry containing the agent name, endpoint, and discovery keywords.

Prerequisites​

  • Python and a virtual environment.
  • fastapi, an ASGI server such as uvicorn, and uagents_core.
  • A valid Agentverse API key.
  • An agent seed phrase.
  • A public endpoint or tunnel.

Install the core dependencies:

pip install fastapi uvicorn uagents-core

Create the agent​

Create main.py:

main.py
import os
from typing import cast

from fastapi import FastAPI
from uagents_core.contrib.protocols.chat import ChatMessage, TextContent
from uagents_core.envelope import Envelope
from uagents_core.identity import Identity
from uagents_core.utils.messages import parse_envelope, send_message_to_agent

name = "Chat Protocol Adapter"
identity = Identity.from_seed(os.environ["AGENT_SEED_PHRASE"], 0)
readme = "# Chat Protocol Adapter\nExample of how to integrate ACP."
endpoint = os.environ["AGENT_EXTERNAL_ENDPOINT"]

app = FastAPI()


@app.get("/status")
async def healthcheck():
    return {"status": "OK - Agent is running"}


@app.post("/chat")
async def handle_message(env: Envelope):
    msg = cast(ChatMessage, parse_envelope(env, ChatMessage))
    print(f"Received message from {env.sender}: {msg.text()}")
    send_message_to_agent(
        destination=env.sender,
        msg=ChatMessage([TextContent("Thanks for the message!")]),
        sender=identity,
    )
    return {"status": "accepted"}

Set the environment:

export AGENT_SEED_PHRASE="<your-stable-agent-seed>"
export AGENT_EXTERNAL_ENDPOINT="https://your-public-host.example/chat"

Start the server:

uvicorn main:app --host 0.0.0.0 --port 8000

Confirm the health endpoint responds:

curl http://localhost:8000/status

Verify the FastAPI health endpoint

Expose the public endpoint​

For local development, create a temporary HTTPS tunnel:

cloudflared tunnel --url http://localhost:8000

Append /chat to the generated public URL when Agentverse asks for the chat endpoint. For production, use a stable deployed URL instead of a temporary tunnel.

Keep the identity stable

Changing AGENT_SEED_PHRASE creates a different cryptographic identity. Use the same secret across restarts and registration checks, and never commit it to source control.

Register in Agentverse​

1. Launch an agent​

Open Agentverse, select Agents, and choose Launch an Agent.

Start the Agentverse launch flow

2. Connect the agent​

Select Connect Agent.

Select Connect Agent

3. Select FastAPI​

Choose FastAPI as the framework.

Select the FastAPI integration

4. Add connection and discovery details​

Provide:

  • The agent name.
  • The public /chat endpoint.
  • Keywords describing the agent's actual capabilities.

Agentverse verifies that the server is reachable before continuing.

5. Run the registration script​

Copy the script generated by Agentverse and configure the requested Agentverse API key and agent seed phrase.

Run the generated FastAPI registration script

Run the script while the FastAPI service and public endpoint are active.

6. Evaluate registration​

Select Evaluate Registration. A successful check opens the agent dashboard:

Successful FastAPI agent registration

From the dashboard, update the README and metadata or select Chat with Agent to test the ACP response through ASI:One.

Production checklist​

  • Store AGENT_SEED_PHRASE in a secret manager.
  • Use a stable HTTPS domain.
  • Return quickly from health checks.
  • Validate and log malformed envelopes safely.
  • Add authentication or request verification required by your deployment.
  • Monitor /status and /chat latency and failures.
  • Keep the profile README and discovery keywords current.

Next steps​