Quickstart

This path takes a developer from API spec to a deployed Telegram or WhatsApp agent.

1. Install and authenticate

pip install -e packages/cli
nexus auth login --api-key gaadmlive_your_key_here
nexus projects list

Expected output:

Authenticated as developer@example.com
Projects
  No projects yet. Run nexus integrate or nexus projects create.

2. Generate an agent from OpenAPI

nexus integrate https://api.example.com/openapi.json \
  --non-interactive \
  --name dayplan-agent \
  --description "Calendar planning over Telegram and WhatsApp"

The generated directory contains:

dayplan-agent/
  nexus-agent.yaml
  SOUL.md
  tools/
  .env.example

3. Review and deploy

nexus validate ./dayplan-agent/nexus-agent.yaml
nexus deploy ./dayplan-agent/nexus-agent.yaml

Minimal deployment config:

apiVersion: nexus/v1
kind: Agent
metadata:
  name: dayplan-agent
personality:
  soul_file: ./SOUL.md
tools:
  builtin:
    - web_search
  mcp: []

4. Connect a channel

Telegram is the fastest beta channel because BotFather can create a bot in minutes.

nexus channels connect telegram --project dayplan-agent --bot-token "$TELEGRAM_BOT_TOKEN"
nexus channels status --project dayplan-agent

Then send your bot:

hello, what can you do?

5. Test the API path

Use the project test command before sending real user traffic.

nexus test --project dayplan-agent --message "What appointments do I have this week?"

Or call the Responses-compatible API directly:

curl -sS https://api.generalaugment.com/v1/responses \
  -H "Authorization: Bearer gaadmlive_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "balanced",
    "input": "What appointments do I have this week?",
    "metadata": {"project": "dayplan-agent"}
  }'

Python example:

import httpx

response = httpx.post(
    "https://api.generalaugment.com/v1/responses",
    headers={"Authorization": "Bearer gaadmlive_your_project_key"},
    json={"model": "balanced", "input": "What can you do?"},
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(
    next(
        part["text"]
        for item in data["output"]
        if item["type"] == "message"
        for part in item.get("content", [])
        if part.get("type") == "output_text"
    )
)

Next, read Connect Your API and Telegram setup.