--- updatedAt: 2026-04-14T09:45:23.000Z agentTools: projectIndex: https://developers.newo.ai/llms.txt --- # 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: 1. **Event received** — `conversation_started` or `user_message` event fires from the integration (chat, phone, Telegram, etc.). 2. **CAMainFlow handles the event** — The ConvoAgent's main flow picks up the event, assembles the prompt, and generates a response. 3. **`broadcast_analyze_conversation` fires** — After the ConvoAgent generates its response, a broadcast event triggers parallel analysis. 4. **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. 5. **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.