​
Synopsis

runagent serve [PATH] [OPTIONS]

​
Description

The serve command starts a local FastAPI server for testing your agent before deployment. It provides hot reload, logging, and debugging capabilities.

​
Options

OptionDescriptionDefault
--port, -pPort to run server on8000
--host, -hHost to bind to127.0.0.1
--reloadEnable auto-reloadtrue in dev
--no-reloadDisable auto-reload-
--workers, -wNumber of worker processes1
--log-levelLogging levelinfo

​
Examples

​
Basic Usage

# Serve current directory
runagent serve .

# Serve specific project
runagent serve ~/projects/my-agent

# Custom port
runagent serve . --port 8080

​
Advanced Usage

# Production-like settings
runagent serve . --no-reload --workers 4

# Debug mode
runagent serve . --log-level debug

# Expose to network
runagent serve . --host 0.0.0.0

​
Available Endpoints

Once running, your agent exposes:

EndpointMethodDescription
/GETWelcome page
/healthGETHealth check
/invokePOSTInvoke agent
/streamPOSTStream responses
/docsGETAPI documentation

​
Testing Your Agent

​
Health Check

curl http://localhost:8000/health

​
Invoke Agent

curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello, agent!"}'

​
Stream Response

curl -X POST http://localhost:8000/stream \
  -H "Content-Type: application/json" \
  -d '{"query": "Tell me a story"}' \
  --no-buffer

​
Development Features

​
Hot Reload

Changes to your agent code automatically restart the server:

INFO:     Detected change in 'agent.py'
INFO:     Reloading...

​
Request Logging

All requests are logged with details:

INFO:     127.0.0.1:53234 - "POST /invoke HTTP/1.1" 200 OK
DEBUG:    Request body: {"query": "test"}
DEBUG:    Response time: 0.123s

​
Error Display

Errors show full traceback in development:

ERROR:    Exception in ASGI application
Traceback (most recent call last):
  File "agent.py", line 42, in process
    ...

​
Configuration

The server reads from runagent.config.json:

{
  "dev_server": {
    "port": 8000,
    "reload": true,
    "log_level": "info"
  }
}

​
Troubleshooting

​
See Also