Receitas
Contribuir
Começar
Voltar para receitas

Dynamic Instructions

Atualize o prompt do agente durante a sessão.

Python / TypeScriptInicianteAgora
GitHub

Guia de implementação

Neste guia

Agora Conversational AI — Instructions Recipe (Python)

License: MIT Python Bun

The instructions recipe in the Agora Conversational AI recipes family. It demonstrates how to configure the agent through system-prompt features, context injection, and live runtime updates — all using Agora's managed OpenAI vendor.

This recipe is zero-key: it uses Agora's managed OpenAI vendor (keyless, just like Deepgram STT and MiniMax TTS). OPENAI_API_KEY is optional — set it only if your Agora account requires a bring-your-own key. There is no separate LLM service to run or expose.

Prerequisites

The same commands work on macOS, Linux, and Windows. On macOS/Linux, setup uses python3; on Windows, it uses the Python launcher (py) or python. WSL and virtualenv activation are not required.

Run It

bash
# 1. Install dependencies
bun run setup

# 2. Add Agora credentials (CLI), or edit server/.env.local by hand
agora login
agora project use <your-project>
agora project env write server/.env.local

# 3. Start the agent backend and web frontend
bun run dev

Open http://localhost:3000 → Start Conversation → speak.

Working from a clone

If you cloned this repo (rather than scaffolding via the Agora CLI), the steps above are complete as written: bun run setup creates the Python venv and installs web dependencies, then bun run dev brings up both services. You still need Agora credentials in server/.env.local before a conversation can connect.

Services:

Deploy

Deploy web (Next.js) and server (a reachable FastAPI backend). Set AGENT_BACKEND_URL in the web deployment so the Next rewrites reach the backend.

A backend-only Docker image is published to ghcr.io/AgoraIO-Conversational-AI/recipe-agent-instructions on v* tags. It runs the agent backend on :8000 only (no separate LLM port — OpenAI is Agora-managed).

Environment variables

Backend env file: server/.env.example.

VariableRequiredDefaultNotes
AGORA_APP_ID✅—Agora Console → Project → App ID
AGORA_APP_CERTIFICATE✅—Agora Console → Project → App Certificate
OPENAI_API_KEY—Optional — Agora manages the OpenAI key by default; set only for bring-your-own key
OPENAI_MODELgpt-4o-miniOpenAI model name
REPLY_STYLEnormalnormal or short (short → terse + low max_tokens)
ASSISTANT_NAMEAdaInjected as {{assistant_name}} in the system prompt
AGENT_EXIT_MESSAGEThanks for chatting — goodbye!Closing instruction appended to the system prompt
AGENT_GREETINGbuilt-inOptional opening line override
AGENT_BACKEND_URL (web deploy)✅—Required when deploying web separately

Commands

bash
bun run setup            # install web deps + create server/ venv
bun run dev              # backend (:8000) + web (:3000)

bun run doctor           # prerequisite check (no creds needed)
bun run doctor:local     # + .env.local + credentials check

bun run verify           # web-only gate (no Agora creds needed)
bun run verify:local     # full local gate: backend compile + web build
bun run clean            # remove venvs and build artifacts

Tests run standalone (no Agora cloud needed): pytest in server/, plus bun run verify in web/. CI runs them on Linux/macOS/Windows × Python 3.10 & 3.13.

Architecture

text
Browser (localhost:3000)
  │  fetch /api/*
  ▼
Next.js  ──rewrite──▶  Agent backend  (server/, localhost:8000)
                          │  starts agent session (managed OpenAI vendor)
                          ▼
                       Agora ConvoAI Cloud
                          │  Deepgram STT (managed)
                          │  OpenAI LLM (Agora-managed, keyless)
                          │  MiniMax TTS (managed)
                          ▼
                       RTM transcript / metrics → web UI

The browser only ever calls Next /api/*, which rewrites to the agent backend. The agent backend owns Agora tokens and agent lifecycle. LLM calls go through Agora's managed OpenAI integration — no separate endpoint to expose. See ARCHITECTURE.md.

What You Get

  • A Next.js web client (:3000) that drives the RTC/RTM lifecycle and only ever calls /api/*.
  • A FastAPI agent backend (:8000) that owns Agora token generation and the agent session lifecycle.
  • The /api/get_config · /api/startAgent · /api/stopAgent contract between the web client and the backend (Next rewrites, no Route Handlers).
  • Agora-managed keyless OpenAI — the same zero-key model used for Deepgram STT and MiniMax TTS. Agora provisions OpenAI access on your behalf; OPENAI_API_KEY is optional (set it only if your Agora account requires a bring-your-own key).
  • template_variables — inject {{assistant_name}} and {{today}} into the system prompt at agent-start time.
  • REPLY_STYLE — set to short for terse one-sentence answers (low max_tokens) or normal (default) for fuller responses.
  • POST /updateInstructions — swap the running agent's system prompt at any time via Agora's update API without restarting the session.
  • AGENT_EXIT_MESSAGE — append a closing instruction so the agent delivers a consistent goodbye line when the user ends the conversation.

How It Works

  1. The browser calls /api/get_config, which Next rewrites to the backend; the backend mints an Agora token from AGORA_APP_ID + AGORA_APP_CERTIFICATE.

  2. The browser joins the RTC channel, then calls /api/startAgent; the backend starts an agent session using the managed OpenAI vendor with the configured system prompt (including template_variables and REPLY_STYLE settings).

  3. The user speaks. Agora runs STT (Deepgram nova-3), then sends the transcript to the Agora-managed OpenAI endpoint.

  4. OpenAI processes the request using the configured OPENAI_MODEL and returns a response. The REPLY_STYLE setting controls verbosity (short caps max_tokens; normal allows fuller replies).

  5. Agora runs TTS (MiniMax) on the reply and plays it back in the channel.

  6. While a session is running, you can swap the agent's system prompt without restarting — call POST /updateInstructions with the agent ID and new instructions:

    bash
    curl -X POST http://localhost:8000/updateInstructions \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<agent_id_from_startAgent>", "instructions": "You are a pirate. Arr!"}'

    The next agent turn will use the new prompt. This is the key capability this recipe demonstrates: a live configurable agent personality driven entirely by system-prompt features, with no separate LLM service to maintain.

  7. AGENT_EXIT_MESSAGE appends a closing instruction to the system prompt so the agent delivers a consistent goodbye line when the conversation ends.

  8. /api/stopAgent ends the session.

Repo Map

  • web/ — Next.js frontend (:3000); RTC/RTM lifecycle and UI.
  • server/ — FastAPI agent backend (:8000); Agora tokens + agent lifecycle, managed OpenAI vendor.
  • ARCHITECTURE.md — system shape and component boundaries.
  • AGENTS.md — guide for coding agents working in this repo.

Troubleshooting

ProblemFix
Agent starts but never respondsCheck OPENAI_MODEL is a valid model name. If your Agora account requires a key, ensure OPENAI_API_KEY is set in server/.env.local.
Local calls fail / hang under a proxyConfigure your proxy to route 127.0.0.1 and localhost DIRECT.

More Docs

License

Released under the MIT License.