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)

This is

• 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

This is not

• 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)

Direction

• Push-based, with an enforced pull-first step

Source of truth

• Avaamo Studio is always authoritative

Rules

• 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.

Supported sync strategies

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

Prompts

• Plain text or Markdown
• One file per prompt
• Human-readable and diff-friendly

Functions

• 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

Manifest (agent metadata)

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

ENV file

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

Example file structure

agents/
  appointment-agent/
    prompt.md
    functions/
      getAvailableSlots.js
      getAvailableSlots.json
    manifest.json
    .env

Example Manifest

{
  "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.