Avaamo Agent Code-First Workflow
A code-first development framework that lets backend engineers author Avaamo agents locally (prompts + functions) in a real IDE and push them into Avaamo Studio, which remains the system of record and execution runtime.
This project exists to fix a real problem:
Avaamo Studio is powerful, but prompt and function authoring inside a browser does not scale for serious engineering work.
What this is (and what it is not)
$3
- A framework / SDK for writing Avaamo agent prompts and functions locally
- A sync tool that:
- Pulls the latest agent state from Avaamo Studio
- Lets you edit prompts/functions in files
- Pushes updates back into Avaamo Studio
- A developer workflow, not a replacement for Avaamo Studio
$3
- Not an agent runtime
- Not an alternative execution engine
- Not a local emulator for Avaamo agents
- Not a UI replacement for Avaamo Studio
All agent execution happens exclusively in Avaamo Studio’s backend.
This tool is strictly for authoring and synchronization.
Core idea
Avaamo Studio today is a web-only agent development environment.
This project introduces a code-first workflow on top of it.
Flow:
1. Avaamo Studio remains the source of truth
2. Developers pull agent definitions locally
3. Prompts are edited as text/Markdown
4. Functions are written as real JS/TS code
5. Changes are pushed back to Avaamo Studio
6. Avaamo executes the agent using OpenAI Realtime + configured TTS providers
Who this is for
- Backend engineers
- People who want:
- Git history
- Diffable prompts
- Typed functions
- Real refactoring tools
- Proper code reviews
If you’re comfortable editing prompts in a browser and clicking save, this tool is not for you.
Sync model (important)
$3
- Push-based, with an enforced pull-first step
$3
- Avaamo Studio is always authoritative
$3
- On startup or before pushing:
- The tool pulls the latest agent state from Avaamo Studio
- If another developer modified the agent in the web UI:
- Local files are updated first
- You resolve conflicts locally
- Only then are changes pushed back
This avoids silent overwrites and keeps Avaamo as the canonical system.
Handling missing or incomplete APIs
This project assumes best-case API availability from Avaamo, but does not depend on it.
$3
1. Official Avaamo APIs (preferred)
2. Headless browser automation (fallback)
- Puppeteer-style DOM interaction
- Used only when APIs are missing or incomplete
This is intentionally pragmatic.
The goal is reliability, not architectural purity.
How agents are authored locally
$3
- Plain text or Markdown
- One file per prompt
- Human-readable and diff-friendly
$3
- Written in JavaScript or TypeScript
- Two files per function
- One file for function definition written as a JSON schema
- One file for function code written in JS
- Function definition and implementation files must share the same base filename.
- Strongly typed where possible
- Mapped to Avaamo functions during sync
$3
A lightweight manifest ties everything together.
Includes metadata required to map the local agent to its configuration in Avaamo.
- agentURL
- skillURL
- agentName
- Prompt file
- Function names
$3
Authentication credentials are resolved via local configuration and are never stored in the repository.
.env file is gitignored and not to be committed
.env is per agent
$3
``
agents/
appointment-agent/
prompt.md
functions/
getAvailableSlots.js
getAvailableSlots.json
manifest.json
.env
$3
`
json
{
"agentURL": "https://x1.avaamo.com/#/agents/1846/edit",
"skillURL": "https://x1.avaamo.com/#/agents/1846/edit?prompt=745",
"agentName": "Appointment Agent",
"prompt": "./prompt.md",
"functions": [
"getAvailableSlots"
]
}
``
Runtime model
- Execution always happens in Avaamo Studio
- Avaamo handles:
- OpenAI Realtime
- Function invocation
- TTS (OpenAI, ElevenLabs, others)
- This SDK:
- Uploads prompts
- Uploads function definitions
- Does not execute agents locally
No local simulation. No partial execution. No divergence.
Version control strategy
- Git tracks:
- Prompt files
- Function code
- Manifests
- Avaamo tracks:
- Deployed agent versions
- Execution history
This keeps Git clean and Avaamo authoritative.
Error handling & safeguards
- Pull-before-push is enforced
- Remote changes are detected
- Conflicts are surfaced explicitly
- No silent overwrites
- No partial uploads
- If the sync fails halfway, nothing is committed remotely.
Why this exists
Web UIs are fine for demos.
They are bad for:
- Large prompts
- Refactoring
- Collaboration
- Reviews
- History
- Safety
This project gives Avaamo Studio a real engineering workflow without changing its runtime model.