Praison AI

Server: Unified

Deploy a unified server that combines the agents API, A2A and A2U providers

Deploy a unified server that combines the agents API, A2A and A2U providers in a single endpoint.

CLI

bash
pip install "praisonai[serve]"
export OPENAI_API_KEY="your-key"

# Start unified server — mounts agents-api + a2a from agents.yaml, plus a2u
praisonai serve unified --file agents.yaml --port 8765

Expected Output:

✓ Starting unified server on 127.0.0.1:8765
  Providers: agents-api, a2a, a2u
  Discovery: /__praisonai__/discovery

The server only advertises providers it actually mounts. agents-api and a2a run the workflow in --file, so they are mounted only when that file exists:

--fileProviders
Existsagents-api, a2a, a2u
Missinga2u
Diagram

Yes

No

praisonai serve unified

–file exists?

agents-api + a2a + a2u

a2u only

Agent

Define the agents the unified server runs in agents.yaml:

yaml
framework: praisonai
topic: "Answer user questions"
roles:
  assistant:
    role: Helpful AI Assistant
    goal: Help users with their questions
    backstory: You are a friendly assistant.
    tasks:
      answer:
        description: "Answer: {topic}"
        expected_output: A clear answer
bash
curl -X POST http://localhost:8765/agents \
  -H "Content-Type: application/json" \
  -d '{"query": "What is PraisonAI?"}'

Response:

json
{"response": "PraisonAI is ..."}

POST /agents accepts query (or message). A body that is not a JSON object returns 400; an agent failure returns 500.

Security

praisonai serve unified mounts agent-driving routes (POST /agents, POST /a2a), so binding it to a non-localhost interface without authentication is refused.

bash
# Localhost — no key required
praisonai serve unified --port 8765

# Remote — key required (via env var)
export PRAISONAI_SERVE_API_KEY="your-secret"
praisonai serve unified --port 8765 --host 0.0.0.0

# Or via flag
praisonai serve unified --port 8765 --host 0.0.0.0 --api-key "your-secret"

Clients send the key in Authorization: Bearer … or X-API-Key: …. Only /health, / and /.well-known/agent.json are public.

Diagram

Yes

No

Set

Missing

praisonai serve unified

Host is
localhost?

Start — no key needed

–api-key or
PRAISONAI_SERVE_API_KEY?

Start — Bearer / X-API-Key enforced

SystemExit — refuse to bind

Unified Endpoints

EndpointMethodProviderNeeds --file?Description
/agentsPOSTagents-apiYesRun the agents YAML workflow
/a2aPOSTa2aYesA2A JSON-RPC message/send (error codes)
/.well-known/agent.jsonGET–NoAgent card; includes url only when a2a is mounted
/a2u/infoGETa2uNoA2U info
/a2u/events/<stream>GETa2uNoA2U event stream
/__praisonai__/discoveryGET–NoDiscovery document
/healthGET–NoHealth check
/GET–NoLanding JSON with the mounted providers list

Agent Card

bash
curl http://localhost:8765/.well-known/agent.json

Response (with --file):

json
{
  "name": "PraisonAI Unified",
  "description": "PraisonAI Unified Server",
  "version": "1.0.0",
  "url": "http://127.0.0.1:8765/a2a"
}

Without --file, the url key is omitted because /a2a is not mounted.

Discovery Document

bash
curl http://localhost:8765/__praisonai__/discovery

Response (with --file):

json
{
  "schema_version": "1.0.0",
  "server_name": "praisonai-unified",
  "providers": [
    {"type": "agents-api", "name": "Agents API", "capabilities": ["invoke"]},
    {"type": "a2a", "name": "A2A Protocol", "capabilities": ["agent-card", "message-send"]},
    {"type": "a2u", "name": "A2U Event Stream", "capabilities": ["subscribe", "stream"]}
  ],
  "endpoints": [...]
}

Without --file, providers contains only a2u.

Client Usage

Use the unified endpoints CLI to interact with any provider:

bash
# List all endpoints
praisonai endpoints list --url http://localhost:8765

# Filter by provider type
praisonai endpoints list --url http://localhost:8765 --type agents-api

# Get discovery document
praisonai endpoints discovery --url http://localhost:8765

# Health check
praisonai endpoints health --url http://localhost:8765

CLI Options

OptionDefaultDescription
--port8765Server port
--host127.0.0.1Server host
--api-key–API key. Required when --host is not 127.0.0.1 / localhost / ::1. Can also be set via PRAISONAI_SERVE_API_KEY. Enforces Authorization: Bearer / X-API-Key on every route except /health, /, /.well-known/agent.json.
--fileagents.yamlAgents YAML file. agents-api and a2a are mounted only when it exists

Environment Variables

VariableDefaultDescription
PRAISONAI_SERVE_API_KEY–API key required to bind praisonai serve unified on a non-localhost host. The server exits with SystemExit if this is unset and no --api-key is passed when --host is not localhost. Also drives the _api_auth middleware when the server is running.

Provider Types

TypeDescription
agents-apiRuns the agents YAML workflow (POST /agents)
a2aAgent-to-agent protocol (POST /a2a)
a2uAgent-to-user event stream (always mounted)

Troubleshooting

IssueFix
Port in uselsof -i :8765
Missing depspip install "praisonai[serve]"
No API keyexport OPENAI_API_KEY="your-key"
Provider not foundCheck discovery document. agents-api / a2a need an existing --file
POST /agents returns 404 / 405--file is missing, so only a2u is mounted
--api-key ... is required when binding to a non-localhost host at startupSet PRAISONAI_SERVE_API_KEY=... (or --api-key ...), or bind to 127.0.0.1 / localhost for a private-only server.

Related