NAF architecture and modules

The Newo Agent Framework (NAF) v3.9.0 is a modular multi-agent framework that powers every Newo AI Employee. This article is the definitive reference for the NAF's internal structure: core agents, flow organization, separated modules, versioning, and the modular architecture pattern. It is written for developers, solutions engineers, and technical partners who need to understand NAF internals.

Architecture overview

The NAF codebase is organized into two top-level directories:

naf/ — The core framework. Contains the primary agents, flows, skills, and shared attributes that handle conversations, booking, scheduling, SMS, email, browser automation, and more.
projects/ — Separated modules. Each module is an independent project with its own agents, flows, versioning, and registry configuration.

Core NAF agents

The NAF defines 12 agents. Each agent is a directory under naf/agents/ containing an agent.yaml definition and a flows/ directory.

Agent `idn`	Role	Description
`ConvoAgent`	Primary conversational agent	The main user-facing agent. Processes messages and responds across all conversational channels: phone, chat, Telegram, WhatsApp, and others. Contains 30 flows covering message handling, booking, scheduling, follow-up, voice actions, tool calling, observation, and more.
`GeneralManagerAgent`	Project manager and orchestrator	Keeper of task objects, task instructions, and business context. Handles project initialization, publishing, migrations, report generation, canvas building, and intent type management.
`ScenarioWriter`	Conversation scenario generator	Generates and writes conversation scenarios via a multi-step pipeline (draft → procedure mapping → formatting → validation). Produces structured scripts that the ConvoAgent follows during interactions.
`TaskManager`	Task lifecycle manager	Manages creation, assignment, tracking, and completion of tasks across the agent team.
`EmailWorker`	Email delivery specialist	Sends email messages on behalf of the agent team. Triggered by other agents via `SendSystemEvent`.
`SmsWorker`	SMS delivery specialist	Sends SMS messages to users. Triggered by inter-agent events rather than direct user interaction.
`MagicWorker`	Browser automation worker	Simulates keyboard and mouse actions within a browser, behaving like a human when interacting with web applications that lack APIs. Used for booking tables, scheduling spa appointments, and similar tasks.
`MultiLocationAgent`	Location routing controller	Controls the target location of a session. Used by businesses with multiple physical locations to route conversations and tasks to the correct branch.
`AgentCreator`	Account initialization agent	Handles automated agent creation and account initialization, including callback and incoming-event processing.
`SuperAgentProject`	Project-level metadata	Handles project-level metadata operations. Internal utility agent.
`ApifyCheckAvailabilityWorker`	Apify integration worker	Checks business availability using the Apify integration. Internal utility agent.
`TestAgent`	Regression testing agent	Used for automated regression testing. Internal utility agent.

Flow and skill organization

Flows group related skills around a specific capability. A flow YAML file defines the skills it contains and the events it subscribes to.

Each skill definition includes:

Field	Description
`idn`	Unique identifier for the skill within its flow.
`prompt_script`	Relative path to the `.nsl` or `.nslg` file containing the skill logic.
`runner_type`	Script engine: `nsl` or `guidance`. See below.
`model`	LLM configuration with `model_idn` and `provider_idn`.
`parameters`	Optional parameters passed to the skill at runtime.

NSL vs NSLG runner types

The NAF uses two script engines for skill prompt scripts:

Runner type	File extension	Template syntax	Description
`nsl`	`.nsl`	Jinja2 (`{% if %}`, `{% for %}`, `{{ }}`)	The primary script engine. Uses Python/Jinja2 template syntax with `{% %}` for control flow and `{{ }}` for expressions. Supports Python string methods, `json.loads()`, `re.sub()`, and other Python builtins.
`guidance`	`.nslg`	Handlebars (`{{#if}}`, `{{#each}}`, `{{Set()}}`)	Legacy script engine based on Handlebars syntax. Uses `{{#if condition}}...{{/if}}` for control flow and `{{Set(name=..., value=...)}}` for variable assignment. Still widely used in the codebase alongside NSL.

Both script engines share access to the same platform actions:

Action	Description
`GetCustomerAttribute(field=...)`	Read a project-level attribute.
`SetCustomerAttribute(field=..., value=...)`	Write a project-level attribute.
`GetPersonaAttribute(id=..., field=...)`	Read a per-user attribute from a persona.
`SetPersonaAttribute(id=..., field=..., value=...)`	Write a per-user attribute.
`SendSystemEvent(eventIdn=..., connectorIdn=...)`	Fire a system event to trigger skills in other flows/agents.
`SendMessage(message=...)`	Send a message to the user.
`SendCommand(commandIdn=..., integrationIdn=...)`	Send a command to an integration (e.g., voice, HTTP).
`GetTriggeredAct()`	Get the event/action that triggered the current skill.
`GetUser()`	Get the current user object.
`GetState(name=...)` / `SetState(name=..., value=...)`	Read/write flow-level state that persists across skill invocations within the same flow.
`GetDatetime(format=..., timezone=...)`	Get the current date/time.
`Gen(...)`	Call the LLM to generate text or structured JSON output.
`Return(val=...)`	Return a value from a skill (used when the skill is called by another skill).

The turn pipeline

When a message arrives, the platform processes it through a coordinated pipeline. Understanding this pipeline is essential for grasping how the Observer, Tool Caller, and ConvoAgent interact:

Event received — conversation_started or user_message event fires from the integration (chat, phone, Telegram, etc.).
CAMainFlow handles the event — The ConvoAgent's main flow picks up the event, assembles the prompt, and generates a response.
broadcast_analyze_conversation fires — After the ConvoAgent generates its response, a broadcast event triggers parallel analysis.
Three flows run in parallel:
- CAObserverFlow (queue mode) — Extracts user information and evaluates conversation quality.
- CAThoughtsFlow (interrupt mode) — Generates structured KEY DIRECTIVES for the next turn.
- CANewoToolCaller (queue mode) — Detects agent commitments and triggers backend actions.
Results feed back — Thoughts are stored in persona attributes, tools fire execution flows, and the cycle repeats on the next message.

ConvoAgent flows

The ConvoAgent is the largest agent with 30 specialized flows:

Flow	Purpose
`CAMainFlow`	Core message processing, conversation start/end, V2V prompting
`CAObserverFlow`	Parallel reasoning and conversation analysis
`CAThoughtsFlow`	Structured thought generation for guidance
`CANewoToolCaller`	Tool condition detection and execution
`CAMessageFlow`	Message formatting and delivery
`CABookingManagementFlow`	Booking creation and management
`CACheckingAvailabilityFlow`	Availability lookup
`CAScheduleFlow`	Calendar and meeting scheduling
`CASearchBookingFlow`	Existing booking search
`CAFollowUpFlow`	Follow-up message scheduling
`CAEndSessionFlow`	Session termination handling
`CADataInjectionFlow`	Runtime data injection
`CARagFlow`	Retrieval Augmented Generation
`CAAssessmentFlow`	Conversation quality assessment
`CAReportFlow`	Report generation
`CACalculatorFlow`	Numeric calculations
`CATimezoneFlow`	Timezone detection and conversion
`CAUserManagementFlow`	User data management
`CABroadcastConversationFlow`	Broadcast message handling
`CAExternalReply`	External reply processing
`CAThinkFlow`	Internal reasoning
`CAGen2SendAgentMessageFlow`	Gen2 agent message delivery
`CAGen2SendUserMessageFlow`	Gen2 user message delivery
`CAExecuteExternalTasksFlow`	External task execution
`CAActionCallTransferFlow`	Call transfer execution
`CAActionCallHangUpFlow`	Call hang-up execution
`CAActionCallDefineVoiceMailFlow`	Voicemail detection
`CAActionCallSendDialpadDigitsFlow`	DTMF digit sending
`CAActionSendEmailInformationFlow`	Email information dispatch
`CAActionSendSMSInformationFlow`	SMS information dispatch

Separated modules

The NAF is extended by independent versioned modules that add specialized capabilities — outbound calling, lead nurturing, conversation assessment, messaging platform integrations, and booking system integrations. Each module maintains its own agents, flows, and version lifecycle, allowing Newo to update a single capability without redeploying the entire framework.

Modules update automatically when new versions are published to the registry. The platform schedules updates during off-peak hours based on each account's preferred update time.

Changelog

NAF architecture and modules: initial publication

Published developer reference covering NAF v3.9.0 architecture, all 12 core agents, 30 ConvoAgent flows, 9 separated modules, modular architecture pattern, and the registry-based versioning system.