# Ema Builder Platform Documentation

Full corpus. Each section header is the canonical page URL.


================================================================================
# Introduction
URL: https://builder.ema.ai/introduction
================================================================================

Introduction This section provides foundational context for the Ema Builder Platform: what Ema is, the concepts that underpin it, a walkthrough of the user interface, and a glossary of key terms. In This Section PageDescriptionWhat Is Ema?Platform overview, AI Employee interfaces, EmaFusion™, and how Ema differs from RPA and copilots.Key ConceptsAgents vs. AI Employees, agent categories, multi-agent orchestration via GWE, user roles, and Human-in-the-Loop.Platform TourNavigating the Ema UI: signing in, AI Employees page, Autopilot, Voice, templates, integrations, conversational workspace, and settings.GlossaryAlphabetical reference of platform and domain terminology. Prerequisites No prior Ema experience is required. This section is designed for builders, admins, and anyone evaluating the platform for the first time. Next Steps After completing this section, proceed to Core Concepts for a deeper look at the Generative Workflow Engine and workflow construction.

================================================================================
# Glossary
URL: https://builder.ema.ai/introduction/glossary
================================================================================

Glossary A unified alphabetical reference of terms used throughout the Ema Builder Platform documentation. A Action-Based Rule -- A QA evaluation rule that verifies actions taken in external systems (CRM, ticketing) rather than analyzing transcript content alone. Dashboard -- A spreadsheet-style AI Employee interface optimized for high-volume, repeatable workflows such as triage queues or data enrichment. Agent (Platform) -- A modular AI component that performs a specific task within the Ema platform, such as transcription, categorization, or rule validation. An autonomous process combining planning, reasoning, and memory. AI Employee (AIE) -- A configured instance that coordinates multiple agents to accomplish a specific business objective. AI Employees are orchestrated by the Generative Workflow Engine and represent complete end-to-end workflows. Audit Log -- A chronological record of actions, configuration changes, and workflow executions within a workspace or AI Employee. Audit logs provide traceability for compliance, debugging, and operational review. Autopilot -- An AI-assisted creation tool that lets you describe the AI Employee you want in natural language and have Ema generate a starting workflow automatically. Available as an entry point on the AI Employees page. Auto-Fail -- A critical QA rule that, when failed, results in an automatic score of zero regardless of other parameter results. Auto-Learning -- Ema's batch calibration feature that automatically generates and refines QA parameter instructions using a golden dataset of human-graded examples. B Binding -- The mechanism by which a workflow definition connects data sources to action inputs. Sources include outputs from other actions, workflow inputs, constants, and persona widget names. Builder -- A user role responsible for designing and assembling multi-agent workflows, either from scratch or by customizing an AI Employee template. C Call Driver -- The most specific (L3) level of contact reason categorization, representing the root cause for a customer call. Contact Reason -- Hierarchical categorization of why customers are calling, organized into L1 (high-level), L2 (detailed), and L3 (specific) levels. Continuous Learning -- Ema's feature for improving evaluation accuracy incrementally through feedback provided during daily quality reviews, as distinct from batch Auto-Learning. CSAT (Customer Satisfaction) -- A metric measuring customer satisfaction with a service interaction, often collected via post-call surveys or predicted by AI analysis. Custom Code Agent -- A GWE agent type that allows builders to execute arbitrary code logic within a workflow. Custom Code agents enable advanced transformations, calculations, or integrations that go beyond the capabilities of pre-built agents. D Data and Resources Agent -- An agent category that leverages knowledge graphs and other repositories to surface information relevant to the current task. Dead Air -- Periods of silence during a call where neither party is speaking. Tracked as part of silence time analysis. Diarization -- The process of separating audio into segments corresponding to different speakers (agent vs. customer). Document -- An AI Employee interface providing live co-authoring inside a Word/Google Docs-style environment for drafting and reviewing long-form content. E EmaFusion -- Ema's proprietary Mixture-of-Experts model that routes each subtask to the optimal LLM from 40+ models across 9+ providers, with cascading fallback when confidence thresholds are not met. End User -- A user role that interacts with a finished AI Employee to obtain outcomes but cannot alter its configuration. G Glossary (Feature) -- A per-AI-Employee feature that defines custom vocabulary (terms and definitions) to ensure consistent, accurate responses aligned with an organization's terminology. Uses whole-word, case-insensitive matching with strict word boundaries. Golden Dataset -- A collection of transcripts with verified human evaluations (Pass/Fail/N/A for each parameter) used to train and calibrate the Auto-Learning system. GWE (Generative Workflow Engine) -- Ema's orchestration layer that coordinates multiple agents within a workflow, managing data flow, dependencies, and execution. Provides a visual builder and a curated library of reusable agents. H Human-in-the-Loop (HITL) -- A capability allowing agents to seek human help mid-task for disambiguation, assistance, or approval. Can be conversational (chat) or structured (dashboards). I Integration -- A connector linking an Ema workspace to an external application (e.g., Salesforce, ServiceNow). Each integration authenticates with the target system and scopes read/write permissions. Interaction -- A single customer service call processed by Agent QA, including audio, transcript, and all evaluation results. K Knowledge Base -- A collection of documents (policies, procedures, product information) that Ema references when evaluating knowledge-verified rules or answering questions. Knowledge-Verified Rule -- A QA evaluation rule that cross-references transcript content against knowledge base documents to verify information accuracy. M Maintenance Mode -- A workspace-level or AI-Employee-level state that temporarily suspends workflow execution for planned updates or configuration changes. While in maintenance mode, incoming requests are held or rejected with a maintenance notice. Multi-Binding -- A workflow configuration where multiple upstream action outputs are bound to a single array-typed input port. Elements from skipped actions are removed; if all elements are skipped, the binding is treated as absent. N Named Inputs -- Key-value pairs configured as named bindings in a workflow, allowing users to pass supplementary context (search results, external tool outputs) to an action beyond its primary query. P Parameter -- A QA evaluation criterion or rule used to assess agent performance. Each parameter has pass/fail criteria and a weight. PII (Personally Identifiable Information) -- Sensitive customer data (names, account numbers) that is detected and masked by Ema during processing. Pre-Built AI Employee -- A template from Ema's catalog providing a ready-to-deploy blueprint for a specific use case (e.g., Agent Assist, Employee Assistant). Protected Parameter -- A QA parameter that achieved 90%+ accuracy during Auto-Learning and is excluded from further automatic modification. Q QA Form -- A document defining all evaluation parameters, their criteria, weights, and criticality levels. QA Score -- The weighted overall score (0--100) calculated from all parameter results, representing the quality of a customer service interaction. S Scorecard -- A summary view displaying all parameter evaluations for a single interaction, including pass/fail status and Ema's reasoning. Sentiment Analysis -- AI analysis of customer emotional state during an interaction, categorized as Positive, Neutral, Negative, or Mixed. Skill Agent -- An agent category that applies domain-specific capabilities, drawing on user data, enterprise knowledge bases, external systems, or the open web. T Transcript -- The text representation of a call conversation, including speaker labels and timestamps. Trigger -- The event that initiates a workflow execution (e.g., a chat message, a scheduled event, or an API call). Trigger-when -- A boolean expression on a workflow action instance that is evaluated at runtime. If true, the action executes; if false, it is skipped along with dependent downstream actions. W Weight (Weightage) -- A numerical value (0--10) indicating the importance of a parameter in calculating the overall QA score. Widget -- A named configuration block attached to a persona that provides shared settings consumed by workflow actions at runtime. Workflow -- A directed acyclic graph (DAG) of action instances, defined in a WorkflowDef, that the Generative Workflow Engine parses, validates, and executes. Each node is an action instance; each edge is a binding. Workflow Builder -- The visual interface for creating and modifying AI Employee workflows, including agent configuration and data flow connections. WorkflowDef -- The protocol buffer definition of a workflow, specifying action instances, their bindings, triggers, conditionals, and outputs. Workflow Version History -- A feature that tracks changes to workflow definitions over time, allowing builders to view previous versions, compare differences, and restore earlier configurations when needed. Workspace -- An organizational workspace in Ema containing AI Employees, integrations, users, and configuration. All resources within a workspace share the same permission and policy context.

================================================================================
# Key Concepts
URL: https://builder.ema.ai/introduction/key-concepts
================================================================================

Key Concepts This page formalizes the core agentic AI concepts that underpin Ema's Builder Platform. These ideas inform everything from solution design to day-to-day operations. Agents: The Building Blocks of Work An agent is an autonomous process that combines planning, reasoning, and memory to complete a clearly scoped task. Ema provides three broad categories of agents: CategoryPurposeData and Resources agentsLeverage knowledge graphs and other repositories to surface information relevant to the task.Action agentsDecide on and execute operations within external applications, typically via APIs.Skill agentsApply domain-specific capabilities, drawing on user data, enterprise knowledge bases, external systems, or the open web to accomplish a specialist activity. AI Employees: Orchestrated Multi-Agent Workflows An AI Employee is a higher-order construct that coordinates multiple specialized agents to perform an end-to-end role. The orchestration is handled by the Generative Workflow Engine (GWE), which offers a visual builder and a curated library of agents so that you can compose, observe, and iterate on complex workflows without writing code. This framework allows Ema to deliver deeper automation, higher accuracy, and better explainability than standalone agents assisting humans in a role. Why Multi-Agent Systems Are Better Enterprise processes worth automating are typically repetitive and complex. AI Employees address both: Predictable and consistent outcomes. Agentic workflows repeatedly execute multi-step procedures with high confidence. Ability to handle complexity. Where single agents plateau at roughly four to five steps, AI Employees reason across many. Superior user experience. The architecture supports richer UI surfaces, explainability, and seamless human-in-the-loop collaboration. Key distinction: Agents perform tasks; AI Employees perform work. Multi-Agent Orchestration via GWE The Generative Workflow Engine is the orchestration layer that coordinates multiple agents within a workflow. It manages data flow, dependencies, and execution order. AI Employees are built and orchestrated in GWE, drawing on a catalogue of reusable agents. For a detailed treatment of GWE, see GWE Overview. User Roles Ema defines three roles that interact with AI Employees at different levels: RoleKey ResponsibilitiesAdminProvision resources, security context, and configuration so an AI Employee can operate effectively. Admins are usually business users and subject matter experts. With Ema's framework, they are empowered to self-manage and improve their AI Employees.BuilderDesign and assemble the multi-agent workflow -- either from scratch or by customizing an AI Employee template. Not all deployments need a builder; if a pre-built AI Employee suffices, the admin can configure and launch it directly.End UserInteract with the finished AI Employee to obtain outcomes. End users cannot alter the AI Employee's configuration. They may interact with Ema via chat, analytics dashboards, or their day-to-day SaaS applications. Human-in-the-Loop Ema's agents can seek human help to disambiguate, assist, and approve their work mid-task. They may ask a question or present a partial or complete solution for approval. When Does an Agent Request Human Input? Lack of information. Agents, like human employees, are not always equipped to complete a task. They may lack resources or need clarifications. Agents can be configured to proactively seek help as needed. Risk or compliance reasons. Critical tasks where errors are unacceptable or where a human sign-off is legally required. Agents can be configured to always seek human input for these cases. Human-in-the-loop can be conversational (via chat) or structured (via dashboards). It unlocks the safe use of agentic AI across critical business flows. Key Takeaways Agents are single-purpose building blocks; AI Employees orchestrate multiple agents into complete workflows. AI Employees are built in the Generative Workflow Engine (GWE), drawing on a catalogue of reusable agents. The architecture delivers predictable, explainable, and scalable automation for complex enterprise workflows.

================================================================================
# Platform Tour
URL: https://builder.ema.ai/introduction/platform-tour
================================================================================

Platform Tour Ema's canvas is the starting point for building agentic AI applications. It provides a no-code workspace where implementation engineers can assemble multiple AI agents into a coordinated mesh, connect them to enterprise data and tools, and manage workspace-level policies -- all from a single screen. Signing In Navigate to app.ema.co. Enter your corporate email address and select Continue. Check your inbox for a one-time login link sent by Ema. Based on your organization's settings, you may be redirected through your identity provider before Ema completes authentication. After authentication, you land on Ema's canvas -- the unified workspace where you create and monitor AI Employees, configure integrations, and administer workspace settings. The persistent navigation rail on the left side of the canvas gives you one-click access to all core work areas: AI Employee creation, integrations, chat history, and workspace administration. AI Employees Page The AI Employees page lists all AI Employees currently available in the workspace. Each is presented as a card showing the AI Employee's name, role summary, running state, and quick actions. Select Use to open an interactive console where you can issue tasks against connected data sources and manage the associated AI Employee configuration. Select Create an AI Employee for a blank canvas to design a bespoke AI Employee that can be provisioned in minutes. Autopilot For a faster starting point, use the Autopilot entry point on the AI Employees page. Describe the AI Employee you want in natural language -- for example, "I need a customer support bot that answers billing questions from our knowledge base" -- and Ema generates a draft workflow you can review, refine, and publish. Autopilot is particularly useful when you are unsure which template best fits your use case or when you want to prototype quickly before committing to a manual build. Pre-Built AI Employee Templates A template catalog sits beneath the live AI Employees and provides pre-built blueprints (such as Agent Assist and Employee Assistant) for rapid deployment. You can also extend the catalog by publishing your own templates, making them immediately available to the broader workspace. Integrations No workflow is complete without external data and tools. The Integrations area lets you link the workspace to more than 200 enterprise applications -- Salesforce, ServiceNow, Google Workspace, and others. For each connector: Authenticate with the required account or service principal. Scope read and write permissions at the object or field level. Confirm activation when the connector card shows Connected. Once a connector is active, every AI Employee in the workspace can call its APIs or ingest its data according to the permissions you granted. Conversational Workspace The Chat section maintains a chronological log of your interactions with every AI Employee. Use these transcripts to: Audit decisions made by the AI Employee. Copy outputs into downstream systems. Resume unfinished requests. Conversations are private to the initiating user and can be deleted at any time. Voice Ema supports Voice AI Employees that interact with end users over phone or voice channels. Voice AI Employees use the same GWE workflow engine as other types but add voice-specific configuration: accent and speed settings, Voice Activity Detection (VAD) tuning, call routing rules, and phone number assignment for inbound and outbound calls. Voice is suitable for phone-based customer support, IVR replacement, and voice-enabled assistants. Custom Code Execution For workflows that require logic beyond pre-built agents, the Custom Code Agent allows builders to run arbitrary code within a GWE workflow. This is useful for custom data transformations, API integrations with non-standard protocols, or domain-specific calculations that are best expressed in code rather than prompt instructions. Workspace Administration The gear icon in the lower-left corner of the navigation rail appears only for workspace administrators. Opening it launches the Settings panel, where admins can: Manage the user roster. Invite new members or remove existing ones from the workspace. Set roles and permissions. Grant, restrict, or modify each user's access level across every AI Employee or the workspace as a whole. Next Steps You now have the foundational context for navigating the Ema canvas. In the following sections, you will build a production-ready AI Employee, connect it to live enterprise data, and apply governance controls that meet large-scale operational standards.

================================================================================
# What Is Ema?
URL: https://builder.ema.ai/introduction/what-is-ema
================================================================================

What Is Ema? Ema is a universal AI Employee platform built on a generative workflow engine that orchestrates a network of specialized agents, connects to more than two hundred SaaS applications and internal APIs, and autonomously observes data, decides on next-best actions, and executes tasks inside complex enterprise workflows. Designed for technically minded implementation teams, Ema translates business goals into end-to-end automations that can resolve support tickets, generate proposals, enrich records, and sync systems without human hand-offs -- all while honoring guardrails like SLAs, data redaction, and audit logging. The platform's low-code interface lets you define triggers, policies, and fallbacks in minutes, delivering rapid time-to-value and freeing teams to focus on strategic work. AI Employees An Ema AI Employee is a multi-agent mesh designed to automate complete pieces of enterprise work. AI Employees execute complex tasks from start to finish, operate independently across your organization, and continuously improve through human collaboration and feedback. Ema provides ready-to-deploy AI Employees tailored for various industries, domains, and business functions. Organizations can experience the impact of agentic AI within hours or days rather than weeks or months. Getting started is straightforward: Grant access to your enterprise knowledge sources (knowledge base documents, public URLs). Connect the applications Ema needs to gather information and execute actions. Customize behavior through natural language instructions and feedback. Behind every AI Employee is Ema's Generative Workflow Engine (GWE) -- an accessible no-code platform that empowers both technical teams and business users to customize existing AI Employees or create entirely new ones. For a deeper look at GWE, see GWE Overview. AI Employee Interfaces AI Employees can be surfaced through purpose-built agentic interfaces or embedded directly in the tools you already use. Each interface runs the same underlying AI Employee logic, so guardrails, audit logs, and learning loops stay consistent everywhere. InterfaceDescriptionChatBrowser-based conversational workspace for questions, tasks, and follow-ups. Also embeddable within Slack, Teams, and Google Chat.VoiceVoice-based interaction via phone or voice channels. Supports configurable voice characteristics, call routing, VAD settings, and phone number assignment for inbound and outbound calls.DashboardSpreadsheet-style view optimized for high-volume, repeatable workflows (e.g., triage queues or data enrichment).DocumentLive co-authoring inside a Word/Google Docs-style environment for drafting and reviewing long-form content.API IntegrationsEndpoints that let you invoke AI Employee capabilities from any enterprise system or custom application. EmaFusion EmaFusion is Ema's proprietary Mixture-of-Experts (MoE) model that serves as the technological foundation for all AI Employees. It operates by disaggregating each agent's request into granular subtasks. For each subtask, EmaFusion assesses complexity and selects the most appropriate Large Language Model (LLM) or ensemble of LLMs capable of meeting a defined accuracy SLA. Outputs from selected candidate models are integrated through confidence-weighted voting and validation. The system continuously refines its internal routing mechanism based on real-time telemetry. Key Capabilities Accuracy Enhancement. By automatically fusing the strengths of specialized LLMs, EmaFusion enhances benchmark performance -- often by double-digit percentages -- without manual adjustments. Cost and Latency Control. Per-request policies avoid costly models when unnecessary and ensure predictable, low-latency responses. Model Agility. New open-source, proprietary, or customer-hosted models can be integrated seamlessly, avoiding single-vendor lock-in. Privacy by Design. Ema automatically obfuscates sensitive data (e.g., names, emails, phone numbers) before sending to models. For technical details, see the EmaFusion research paper. AI Employees: Beyond RPA and Copilots Traditional automation tools -- RPA, BPM, and point copilots -- optimize slices of work but fail to orchestrate the complex interplay of decisions, data, and actions that define modern enterprise workflows. Limitations of Traditional Approaches ChallengeRoot CauseInflexibility and BrittlenessClassic RPA and BPM suites rely on positional clicks or rigid business rules. Any UI or process change breaks the automation.Unstructured Data Blind SpotsPDFs, emails, and chats require semantic understanding that rules-based engines lack.Extended Deployment CyclesHeavy process-mapping plus custom scripting means months before first value is realized.Poor Usability and Low AdoptionAutomation bolted onto existing systems rather than embedded in natural workflows.Low or Unclear ROIPoint solutions optimize silos, not end-to-end outcomes. How Ema Differs Ema's agentic AI approach combines advanced LLM reasoning with multi-agent orchestration to manage complex business processes end to end. CapabilityRPA (Fixed)LLM Copilot (Point)Ema (Agentic AI)End-to-end workflow automationNoNoYesHandles unstructured data (PDF, email)NoPartialYesSelf-introspection and continuous learningNoNoYesOrchestrates multiple specialized agentsNoNoYesDeployment speed and maintainabilityMonths, brittleWeeks, scriptsDays, composable Core characteristics of Ema's approach: Human-like capabilities. Autonomously plan, decide, and act across multiple applications to achieve a goal. Self-improving. Evaluate performance, incorporate feedback, and dynamically retrain processes. Composable. Discrete agents -- retrievers, validators, actors -- assemble into new AI Employees without code-heavy sprawl. Ema extends these foundational agentic AI concepts with the production-grade observability, security, and governance required for enterprise deployment.

================================================================================
# Getting Started
URL: https://builder.ema.ai/getting-started
================================================================================

Getting Started This section walks you through everything you need to go from first login to a working AI Employee. In This Section First Login -- Sign up, authenticate, and complete onboarding. Create Your First AI Employee -- End-to-end quickstart: pick a template or use Autopilot, configure a workflow, test it, and run your first conversation. AI Employee Types -- Understand the different AI Employee interfaces and when to use each one. Effective Discovery -- A framework for scoping high-impact use cases before you build. Prerequisites Before you begin, confirm the following: You have received an invitation email from your Ema workspace administrator. You have a supported browser (Chrome, Edge, Firefox, or Safari -- latest two major versions). Recommended Path Sign in -- Follow the First Login guide to access the Ema platform. Explore templates -- Browse the AI Employee templates on your dashboard to see what is available out of the box. Build something -- Walk through Create Your First AI Employee to deploy a simple RAG-based chat assistant in under 30 minutes. Understand your options -- Read AI Employee Types to pick the right interface for your next use case. Plan for production -- Use the Effective Discovery framework to scope and validate use cases before committing to a full build.

================================================================================
# AI Employee Types
URL: https://builder.ema.ai/getting-started/ai-employee-types
================================================================================

AI Employee Types Every AI Employee in Ema is powered by a GWE (Generative Workflow Engine) workflow. The workflow defines the logic. The type determines how the AI Employee interacts with end users -- its interface, input method, and output format. When you create a new AI Employee, you select a type. This choice is permanent -- it cannot be changed after creation. Available Types Chat Interface: Ema Webapp Chat at app.ema.co (or your custom domain). Best for: Internal knowledge assistants, policy Q&A, compliance lookups, general-purpose AI assistants for employees. How it works: Users interact through a conversational chat interface in the Ema web application. The AI Employee processes natural-language queries and returns text responses. Key features: "Show Work" explanations for transparency into how the response was generated. Paragraph-level source citations with page numbers. Per-response feedback collection (thumbs up/down). Full conversation history. Voice Interface: Voice-based interaction via phone or voice channel. Best for: Phone-based customer support, IVR replacement, voice-enabled assistants, outbound call campaigns. How it works: The AI Employee handles voice conversations using speech-to-text and text-to-speech processing. Configuration includes voice settings (accent, speed, language), conversation behavior, call routing, data storage preferences, and phone number assignment for inbound and outbound calls. Key features: Configurable voice characteristics (accent, speed, language). Conversation settings for behavior and tone. Call settings and routing configuration. VAD (Voice Activity Detection) settings for natural turn-taking. Phone number assignment for inbound and outbound calls. Data storage and feedback collection settings. Dashboard Interface: Structured tabular output (Agentic Dashboard). Best for: Analytical tasks over large volumes of unstructured data. Bulk document processing. Data extraction and rule validation at scale. How it works: Instead of conversational input/output, the Dashboard type processes structured inputs (rows of data or documents) and produces structured outputs in a tabular dashboard format. Each cell in the output is traceable to its source. Key features: Bulk orchestration across many inputs. Per-cell source inspection. API and CSV export. Multiple input type support. Human-in-the-loop support with confidence scores. Filtered sub-dashboard views. Document Interface: Collaborative document editor (Ema Document Editor). Best for: Long-form document generation (300+ pages), contracts, reports, policy documents. How it works: An agentic collaborative editor that supports iterative generation and regeneration of document sections. Multiple users can collaborate on the same document. Key features: Section-level collaboration. Version control and audit trail. Status management per section. Iterative regeneration. Choosing the Right Type Use CaseRecommended TypeInternal employee Q&AChatPhone-based support or IVR replacementVoiceBulk document analysisDashboardLong-form document draftingDocument API Access All AI Employee types can be invoked via API, regardless of their primary interface. This allows you to integrate any AI Employee into custom UIs or backend workflows. See API Reference for details. What Happens After You Choose Once you select a type and create the AI Employee: A GWE workflow is initialized with the appropriate trigger type (chat trigger, dashboard trigger, voice trigger, etc.). Configuration widgets specific to the type appear on the AI Employee configuration page (e.g., voice settings for Voice, SDK config for Chatbot). You can customize the workflow in the GWE canvas regardless of type -- the workflow logic is independent of the interface. For a hands-on walkthrough of building your first AI Employee, see Create Your First AI Employee.

================================================================================
# Effective Discovery
URL: https://builder.ema.ai/getting-started/effective-discovery
================================================================================

Effective Discovery Effective discovery is the foundation of any successful AI Employee deployment. Before configuring workflows and connecting data sources, invest time in understanding the problem space, validating feasibility, and aligning stakeholders. This section provides a structured framework for scoping AI Employee use cases and designing deployments that deliver measurable value. Why Discovery Matters GoalWhat Effective Discovery EnablesRisk of SkippingStakeholder AlignmentClear objectives, roles, timelines, and governance.Misaligned expectations, delays, scope creep.Data and Compliance ReadinessDefined access, security, and compliance posture early.Legal blockers, security review delays, re-scoping.Process and User FitValidates that AI is the right abstraction for the task.Low usage, unclear ROI, or unnecessary complexity.RepeatabilityEnables template-based delivery and scaled reuse.One-off custom work with minimal leverage across deployments. Discovery Phases The discovery process follows three phases. Treat these as gates -- progress only once the required inputs are documented and validated. PhasePrimary OwnerTypical TimelineKey OutputsDemo PreparationSales and Solution ArchitectPre-salesRelevant demo aligned to customer vertical. Completed use-case intake questionnaire.Proof of Concept (PoC) DiscoverySolution Architect2--4 weeksValidated use-case matrix, success metrics, PoC scope of work, and early legal/data inputs.Product LaunchPrimary Ema Builder4--6 weeksFinal deployment documentation including business logic, agent configuration, and monitoring plans. Only advance to the next phase once artifacts are complete and aligned across stakeholders. Step-by-Step Discovery Guide 1. Initial Preparation Before your first meeting, review the customer's industry, maturity, and operating model. Draft a Hypothesis Use-Case Matrix identifying 3--5 candidate workflows where AI could deliver measurable value. 2. Stakeholder Interviews Start broadly, then narrow: Exploratory questions: Where is the most manual effort? What processes are mature enough for automation? Where would success be most visible? Role-based conversations: Business: Goals, metrics, urgency, ROI. Process SMEs: Daily pain points, exceptions, user behavior. IT and Data: Data access, systems in scope, integration feasibility. Security/Legal: Deployment model preferences, compliance considerations. 3. Process Mapping Use visual artifacts to align stakeholders: Document the current workflow using a swim-lane diagram. Shadow users to observe real behavior. Identify latency points, manual steps, and high-frequency tasks. Flag automation-ready segments: structured inputs, deterministic logic, known outputs. 4. Data Readiness Evaluate early whether the use case is viable from a data perspective: Is there sufficient historical volume? Are the outcomes labeled or easy to infer? Is there a viable access path (API, export, database connection)? Can synthetic data be used to accelerate PoC progress? 5. Use-Case Scoring Use a consistent framework to compare candidate workflows: DimensionWeightDescriptionBusiness Impact3xStrategic importance, revenue or cost impact.Leverage2xNumber of users, frequency of task.AI Suitability2xClear input/output patterns; logic explainable by examples.Data Readiness1xAccessibility, quality, security review status.Risk/Criticality-1xPenalty if wrong; data sensitivity or operational disruption. Drop any use case that lacks basic AI fitness, scale, or clarity of value. Designing AI Employees After Discovery Once high-potential use cases are validated, the build follows three stages: Prototype -- Build a demo showing the full happy path using sample or synthetic data. Hardcode steps where needed to validate the concept quickly. Production Readiness -- Replace mocks with live systems, expand test coverage, introduce human-in-the-loop controls for high-risk steps, and define rollback logic. Scaling -- Generalize prompts, actions, and workflows into reusable templates. Build evaluation harnesses. Layer in observability for performance and trust. Key Deliverables by Stage StageDeliverablesPre-DiscoveryHypothesis Use-Case Matrix, Stakeholder MapDiscoveryProcess Maps, Data Inventory, Interview SummariesValidationScored Use-Case Matrix, AI Fit AssessmentDesignAI Employee Specification DocumentBuildFunctional Demo, Evaluation Framework, RunbookHandoffAdmin Toolkit, Metrics Dashboard, CI Plan Common Pitfalls Scope creep post-PoC: Lock the PoC scope in writing. Treat additions as formal change requests. Overuse of AI for deterministic tasks: Avoid deploying LLMs where a rules engine would be more efficient. Use AI suitability scoring rigorously. Security and legal involvement too late: Bring these stakeholders into discovery, not after a prototype is built. Silent failures in agent logic: Instrument every step. Provide clear error handling and feedback loops. Domain-Specific Discovery Guides For detailed discovery frameworks tailored to specific business domains, see: Hire to Retire -- Employee experience and HR lifecycle. Query to Resolution -- Customer support and service operations. Lead to Cash -- Document intelligence and sales operations.

================================================================================
# Hire to Retire Discovery Guide
URL: https://builder.ema.ai/getting-started/effective-discovery/hire-to-retire
================================================================================

Hire to Retire Discovery Guide This guide provides a structured framework for conducting discovery for AI Employees that support the employee lifecycle -- from talent acquisition through onboarding, employee support, and offboarding. Product Suite Overview Ema's Employee Experience (EX) suite consists of specialized AI Employees that support different stages of the employee journey: AI EmployeePurposeJob Description GeneratorCreates comprehensive, inclusive job descriptions using structured inputs.Market Intelligence GeneratorBenchmarks roles and salaries with real-time labor market data.Resume Ranking AssistantExtracts, scores, and ranks candidate resumes against job requirements.Leadership RecruiterAutomates executive sourcing and engagement.Onboarding AssistantGenerates offer letters and employment contracts.Employee AssistantDelivers real-time support and workflow automation for employees. Each AI Employee can be deployed independently or together, based on organizational needs and technical readiness. Discovery Preparation Required Knowledge Familiarity with HR systems (ATS, HRIS, case management, payroll). Understanding of HR lifecycle workflows and role responsibilities. Awareness of data privacy, compliance, and security expectations. Stakeholders to Involve HRIS and HR operations teams. Talent acquisition leads and recruiters. IT, Security, and Compliance. Legal, Procurement, and Policy owners. End users such as HR business partners and employee experience owners. Recommended Pre-Work Gather HR process documentation and system maps. Identify available sandbox or test environments. Clarify scope of AI Employee(s) and expected outcomes. Confirm access to sample data (e.g., resumes, job descriptions, support tickets). End-to-End Workflow Mapping Employee Lifecycle Discovery Map the complete employee lifecycle to ensure AI Employees align with real operational workflows. What to capture: End-to-end journey stages: Document each phase from hiring through onboarding, employee movement, and offboarding. Cross-system data transitions: Clarify how data flows between systems like ATS, HRIS, payroll, and benefits. Human approvals and checkpoints: Identify where decisions are made by people (e.g., offer approvals, policy exceptions). These are areas where AI can assist, not automate. Manual bottlenecks: Highlight repetitive or high-effort tasks that burden HR staff. Compliance and audit steps: Understand where validations or approvals are required by legal, policy, or union agreements. Discovery methods: Live walkthroughs with HR staff narrating recent cases. Shadowing or screen recording reviews. Stakeholder interviews across HR, IT, legal, and operations. SOP reviews cross-checked against actual practices. Functional Discovery by AI Employee Job Description Creation What to capture: Trigger events that initiate JD creation (requisition, attrition, expansion). Existing templates and storage locations. Approval and review flows. Update frequency and ownership. Compliance and DEI considerations (localization, EEOC). Resume Evaluation What to capture: Resume formats and parsing reliability. Scoring and ranking logic (skills match, experience fit). Required extraction fields (certifications, education, years of experience). Bias mitigation practices. Explainability needs for regulated environments. Executive Hiring What to capture: Leadership competency definitions. Sourcing channels (LinkedIn, referrals, search firms). Outreach personalization approaches. Assessment methods and scorecards. Market monitoring practices. Employee Support What to capture: Most common employee requests and queries. Current support channels (chat, email, portal). Manual touchpoints where HR is overloaded. Region- or policy-specific variations. Multilingual needs and UX constraints. Success Metrics AI EmployeeMetricDescriptionJob Description GeneratorTime to CreateAverage time to generate a new JD.Job Description GeneratorAccuracy RatePercentage of JDs requiring minimal edits.Resume Ranking AssistantTime to ScreenTime saved in initial resume filtering.Resume Ranking AssistantQuality ScorePercentage match between ranked and hired candidates.Leadership RecruiterTime to FillDays from search to shortlist.Leadership RecruiterEngagement RatePercentage of executives who engage with outreach.Employee AssistantQuery VolumeNumber of queries handled autonomously.Employee AssistantAccuracy Rate1 minus percentage of responses rated negatively. Pre-Launch Evaluation Checklist Golden dataset of sample queries or resumes prepared. Internal quality thresholds defined (e.g., 85% accuracy). SME validation workflows established. Test environment coverage confirmed with mock data. Baseline metrics captured for comparison. Stakeholder Roles RoleResponsibilityExecutive SponsorStrategic alignment, resource allocation.HRIS LeadTool integration and technical ownership.Talent LeadDomain input for AI evaluation and QA.Knowledge or Policy OwnerDocument access, tagging, and updates.IT or SecurityAuth setup, access control, observability.End UsersReal-world feedback and usability testing.

================================================================================
# Lead to Cash Discovery Guide
URL: https://builder.ema.ai/getting-started/effective-discovery/lead-to-cash
================================================================================

Lead to Cash Discovery Guide This guide provides a structured framework for conducting discovery for AI Employees that address friction points across document-heavy and sales workflows -- from data extraction and rule validation through document generation and outbound sales. Product Suite Overview The Lead-to-Cash suite includes document intelligence agents and AI-powered sales tools: AI EmployeePurposeData ExtractionParses structured information from documents of any format (PDFs, scans, Word files) and prepares it for downstream consumption.Rule ValidationEvaluates extracted data against customer-defined business rules or regulatory constraints to flag errors, omissions, or compliance risks.RFP WriterGenerates tailored responses to RFPs by leveraging prior submissions, product knowledge, and document structure.Document GeneratorAutomates creation of enterprise-ready documents such as contracts, memos, performance summaries, and customer-facing letters.AI-SDRAutomates outbound sales prospecting: sources leads, generates personalized messaging, and executes outreach via CRM integration. These AI Employees can be deployed independently or as a cohesive solution depending on input data complexity and pipeline maturity. Discovery Preparation Required Knowledge Document formats, intake processes, and downstream output usage. Validation rules and audit/compliance dependencies. Sales outreach stack: enrichment, sequencing, CRM integration. Document automation workflows (e.g., RFP lifecycle, doc generation templates). Stakeholders to Involve Admins managing AI configuration and user access. Business users (SDRs, proposal managers, legal analysts). Sales leaders and revenue operations. Procurement, legal, and compliance stakeholders. IT/Security responsible for integration and data governance. Recommended Pre-Work Collect sample input documents (contracts, RFPs, forms) and desired outputs. Document validation rules and doc generation templates. Audit lead sourcing tools and current sales messaging flows. Confirm target KPIs and measurable outcomes. End-to-End Workflow Mapping Document and Sales Process Discovery What to capture: Document lifecycle stages: Intake, data extraction, validation, drafting, review, and delivery. Sales engagement flow: How leads are sourced, segmented, contacted, and handed off to AEs. Template and rules management: How frequently used templates and validation rules are stored and maintained. Tool and system transitions: How data or content moves between CRM, shared drives, CMS, or via manual handoffs. Approval and review checkpoints: Which stakeholders review or approve documents and at what stage. Manual effort and bottlenecks: Areas where teams spend time on formatting, data entry, or chasing approvals. Data Extraction What to capture: Source document formats and intake channels. Target fields or tables routinely parsed, especially sections with the most errors today. Volume and variety of documents processed per day or week. Error and delay points where staff correct low-confidence outputs. Process handoffs: who receives the output, in what format. Rule Validation What to capture: Validation logic: key rules, ranges, or flags for quality or compliance. Rule sources: where rules are defined, stored, and who owns them. Failure handling: what happens when a record fails (escalation, rejection, manual fix). Review checkpoints: where humans intervene to approve or override. Recurring gaps: rules that often fail or require frequent human intervention. RFP Writer What to capture: Intake methods: how RFPs arrive and are triaged or assigned. Drafting workflows: who writes each section, whether content is reused or started fresh. Content reuse: availability of answer banks, past responses, or shared templates. Review cycles: how drafts are reviewed and by whom. Collaboration process: which teams contribute and how responses are assembled. Document Generator What to capture: Common document types produced across departments. Template logic: structure, dynamic fields, conditional content. Content sources: manual input, historical examples, system data. Approval flows by document type. Brand and tone controls: formatting, tone, or legal checks. AI-SDR What to capture: Team structure: SDR responsibilities, quotas, relationship to AEs. Prospecting process: how leads are selected, segmented, and approached. Tooling stack: CRM, enrichment, sequencing, and personalization tools. Conversion metrics: meetings booked, conversion rates, cost per lead. Efficiency blockers: time spent on research, copy-pasting, or personalizing content. Success Metrics AI EmployeeMetricDescriptionData ExtractionThroughputNumber of documents parsed daily.Data ExtractionAccuracyPercentage of correct field extractions.Rule ValidationPrecisionPercentage of rules correctly flagged.Rule ValidationCompliancePercentage of outputs compliant to policy.RFP WriterTime SavedAverage hours saved per RFP.RFP WriterDraft QualitySME rating of first draft usability.Document GeneratorCreation EfficiencyAverage time saved producing documents.Document GeneratorReview Success RatePercentage of generated content approved without edits.AI-SDRMeetings GeneratedMeetings per SDR per month.AI-SDRCost EfficiencyCost per qualified lead. Pre-Launch Evaluation Checklist Golden input/output pairs validated. Error thresholds defined for extraction and validation. Template formats and field mappings aligned. Integration feasibility assessed (CRM, storage, etc.). Pilot timeline and success metrics confirmed. Stakeholder Roles RoleResponsibilityExecutive SponsorStrategic alignment, budget ownership.Proposal OwnerOversees RFP and structured document workflows.Content Owner / Department LeadManages document categories across HR, Legal, Marketing.End UsersSDRs, proposal writers, document reviewers.Sales / Revenue OpsSales metric tracking, CRM workflows.

================================================================================
# Query to Resolution Discovery Guide
URL: https://builder.ema.ai/getting-started/effective-discovery/query-to-resolution
================================================================================

Query to Resolution Discovery Guide This guide provides a structured framework for conducting discovery for AI Employees that improve customer support operations -- from initial query through resolution, quality assurance, and insight extraction. Product Suite Overview The Query-to-Resolution suite addresses multiple stages of the customer service lifecycle: AI EmployeePurposeCustomer Support (Chatbot)Handles Tier-1 support interactions autonomously in chat environments.Agent AssistDrafts high-quality email responses and suggestions for support agents in real time.QA AutomationEvaluates support transcripts against SOPs to flag gaps and automate quality evaluations.Knowledge Base AugmentorDetects outdated knowledge articles and automates updates using ticket data.Insight FinderIdentifies trends across tickets, chat logs, and resolution notes for coaching or root cause analysis. Each AI Employee can be deployed individually or in combination depending on support maturity and infrastructure. Discovery Preparation Required Knowledge Familiarity with tools like Zendesk, Salesforce Service Cloud, Intercom, or Freshdesk. Understanding of support team structures including triage, escalation, and automation flows. Awareness of how documentation, macros, and bots are used in current support operations. Stakeholders to Involve Support Operations or Platform Admins. Team Leads or SMEs. Knowledge Managers or Documentation Owners. IT or Security Teams. End users (agents, analysts). Recommended Pre-Work Request process maps, escalation matrices, and SOPs. Collect real support tickets with transcripts if possible. Confirm initial AI Employee scope and outcomes. Ensure test or sandbox environment access. End-to-End Workflow Mapping Process Discovery Understand how the support organization handles customer inquiries from first contact to resolution. Go beyond surface-level steps to uncover decision points, manual handoffs, and exceptions. What to capture: Sequence and structure of key workflows: ticket creation, triage, assignment, resolution, escalation, and feedback. Roles and responsibilities at each step and how handoffs are managed. Sources of friction or inconsistency (SLA violations, resolution delays). Exceptions and escalation logic. Segmentation logic by product, issue type, or customer tier. Discovery methods: Live ticket walkthroughs with SMEs narrating their decision-making process. Agent shadowing via recordings or real-time observation. Process map review annotated with what actually happens. Group whiteboarding sessions to highlight edge cases. Knowledge and Content Sources Map knowledge assets that AI Employees will rely on for response generation, evaluation, or documentation updates. What to capture: Types of content used: articles, macros, SOPs, wikis, escalation paths, changelogs, historical cases. Source systems: Zendesk Guide, Notion, SharePoint, Google Docs, homegrown wikis. Update workflows and ownership. Content access, structure, tagging, and versioning. Content reliability: known contradictions, stale pages, orphaned documents. Tooling and System Integration Map all technical dependencies that influence feasibility, scope, and time to deploy. What to capture: System inventory across the support stack (ticketing, KB, chat, CRM, analytics). Intended actions: read-only vs. create/update operations. Authentication and access pathways (API tokens, OAuth, SSO). Environment separation (test/dev environments for safe prototyping). Compliance and observability requirements. Approval chain for integration access. Success Metrics AI EmployeeMetricDescriptionCustomer Support (Chatbot)AccuracyPercentage of responses not rated negative.Customer Support (Chatbot)AdoptionActive users per day or week; session completion rate.Customer Support (Chatbot)DeflectionPercentage of tickets resolved without agent intervention.Agent AssistCoveragePercentage of tickets with AI-suggested draft.Agent AssistAccuracySME-rated quality of suggestions.QA AutomationCoveragePercentage of SOP or QA criteria evaluated by AI.QA AutomationAlignmentPercentage of AI evaluations matching human QA.QA AutomationThroughputPercentage of total conversations evaluated.KB AugmentorUpdate VolumeNumber or percentage of stale docs updated.KB AugmentorEfficiencyTime saved via automated maintenance.Insight FinderInsight ScopeTopics and patterns extracted.Insight FinderAnalyst Time SavedHours saved monthly. Pre-Launch Evaluation Checklist Golden datasets of sample queries and expected responses prepared. Accuracy thresholds defined (e.g., chatbot >= 85%). SME review workflows established. Test sandbox configured. Evaluation rubric documented. Stakeholder Roles RoleResponsibilityExecutive SponsorBusiness alignment, budget approval.Platform Admin / ChampionManages console, configuration, role mapping.Support SMEProvides process insights and escalation knowledge.Knowledge OwnerOwns article updates and tagging.IT / Security LeadGoverns access, compliance, integrations.End UsersValidate usability and provide real-time feedback.

================================================================================
# Create Your First AI Employee
URL: https://builder.ema.ai/getting-started/first-ai-employee
================================================================================

Create Your First AI Employee This quickstart walks you through building a simple AI Employee from scratch using the Generative Workflow Engine (GWE). By the end, you will have a working chat-based AI Employee that answers questions from uploaded documents -- a basic RAG (Retrieval-Augmented Generation) workflow. Time estimate: 20--30 minutes. Prerequisites An Ema account with admin privileges (non-admins cannot create AI Employees). A sample document to use as a knowledge source (PDF, DOCX, TXT, or PPT). If you do not have one handy, any publicly available PDF works. Two Ways to Start You can create an AI Employee in two ways: Manual creation -- Select a template or start from a blank workflow. Follow the step-by-step guide below. Autopilot (Ask Ema) -- Describe what you need in natural language and let Ema generate a draft workflow for you. This is especially useful for quick prototyping or when you are unsure which template to use. You can always refine the generated workflow manually afterward. The rest of this guide covers the manual creation path. Step 1: Create a New AI Employee Navigate to the AI Employees page. Click Create to open the Templates screen. Browse by category or search by keyword to find a suitable template. Click + Create on a template card, or select Custom AI Employee to start from a blank workflow. Enter a name for your AI Employee (e.g., "Compliance Analyst"). Click Create. You are now taken to the GWE canvas -- the visual workflow builder. Step 2: Configure Shared Resources The GWE canvas opens to the Shared Configuration view. This is where you set up resources available to all agents in the workflow. Add Data Sources In the shared configuration panel, locate the Data Sources section. Click Add Folder to create a new data source folder. Choose one of two folder types: File upload -- Upload documents from your local machine or a connected file storage app. Web scraping -- Provide URLs for Ema to scrape. Ema follows links up to two levels deep and downloads any documents it encounters. Upload your sample document (or provide a URL). Ema currently supports these file formats: PDF, DOCX, TXT, PPT. Web scraping can take a few minutes to complete. Files uploaded from linked storage apps refresh with up to a 10-minute delay. Configure EmaFusion™ (Optional) EmaFusion is Ema's proprietary Mixture-of-Experts model configuration. The default settings work well for most use cases. You can adjust them later at the individual agent level. Step 3: Build a Simple Agentic Workflow Start with the simplest possible workflow -- a single agent that responds using an LLM. Click Save to return to the blank workflow canvas. Open the Agent Library and navigate to Frequently Used Agents. Select Respond to a Query and drag it onto the canvas. Click the Query input on the Respond to a Query agent. From the dropdown, connect it to the User Query output from the workflow trigger. At this point, you have a working (but basic) workflow: user asks a question, the LLM generates a response. However, it has no access to your documents yet. Step 4: Add Document Search (RAG) To ground the AI Employee's responses in your uploaded documents: From the Agent Library, add a File Search agent to the canvas. Connect the File Search agent's Query input to the User Query from the trigger. In the File Search agent's configuration panel (right side), assign the data source folders you created in Step 2. Remove the Respond to a Query agent (it was a placeholder). Add a new Respond to a Query agent. Connect its Query input to the User Query from the trigger. Connect its Search Results input to the Results output of the File Search agent. Your workflow now follows the standard RAG pattern: User Query --> File Search --> Respond to a Query --> Output Step 5: Configure Agent Instructions Click on the Respond to a Query agent to open its configuration panel. In the Instructions field, add any specific directives. For example: "Respond in a professional tone." "Include source citations in your responses." "Use bullet points for lists." These instructions guide how the LLM agent processes the search results and formats its response. Step 6: Set the Workflow Output Click on the Respond to a Query agent's output. Select Publish as Workflow Output. Only certain output types can be published as workflow output. Raw search results cannot be published directly -- they must pass through an LLM agent first. Step 7: Save and Publish Click Save in the toolbar. Click Publish to make the workflow active. Step 8: Enable the AI Employee Navigate back to the AI Employee configuration page (click Go to AI Employee Config). Toggle the Enable switch to turn on the AI Employee. Step 9: Test Your AI Employee Open the chat interface for your AI Employee. Ask a question related to your uploaded document. For example: "What is a DPO?" The AI Employee will: Search through your connected documents. Generate a response grounded in the search results. Include source citations (page numbers and paragraphs). Click Show Work to review the step-by-step execution trace, including which documents were searched and how the response was assembled. What to Do Next You now have a working AI Employee with a basic RAG workflow. From here, you can: Add intent classification to branch your workflow based on query type. See the Conditionals section for branching patterns. Connect external applications to give your AI Employee access to live data from tools like Salesforce, Zendesk, or SharePoint. Configure permissions to control which users can interact with or modify this AI Employee. Set up evaluation to measure response quality and track accuracy over time. Review version history to track workflow changes over time and restore earlier configurations if needed. For a deeper understanding of the different AI Employee types and when to use each one, see AI Employee Types.

================================================================================
# First Login
URL: https://builder.ema.ai/getting-started/first-login
================================================================================

First Login This guide walks you through signing up and logging in to the Ema platform for the first time. Authentication Methods Ema supports several authentication methods. The method available to you depends on how your workspace administrator configured the domain. MethodDescriptionSSO (Single Sign-On)Your organization's identity provider (e.g., Okta, Azure AD) handles authentication. Ema redirects you to your IdP login page.Email + Magic LinkEma sends a one-time login link to your email. Click the link to authenticate -- no password required.Email + OTPEma sends a 6-character one-time passcode to your email. Enter it on the verification screen.Google OAuthSign in with your Google account. Available unless your workspace administrator has disabled Google login.Microsoft Azure ADSign in via Microsoft's identity platform. Requires your organization to register Ema as an Azure AD application. Your workspace administrator determines which methods are enabled. If you are unsure which method to use, enter your email on the login page -- Ema will route you to the correct flow automatically. Step-by-Step: First Login 1. Navigate to the Login Page Open your browser and go to your Ema instance URL. This is typically one of: https://app.ema.co (production) A custom domain provided by your organization (e.g., https://yourcompany.ema.co) You will see the "Let's get started" page with an email input field. 2. Enter Your Email Type the email address your administrator invited you with and click Continue. Ema checks your email against the workspace configuration and determines the appropriate login method: SSO domains -- You are redirected to your organization's identity provider. OTP-enabled domains -- A 6-character one-time passcode is sent to your email. Magic-link domains -- A temporary login link is sent to your email. 3. Complete Verification If you are redirected to SSO: Authenticate with your identity provider as usual. You are redirected back to Ema automatically. If you received an OTP: Check your email for a message from Ema containing a 6-character code. Enter the code on the verification screen. Click Verify OTP. If you do not receive the OTP within a few minutes, click Request new OTP. There is a cooldown period between requests (typically 60 seconds). After too many failed attempts, your account may be temporarily locked for security. If you received a magic link: Check your email for a message from Ema. Click the login link in the email. You are authenticated and redirected to the platform. 4. Sign in with Google (Alternative) If your workspace has Google login enabled, you can skip the email entry and click Continue with Google directly. This opens the standard Google OAuth consent screen. 5. Sign in with Microsoft Azure AD For organizations using Microsoft Azure AD, the SSO flow redirects you to Microsoft's login page. Authenticate with your Microsoft credentials and you are redirected back to Ema. Azure AD integration requires that your IT administrator has registered Ema as an application in your Azure AD tenant. Contact your IT team if you see an "access denied" error. Onboarding Flow (First-Time Users) After your first successful authentication, Ema walks you through a brief onboarding sequence: What's your name -- Enter your first and last name. This is used to identify you in conversations and audit logs. Welcome -- A landing page that introduces the platform and directs you to the AI Employees dashboard. After completing onboarding, you land on the AI Employees page, where you can see any AI Employees shared with you and -- if you are an admin -- create new ones. Returning Users On subsequent visits, Ema remembers your authentication method. Enter your email and you are routed to the same login flow. Sessions persist via token-based authentication; you remain logged in until the token expires (approximately 24 hours). Troubleshooting ProblemResolution"Email not found" errorYour email has not been added to the workspace. Ask your administrator to invite you via Workspace Settings > Users.OTP not arrivingCheck your spam folder. If still missing, wait for the cooldown timer and request a new OTP."Access denied" after SSOYour identity provider may not have granted access to the Ema application. Contact your IT team."Passwordless login is disabled"Your domain is configured for a different login method. Try SSO or contact your administrator.Account locked after too many OTP attemptsWait for the lock period to expire (typically 15 minutes), then request a new OTP.

================================================================================
# Core Concepts
URL: https://builder.ema.ai/core-concepts
================================================================================

Core Concepts This section covers the foundational concepts of the Ema Builder Platform. Understanding these concepts is essential before building or customizing AI Employees. Platform Fundamentals AI Employees -- What AI Employees are, their lifecycle, interface types, and how they differ from traditional automation. AI Employee Groups -- Organizing AI Employees into groups for easier navigation and management. Workspaces and Tenants -- Multi-tenant architecture, workspace isolation, partner-customer hierarchy, and tenant management models. Projects -- Project-based workflows for campaign, recruitment, document generation, and other multi-step processes. Frontier Apps -- Deploying custom web applications that connect to AI Employees via the Ema platform. Generative Workflow Engine (GWE) GWE Overview -- What the Generative Workflow Engine is, the visual canvas, code view, and how workflows execute as DAGs. Workflows and Actions -- Workflow structure, action types, the DAG execution model, and how actions compose. Named Inputs and Outputs -- The preferred data-passing protocol for flexible, multi-output workflows. Conditionals -- Boolean trigger-when expressions, skip propagation, optional agents, and branching patterns. Type System: Well-known types, array types, and enumerations. Workflow Validation -- Static validation, path enumeration, and ensuring all paths produce required outputs. Workflow Version History -- Tracking changes to workflow definitions over time and reverting to previous versions. For internal implementation details (Temporal orchestration, gRPC contracts, data models, and protocol internals), see the internal core concepts supplement.

================================================================================
# AI Employee Groups
URL: https://builder.ema.ai/core-concepts/ai-employee-groups
================================================================================

AI Employee Groups AI Employee Groups let you organize AI Employees into logical collections on the AI Employees dashboard. Groups are organizational labels that improve browsing and management -- they do not affect permissions or workflow execution. Key Rules An AI Employee can belong to one group or be ungrouped. Only one level of grouping is supported. You only see groups that contain at least one AI Employee you have access to. Group names must be unique within a tenant. Creating a Group Click New Group near the group chips at the top of the dashboard. Step 1 -- Details: Enter a group name (required) and optional description. Submit to create. Step 2 -- Move Employees (optional): Search and multi-select AI Employees to add to the group, then click Move. You can also skip this step to create an empty group. Editing and Deleting Groups Edit group details: Update the group name or description from the group action menu. Delete group: Remove the group (confirmation required). When a group is deleted, its AI Employees return to the tenant's default ungrouped area. Both actions are available from the group action menu that appears alongside each group section. Card-Level Actions Each AI Employee card (revealed on hover) provides the following actions: ActionDescriptionOpenView the AI EmployeeConfigureOpen the AI Employee configuration pageRenameChange the AI Employee's display nameDeleteRemove the AI Employee (with confirmation dialog)Move to groupChoose a target group from a submenu. The current group is hidden from the target list. Includes a + New Group option that pre-selects the AI Employee in the create flow.Remove from groupSend the AI Employee back to the ungrouped area. Hidden if the AI Employee is already ungrouped. Group Navigation Horizontally scrollable group chips appear at the top of the AI Employees page. Each chip shows the group name and a dynamic count of AI Employees. A + affordance lets you create a new group directly from the chip bar. Click a chip to filter the dashboard to that group's AI Employees. Roles and Access ActionRequired RoleCreate groupsTenant Admin, Manager, or BuilderCreate AI Employees inside a groupTenant Admin or BuilderMove existing AI Employees into a groupAdmin or Manager access on the AI EmployeeView groupsAccess to at least one AI Employee in the group Group permissions are intentionally lenient in the current model. Treat groups as organizational labels for easier browsing, not as security boundaries. Guest users without create rights will not see groups they have no AI Employee access to. Next: Workspaces and Tenants

================================================================================
# AI Employees
URL: https://builder.ema.ai/core-concepts/ai-employees
================================================================================

AI Employees An Ema AI Employee is an agentic AI mesh designed to automate complex enterprise tasks end-to-end. AI Employees work independently across your organization, connect to over 200 SaaS applications and internal APIs, and continuously improve through human collaboration and feedback. Unlike traditional RPA bots or copilots, AI Employees can understand context, formulate plans, request clarification, and leverage feedback loops to improve over time. Every AI Employee is powered by the Generative Workflow Engine (GWE) and EmaFusion™, Ema's proprietary Mixture-of-Experts model. AI Employee Lifecycle An AI Employee follows a four-stage lifecycle: 1. Create Start from a pre-built template or create a custom AI Employee from scratch. Templates are available for common domains (Customer Experience, Sales, HR, Healthcare, BFSI, and more). Each template includes a GWE workflow that can be further customized. To create an AI Employee: Navigate to the AI Employees page. Click Create to open the Templates screen. Browse by category or search by keyword. Click + Create on a template card, or select Custom AI Employee to start from a blank workflow. Only users with the Admin or Builder tenant role can create AI Employees. See Workspaces and Tenants for role details. 2. Configure After creation, configure the AI Employee: Workflow: Open the Workflow Builder to define or customize the GWE workflow -- the sequence of agents, data flows, and branching logic. Shared Configuration: Add resources used by multiple agents, such as connected applications, data sources, and default EmaFusion settings. AI Employee Outputs: Define the named outputs this AI Employee produces (see Named Inputs and Outputs). Integrations: Connect to enterprise applications for data retrieval and action execution. 3. Deploy Once configured, the AI Employee is available to end users through one or more interaction interfaces. Deploy by saving and publishing the workflow. AI Employees can also be shared to child tenants via template sharing. 4. Monitor After deployment, monitor AI Employee performance through: Audit logs: Review configuration changes, workflow publishes, and user access events for the AI Employee. Audit logs are queryable per-AI-Employee and per-tenant. Metrics: Track usage, accuracy, and response times. Feedback loops: Collect per-response feedback from end users to drive continuous improvement. Version history: Review and compare previous workflow versions. See Workflow Version History. Interaction Interfaces AI Employees can be surfaced through purpose-built interfaces or embedded directly in existing tools. Each interface runs the same underlying workflow, so guardrails, audit logs, and learning loops remain consistent everywhere. InterfaceDescriptionWeb-app ChatBrowser-based conversational workspace at app.ema.co (or customer-specific domains). Supports "Show Work" explanations, paragraph-level source citations, and per-response feedback.Ema ChatEmbeddable conversational interface for Slack, Teams, Google Chat, and website embedding.VoiceReal-time voice interaction via telephony or browser-based calling. Supports configurable voice settings, conversation parameters, call handling, data storage, VAD (Voice Activity Detection), and feedback collection.Agentic DashboardSpreadsheet-style view for high-volume, repeatable workflows (triage queues, data enrichment). Supports structured outputs, API/CSV export, and per-cell source inspection.Document EditorCollaborative editor for long-form documents (300+ pages) with iterative regeneration, section-level collaboration, version control, and status management.Application IntegrationsIntegration with existing systems such as ticketing and case management platforms.APIEndpoints for invoking AI Employee capabilities from any enterprise system or custom application. The interface is selected at creation time and cannot be changed afterward. Template Categories Ema provides ready-to-deploy templates organized by industry and function: BFSI -- Banking, financial services, and insurance automation Customer Experience -- Support ticket resolution, FAQ handling, escalation Employee Experience -- HR tasks, onboarding, internal helpdesk General -- Knowledge base Q&A, document summarization, data enrichment Healthcare -- Clinical documentation, patient communication Sales Experience -- Lead enrichment, SDR outreach, proposal generation Each template card shows the template name, a short description, and a + Create button. After clicking Create, the subsequent configuration steps are the same regardless of the template chosen. EmaFusion EmaFusion is the proprietary Mixture-of-Experts model that underpins all AI Employees. For each subtask, EmaFusion: Assesses complexity and selects the most appropriate LLM from 40+ models across 9+ providers. Falls back to the next-best model if the initial response does not meet a confidence threshold. Continuously refines its routing based on real-time telemetry. Key capabilities: Accuracy enhancement -- Routes each subtask to the best-suited model, often exceeding single-model benchmarks by double-digit percentages. Cost and latency control -- Enforces per-request policies to minimize unnecessary use of expensive models. Model agility -- Supports seamless integration of new open-source, proprietary, or customer-hosted models. AI Employees vs. Traditional Automation CapabilityRPALLM CopilotAI Employee (Ema)End-to-end workflow automationNoNoYesHandles unstructured data (PDF, email)NoPartialYesSelf-introspection and continuous learningNoNoYesOrchestrates multiple specialized agentsNoNoYesDeployment speedMonths, brittleWeeks, scriptsDays, composable Next: AI Employee Groups | GWE Overview

================================================================================
# Conditionals
URL: https://builder.ema.ai/core-concepts/conditionals
================================================================================

Conditionals Many workflows include branches where the execution path depends on runtime results. GWE supports this through trigger-when conditions, boolean expressions evaluated at runtime that determine whether an agent executes or is skipped. Trigger-When Conditions A trigger-when condition is a boolean expression attached to an agent instance. It can only reference values that are enumerations: Outputs of previous agent instances that are enumerations. Workflow inputs that are enumerations. If the condition evaluates to true, the agent executes normally. If false, the agent is skipped. Example: Classification Branch Trigger --> CLASSIFY --> [trigger-when Class1] B --> C --> D \-> [trigger-when Class2] E --> F If CLASSIFY produces Class1, then B, C, and D run while E and F are skipped. If it produces Class2, then E and F run while B, C, and D are skipped. Skip Propagation When an agent is skipped, any downstream agent that depends on its output is also skipped, or all of its inputs from the skipped agent are optional. This allows a single branch point to control long chains without redundant configuration. Precedence Rules The engine evaluates skip logic in the following order of precedence for each agent instance: Explicit trigger-when false: If the agent has a trigger-when condition that evaluates to false, it is skipped. Missing required inputs: If any of the agent's required inputs come from agents that were skipped, the agent is also skipped. All inputs skipped: If all of the agent's inputs come from skipped agents and all are optional, the agent still runs. The exception is when the inputs are part of a Named Inputs group that is marked as required. See below. Conditionals with Multi-Bindings When an array input is bound to multiple upstream agents via a multi-binding, the conditional rules are: Each element of a multi-binding is always optional. If an upstream agent was skipped, that element is removed from the array. If all elements were skipped, the entire multi-binding is treated as skipped and the agent does not run. The exception is when the multi-binding input is marked optional on the agent. In that case, the agent still runs with an empty array. Example: Reducer Pattern Trigger --> CLASSIFY --> [trigger-when Class1] B --> C --\ +--> [multi] D \-> [trigger-when Class2] X --> Y --/ D receives outputs from both C and Y as elements of an array. If CLASSIFY produces Class1, then C runs and Y is skipped. D receives an array with one element (from C). If neither branch runs, D's required multi-binding has zero elements, and D is skipped. Conditionals with Named Inputs Named Inputs groups interact with conditionals as follows: Each named binding can be independently marked as optional by the workflow builder. If all named bindings in a group are optional and none have values at runtime: If the Named Inputs group is optional per the agent definition, the agent can run without them. If the Named Inputs group is required, the agent cannot run (at least one element must be present). A named binding marked as non-optional within an optional group is still considered required. Example: Named Inputs with Branches Trigger --> CLASSIFY --> [trigger-when Class1] B --> C ---->[opt named] D --> E --> F \-> [trigger-when Class2] X --> Y --->[opt named]-^ If the Named Inputs group on D is required, D runs only when at least one of C or Y produces a value. If neither branch provides a value, D is skipped. Optional Agents Pattern When an agent has all optional inputs, it runs even if all upstream agents were skipped. This can be useful in some cases but surprising in others. Consider: Trigger --> CLASSIFY --> [trigger-when Class1] B --> C ----->[opt] D --> E --> F \-> [trigger-when Class2] X --> Y ----->[opt]-^ \-> [trigger-when Class3] S --> T ----->[opt]----> Output If CLASSIFY produces Class3, then S and T run, but none of B/C or X/Y do. If D has all optional inputs, it would run with no input data, which may not be the intended behavior. Solutions: Use a required multi-binding instead of separate optional inputs. With zero elements, D will not run. Use a required Named Inputs group with individually optional named bindings. At least one element must be present. Add an explicit trigger-when condition to D. Note that trigger-when currently supports only simple conditions (not OR expressions). Current Limitations Trigger-when conditions currently support only simple boolean expressions. Compound conditions (e.g., "trigger when Class1 OR Class2") are not directly supported. Use multi-bindings or Named Inputs groups as workarounds. Next: Type System

================================================================================
# Frontier Apps
URL: https://builder.ema.ai/core-concepts/frontier-apps
================================================================================

Frontier Apps Frontier Apps are custom web applications that run on the Ema platform and connect to AI Employees. They extend the platform's capabilities beyond the built-in interaction interfaces (chat, dashboard, document editor) by allowing deployment of purpose-built applications. What Frontier Apps Are A Frontier App is a containerized web application deployed and managed through the Ema platform. Each app: Is provisioned from a catalog entry that defines its image, configuration parameters, and resource requirements. Connects to one or more AI Employees via named slots (AI Employee (AIE) bindings). Runs on Ema-managed infrastructure with a dedicated subdomain and URL. Optionally receives a provisioned database. AIE Interaction Patterns Every Frontier App is built on top of AI Employees (AIEs). There are three integration patterns, each suited to a different use case: PatternDescriptionBest ForDashboard AIEStructured input/output. Submit data, AI processes it, get structured results back.Document parsing, data extraction, classification, report generation.Chat AIEConversational. Send messages, receive replies in a back-and-forth exchange.Q&A bots, assistants, interactive workflows.Docgen AIEDocument generation. Provide inputs and receive generated documents.Report generation, templated document creation. The template includes pre-built API routes, React Query hooks, and MongoDB models for both the Dashboard and Chat patterns. You configure your AIEs and build the UI -- the plumbing is handled for you. App Catalog The catalog is a registry of available app templates. Each catalog entry specifies: FieldDescriptionName and slugHuman-readable name and URL-safe identifier.DescriptionWhat the app does.CategoryOrganizational category (e.g., analytics, customer-facing).VisibilityPUBLIC (available to all tenants) or RESTRICTED (limited access).Configurable parametersNamed parameters the deployer can set (e.g., API keys, feature flags). Each has a name, type (string, number, boolean), required flag, default value, and description.Required AIE slotsNamed slots that must be bound to AI Employees. Each slot specifies an expected interaction type (e.g., PERSONA_INTERACTION_TYPE_DASHBOARD) and optional input/output schemas.Resource specCPU and memory requirements.Health check pathEndpoint the platform uses to verify the app is running. App Lifecycle A deployed Frontier App transitions through the following states: DEPLOYING --> RUNNING --> STOPPED --> DELETED | ^ | | v (start) FAILED StateDescriptionDEPLOYINGThe app is being built and provisioned. See deploy stages below.RUNNINGThe app is live and accessible at its URL.ACTIVE Alias for RUNNING in some contexts.STOPPEDThe app has been manually stopped. Can be restarted.FAILEDDeployment or runtime error. Check logs for details.DEGRADEDThe app is running but experiencing issues (e.g., partial failures or reduced performance).DELETEDThe app has been permanently removed. Deploy Stages During the DEPLOYING state, the app progresses through internal stages: BUILDING -- Container image is being built or pulled. PROVISIONING_DB -- Database is being created (if required). INSTALLING -- App is being deployed to the cluster. AWAITING_IP -- Waiting for an external IP assignment. CHECKING_HEALTH -- Verifying the app responds on its health check endpoint. Platform-Injected Configuration At deploy time, the platform automatically creates a ConfigMap with the following environment variables: VariableSourceExampleAUTH_JWKS_URLPlatform's JWKS endpointhttp://frontier-apps.frontier-apps-platform:8000/jwksAUTH_ISSUERFrom Helm valuesdev.ema.coNEXT_PUBLIC_AI_EMPLOYEE_API_URLFrom Helm valueshttps://api.dev.ema.coMONGODB_URIProvisioned by deployermongodb://myapp_user:...@10.10.0.12:27017/frontier_myappAIE_*_PERSONA_IDFrom tenant's AIE bindingsAIE_RESUME_PARSER_PERSONA_ID=424a03bc-... Deploying a Frontier App Navigate to the Apps page from the main navigation. Browse the catalog or search for an app by name. Click Deploy (or the equivalent action) on a catalog entry. In the deploy modal, configure: Parameter values: Fill in any configurable parameters defined by the catalog entry. AIE bindings: For each required AIE slot, select an AI Employee from your tenant. The slot's interaction type determines which AI Employees are eligible. Submit to start deployment. The app enters DEPLOYING state. Post-Deployment After all deploy stages complete, the app is live at https://<slug>.apps.dev.ema.co. Updating a Deployed App To update an already-deployed app: Push new code to main -- GitHub Actions builds a new container image automatically. In the platform UI, the app can be redeployed with the new image tag. AIE bindings and configurable parameters can be changed via the platform UI's Update flow, which triggers a redeployment. Managing Deployed Apps The My Apps tab on the Apps page shows all apps deployed in your tenant. Available operations: OperationDescriptionStopPause a running app. The app becomes STOPPED and is no longer accessible.StartResume a stopped app.DeletePermanently remove the app and its resources. Each deployed app shows: App name and description (from the catalog entry). Current status. App URL (accessible when status is RUNNING). Deployed image tag and deployment timestamp. AIE Bindings AIE bindings connect a Frontier App to one or more AI Employees. Each binding maps a named slot in the app to a specific AI Employee (persona). { "slot_name": "primary_assistant", "persona_id": "abc-123-def" } The slot definition in the catalog entry can specify: Interaction type: The expected interface type (e.g., dashboard, chat). Input schema: The data structure the app sends to the AI Employee. Output schema: The data structure the app expects back. How Slots Work at Runtime When a tenant deploys your app and binds a persona to a slot, the platform injects the persona ID as an environment variable into the app's ConfigMap. For example, if the slot is named AIE_RESUME_PARSER_PERSONA_ID, the platform sets: AIE_RESUME_PARSER_PERSONA_ID=424a03bc-fc5d-4a71-8acf-36d1f9ba7344 Your app reads this env var automatically -- no code changes are needed per tenant. Technical Details Each app gets a unique subdomain and app URL within the Ema platform. Apps are deployed as containers with configurable CPU and memory resources. The platform manages health checking via the configured health check path and port. Database provisioning is automatic for catalog entries that require it. The database name is tracked per deployment. Architecture Each Frontier App is an isolated Next.js application with its own MongoDB database, deployed to a shared Kubernetes namespace. The app communicates with two backends: Browser (React) | | fetch('/api/...') <- same-origin, your app's API v Your App's API Routes (/api/*) | - Authentication via JWT | - MongoDB read/write | - Business logic | | AIE SDK calls (server-side only) v Ema Core API - AI Employee processing BackendURLUsed ByThis app's API/api/* (same origin)Client components, React Query hooksEma Core APIVia NEXT_PUBLIC_AI_EMPLOYEE_API_URLServer-side AIE SDK only Important: Client components must never call the Ema Core API directly. All AIE communication goes through your app's API routes, which handle authentication, caching, and the AIE SDK calls. Key Design Principles PrincipleHow It's AchievedDatabase IsolationEach app gets its own MongoDB database on the shared cluster.Shared AuthJWT tokens from ema-app SSO, verified via JWKS endpoint.Self-ServiceFork the starter template; GitHub Actions handle provisioning and deployment.Consistent UXEma Design System provides a shared component library. Previous: Projects | Back to: Core Concepts Index

================================================================================
# Generative Workflow Engine (GWE) Overview
URL: https://builder.ema.ai/core-concepts/gwe-overview
================================================================================

Generative Workflow Engine (GWE) Overview The Generative Workflow Engine (GWE) is the orchestration layer that powers every AI Employee in Ema. GWE is best understood as an interpreter for a limited programming language: it executes a program (workflow) by running a series of function calls (actions) in sequence, mediating data flow between them as defined by the workflow configuration. Each AI Employee runs on an adaptive, multi-agent workflow built with GWE. The engine is responsible for: Parsing and validating workflow definitions. Executing workflows by orchestrating actions in topological (DAG) order. Mediating data between actions via typed bindings and ports. Storing results for downstream consumption and audit. Tracking version history so that workflow changes can be reviewed, compared, and reverted. Visual Canvas The Workflow Builder provides a visual canvas for designing and inspecting workflows. To access the Workflow Builder: Navigate to the AI Employees page and select an AI Employee. On the configuration page, click Go to Workflow Builder. The canvas displays: Trigger block: The entry point that activates the workflow (e.g., a chat message, an email, a document upload, a dashboard row). Agent blocks: Nodes representing individual actions in the workflow. Each block shows the agent's name, description, and input/output connections. Connecting lines: Edges that illustrate data flow -- how outputs from one agent become inputs for the next. Interacting with the Canvas Drag blocks to rearrange the layout. Zoom in and out for better visibility. Click an agent block to open its configuration panel, where you can: View and edit the agent's name, description, inputs, and outputs. Rename or remove the agent. Access advanced settings (e.g., EmaFusion model selection). Shared Configuration A shared configuration section lets you add resources used by multiple agents: Connected applications and data sources. Default EmaFusion settings (can be overridden at the agent level). Code View The Code tab provides a read-only, code-based representation of the workflow for deeper inspection. This view shows the raw workflow definition, which is useful for: Debugging complex data flows. Understanding the exact binding and conditional configuration. Comparing workflow versions. Issues Tab The Issues tab lists any errors or misconfigurations detected within the workflow. Common issues include: Missing required bindings. Type mismatches between connected ports. Unreachable actions due to conditional logic. Required outputs that are not produced on all execution paths. See Workflow Validation for details on the static validation system. How Workflows Execute Under the hood, GWE compiles a workflow definition into a directed acyclic graph (DAG): Each node in the graph is an action instance -- a call to a specific agent with bound inputs. Each edge is a binding -- a connection that carries data from one action's output to another's input. The engine executes actions in topological order, ensuring that every action's inputs are available before it runs. At each step, the engine assembles input data from upstream outputs, invokes the action provider (typically via RPC), and stores the output for downstream consumers. The actual data values (the user's query, a search result, an API response) are not known until runtime. The workflow definition specifies the structure of data flow; runtime execution fills in the values. Trigger --> Action A --> Action B --> Action C --> Output \ ^ \--> Action D ----------/ In this example, Action C depends on both Action B and Action D. The engine runs A first, then B and D in parallel (since neither depends on the other), and finally C once both B and D have completed. For detailed coverage of how actions, bindings, and conditionals work, see: Workflows and Actions Conditionals Access Requirements ActionRequired RoleView the Workflow BuilderAdmin or Manager on the AI EmployeeEdit the workflowAdmin on the AI EmployeeCreate new AI EmployeesAdmin or Builder at the tenant level Users without admin or manager access can use the AI Employee but cannot view or modify its workflow. Next: Workflows and Actions

================================================================================
# Named Inputs and Outputs
URL: https://builder.ema.ai/core-concepts/named-inputs-outputs
================================================================================

Named Inputs and Outputs Named Inputs and Named Outputs are the preferred data-passing protocols in GWE. They provide structured, labeled channels for data to flow into and out of agents and workflows. Named Outputs (AI Employee Outputs) Named Outputs define the structured results that an AI Employee produces. You configure them at the workflow level and bind specific agent outputs to labeled output slots. How Named Outputs Work In the AI Employee Outputs panel (visible in the Workflow Builder), each output has: Output name: A natural language label for the output (e.g., Ticket Response, Category, Abstain Reason). Description: What this output represents. Output type: The data format (String, Boolean, etc.). Output requirement: Whether it is Required or Optional. Append if multiple outputs: Whether to combine multiple values into an array when more than one agent produces this output. Published vs. Eligible Each output shows two status indicators: Published: How many agents are currently selected to produce this output. Eligible: How many agents in the workflow can produce this output. Connecting Outputs To connect an agent to produce a named output: Find the output in the AI Employee Outputs panel. Click on an eligible agent. Use the Publish button to select that agent as a producer. Example: Agent Assist AI Employee The Agent Assist template includes predefined outputs: OutputDescriptionTicket ResponseThe main response to the user's queryAbstain ReasonExplanation when the AI chooses not to respondL1 CategoryTop-level categorizationL2 CategorySecond-level categorizationL3 CategoryThird-level categorizationPublic ResponseWhether to post publicly or as a private note Outputs marked as required must be connected to at least one agent. The system validates that all required outputs are produced on every execution path. See Workflow Validation. Named Inputs Named Inputs let agents receive multiple, labeled inputs from other agents or sources in the workflow. They consolidate supplementary information beyond the primary query into a structured, key-value format. Use Cases Named Inputs serve two primary purposes: Flexible primary inputs: Generic agents that accept different types of inputs in the same slot. For example, the Categorizer agent accepts texts, search results, or documents through its named inputs. In such cases, at least one input field is typically required. Supplementary context: Additional information beyond the primary query, such as external tool results, search data, or outputs from previous steps, all consolidated in one place. For example, the "Additional Context" section in the Respond to a Query agent. These are often optional. Supported Types Integers / Floats Booleans Strings Dictionaries (JSON) Text with sources (citations) Documents Chat conversations Extraction outputs Rulesets Search results Adding Named Input Fields Identify an agent that supports named inputs. Click the + Input Field button on the agent's configuration panel. Configure the field: Name: A label for this input (used in instructions). Description (optional): What this input represents. Optional: Toggle to make the field non-mandatory. List: Toggle to accept multiple connections to this field. Connect other agent outputs to the field. If List is enabled, you can connect multiple sources. Optionally reference named input fields by name in the agent's Instructions field to guide how the LLM uses them. If named inputs are mandatory for an agent (e.g., the Categorizer agent where they are primary inputs), you will see a validation error until at least one input field is added and connected. Named Input Rules with Conditionals Named inputs interact with the conditional system as follows: Each named binding can be independently marked as optional by the workflow builder. If a single named binding is optional and has no value at runtime, it is ignored. If all named bindings in a group are optional and none have values: If the Named Inputs group itself is optional (per the agent definition), all can be ignored. Otherwise, the agent is missing a required input and cannot run. If a Named Inputs group is optional as a whole but contains a non-optional named binding, that binding is still considered required. See Conditionals for the full skip-propagation rules. Next: Conditionals

================================================================================
# Projects
URL: https://builder.ema.ai/core-concepts/projects
================================================================================

Projects Note: Projects are not available for all AI Employees and cannot be added by a builder at this time. Projects are multi-step, goal-oriented workflows that extend beyond single-query interactions. While a standard AI Employee processes individual requests, a Project manages an end-to-end process with multiple stages, configuration, and status tracking. What Projects Are A Project is a stateful unit of work associated with an AI Employee. It has: A project type that determines its structure and available stages. A configuration (proto config) that stores project-specific settings. A state that tracks progress through the project lifecycle. A status log that records state transitions and events. Projects are accessed from the AI Employees page under the associated AI Employee. Project Types The platform supports the following project types: Project TypeDescriptionSDR (Sales Development)Sales outreach campaigns with prospect research, messaging, and follow-up.Executive RecruiterRecruitment workflows with candidate sourcing, screening, and outreach.RFPRequest for Proposal response generation with template management and section drafting.Chatbot Chatbot-based project workflow.Rule Validation Compliance or rule-checking project workflow.PPT GeneratorPresentation generation projects.Generalized Document WriterGeneral-purpose document creation projects.Workflow-Based Document GeneratorDocument generation driven by GWE workflows.Proposal WriterProposal drafting and generation projects. Sub-Project Types Some project types support sub-projects for more specific use cases: Custom Document -- Free-form document creation. Advanced RFP -- Complex RFP responses with multi-section management. Blog -- Blog post generation. Simple RFP -- Streamlined RFP response. Meeting Summary -- Meeting notes and action item generation. Sales Intelligence Report -- Account research and competitive intelligence. Project Lifecycle Projects progress through the following states: StateDescriptiondraftProject created but not yet started. Configuration is being set up.activeProject workflow is running or ready for interaction.completedProject has finished successfully.failedProject workflow encountered an error.cancelledProject was manually cancelled.inactiveProject is paused or deactivated. Creating and Running Projects Navigate to an AI Employee that supports projects. Create a new project from the AI Employee's interface. Configure project-specific settings through the step-by-step UI. Trigger the project workflow. The project transitions from draft to active. Monitor progress and interact with results as the workflow executes. The exact entry point for creating projects may vary by AI Employee template and interaction type. Updating Projects Projects support configuration updates after creation. The update flow reuses the same step-by-step interface but in update mode, allowing you to modify settings and re-trigger the workflow. Next: Frontier Apps

================================================================================
# Type System
URL: https://builder.ema.ai/core-concepts/type-system
================================================================================

Type System Every port (input or output) in a GWE workflow has a type. The engine enforces type-checking at configuration time, ensuring that data passed between agents matches the expected format. This prevents runtime errors and provides intellisense-like support in the Workflow Builder. Well-Known Types GWE provides a set of built-in types that have special support across the platform and SDKs. Primitive Types TypeDescriptionExampleSTRINGText values"Hello, world"FLOATFloating-point numbers0.95Integer (proto: INT)Whole numbers42Boolean (proto: BOOL)True or falsetrueStruct (proto: STRUCT)Structured key-value data{"key": "value"} Framework Types These types represent common data structures used across Ema's agent ecosystem. They receive special treatment in the engine and SDKs, including automatic formatting for LLM consumption. TypeDescriptionDocumentDocument content with metadata (title, source, format)SearchResultWeb or knowledge-base search result with URL, snippet, and relevance scoreTextWithSourcesText content with inline source citationsChatConversationPrior conversation history (message list with roles)ExtractionColumnDefines column schema for entity extractionMatchedSegmentA chunk or segment matched from a larger document (defined in the Search service, not registered as a GWE well-known type)RulesetA set of business rules for validation agentsDateCalendar date valueDateTimeDate and time valueAnyAccepts any type (used for generic ports) Additional framework types (such as DatastoreConnection, FusionLlmConfig, DataProtectionConfig, and others) are used internally by the platform. Framework types are automatically prepared for LLM consumption when passed to LLM-based agents. For example, a SearchResult is formatted with its title, URL, and snippet in a way that the LLM can reference and cite. Array Types An array type represents an ordered list of a single element type. Array types use the syntax array { <element_type> }. Examples: array { STRING }: A list of strings (analogous to []string in Go). array { Document }: A list of documents. array { array { STRING } }: A nested array (analogous to [][]string in Go). Arrays are used heavily in multi-binding patterns where an agent consumes outputs from multiple upstream agents. Array Type-Checking When a multi-binding connects multiple upstream outputs to an array input: All bound values must match the array's element type. For nested arrays, the element type may itself be an array type. Enumerations User-defined enumerations represent a fixed set of possible values. Enumerations are particularly useful for classification tasks where an agent must select from predefined categories. Example Ticket Priority Enum: Enum: TicketPriority Values: [LOW, MEDIUM, HIGH, CRITICAL] When an agent output is an enum type, it can be used in run-if conditions to drive branching logic: CLASSIFY (output: priority, type: TicketPriority) +-- [run-if priority == HIGH] --> Escalate +-- [run-if priority == LOW] --> AutoResolve Enumerations are defined as part of the agent's output specification. The Workflow Builder displays the available values when configuring conditional branches. Next: Workflow Validation

================================================================================
# Workflow Validation
URL: https://builder.ema.ai/core-concepts/workflow-validation
================================================================================

Workflow Validation GWE performs static validation on workflow definitions to catch errors before runtime. The validation system simulates workflow execution with dummy inputs to verify that all execution paths produce the required outputs and that the workflow structure is sound. What Static Validation Checks Static validation verifies: All required bindings are present: Every required input port has a binding. Type compatibility: All bindings connect compatible types (see Type System). No cycles: The workflow DAG contains no circular dependencies. Required outputs are produced: Every required Named Output is produced on every possible execution path. Custom rules: Any persona-type-specific validation rules are satisfied. How Validation Works The validation process has two stages: Stage 1: Path Enumeration The engine enumerates all possible execution paths through the workflow. A path is the set of agents that execute based on the conditional branching rules. Branching agents: An agent is considered a branching agent if one of its outputs is used in a run-if condition by at least one downstream agent. When the engine encounters a branching agent during traversal, it creates a separate path for each possible output value. For example, if a CLASSIFY agent produces an enum with three values (Class1, Class2, Class3), the engine creates three paths: Path 1: Trigger -> CLASSIFY(->Class1) -> B -> C -> D -> Output Path 2: Trigger -> CLASSIFY(->Class2) -> E -> F -> Output Path 3: Trigger -> CLASSIFY(->Class3) -> G -> Output Stage 2: Per-Path Validation For each enumerated path, the engine: Plugs in dummy inputs for workflow inputs and widget bindings. Simulates agent execution by plugging in dummy outputs for each non-branching agent that is allowed to execute. For branching agents, uses the specific branch value chosen for this path and dummy values for all other outputs. Validates that all required Named Outputs are produced. Validates any custom rules defined for the persona type (e.g., Agent Assist AI Employees may have specific output requirements). Validation skips all calls to databases and external microservices. It tests the workflow structure, not the runtime behavior of individual agents. Validation Errors Validation errors appear in the Issues tab of the Workflow Builder. Common validation errors include: ErrorCauseResolutionRequired output not producedA required Named Output is not bound to any agent on one or more paths.Connect the output to an eligible agent on the missing path.Missing required bindingAn agent's required input has no binding.Add a binding (upstream output, workflow input, constant, or widget).Type mismatchA binding connects incompatible types.Verify that the source type matches the destination port type.Cycle detectedThe workflow graph contains a circular dependency.Remove the circular binding.Unknown agent typeAn agent instance references an unregistered agent type.Verify the agent type name and ensure it is registered. When Validation Runs On save: Validation runs automatically when you save a workflow in the Workflow Builder. Workflows with validation errors cannot be saved by default. On deploy: The engine re-validates before executing a workflow. If validation fails, the execution is rejected. Static validation errors are stored alongside the workflow definition and are surfaced in the Issues tab. Next: Workflow Version History

================================================================================
# Workflow Version History
URL: https://builder.ema.ai/core-concepts/workflow-version-history
================================================================================

Workflow Version History Every AI Employee's workflow accumulates changes over time as builders add agents, adjust bindings, modify prompts, and tune conditional logic. Workflow Version History provides a structured record of these changes, enabling teams to understand what changed, when, and by whom. What Version History Tracks Each time a workflow is saved or published, the platform records a version entry (also called a change log entry). A version entry captures: Timestamp: When the change was made. User: Who made the change. Change type: The nature of the modification (e.g., workflow publish, configuration update, agent addition or removal). Workflow snapshot: The complete workflow definition at that point in time, enabling comparison between any two versions. Viewing Version History To access version history for an AI Employee: Navigate to the AI Employee's configuration page. Open the Version History panel (accessible from the Workflow Builder or the AI Employee settings). Browse the chronological list of versions. Each entry shows the timestamp, author, and a summary of changes. Viewing Existing Versions The Version History view helps builders inspect previously saved workflow versions and understand how the workflow evolved over time. This is useful for: Debugging regressions: Identify which change caused a workflow to behave differently. Reviewing prior versions: Understand what changed between existing workflow versions. Audit compliance: Demonstrate what configuration was active at a specific point in time. Reverting to a Previous Version If a workflow change introduces unexpected behavior, you can revert to a previously published version: Open the Version History panel. Select the target version to update the workflow canvas and show that version's workflow definition. Click Restore to immediately publish that version by creating a new version entry with the restored workflow contents. Restoring a previous version does not delete any history. It immediately republishes the selected version as a new version entry, preserving the full audit trail. Version History and Audit Logs Workflow version history is complemented by the platform's Audit Log, which records broader events beyond workflow changes: Record TypeScopeExamplesVersion HistoryWorkflow definition changesAgent added, binding modified, prompt updated, workflow publishedAudit LogAI Employee-level events outside workflow versioningAI Employee configuration updates, data source additions, and similar AI Employee-level configuration changes Together, version history and audit logs provide a fuller picture of an AI Employee's evolution -- combining workflow version changes with other AI Employee-level activity. Best Practices Publish incrementally: Make small, focused changes and publish after each one. This keeps the version history granular and makes it easier to identify which change caused a specific behavior. Use version history for traceability: Review prior published versions to understand how the workflow changed over time and to restore a known-good version when needed. Use audit logs for compliance: For regulated environments, combine workflow version history with audit logs to create a complete change audit trail. Previous: Workflow Validation | Back to: Core Concepts Index

================================================================================
# Workflows and Actions
URL: https://builder.ema.ai/core-concepts/workflows-actions
================================================================================

Workflows and Actions A workflow is the executable program that defines an AI Employee's behavior. A workflow is composed of actions -- discrete units of work that the engine executes in sequence according to a directed acyclic graph (DAG). Action Types An ActionType is analogous to a function signature. Each action type defines: A unique name identifying the action. Input parameters -- the data the action consumes, each with a name and type. Output parameters -- the data the action produces. An implementation type that tells the engine how to invoke the action (e.g., via RPC to a backend service). Ema provides a large library of pre-built action types (agents) covering common tasks. Builders select from this library when constructing workflows -- action registration is managed internally by the platform. Search agents -- Retrieve information from knowledge bases, web, or connected applications. LLM agents -- Generate text, classify content, extract entities, or respond to queries. Classification & Routing agents -- Categorize incoming requests and route them to the appropriate workflow branch. Response agents -- Publish or deliver the final output of a workflow to the end user or downstream system. Tool agents -- Execute external API calls, database queries, or other integrations. Human Collaboration agents -- Pause execution for human review, approval, or input (Human-in-the-Loop). Validation agents -- Apply rule sets and business logic checks. Conversion agents -- Transform data between formats (e.g., Convert to Text). Custom Code agents -- Execute sandboxed JavaScript or TypeScript code within workflows for bespoke processing logic that falls outside standard agent capabilities. The sandbox does not support third-party packages or other languages. Action Instances An ActionInstance is a single invocation of an action type within a workflow -- analogous to a single line of code that calls a function. Each action instance specifies: Which action type to call. Bindings that connect each input parameter to a data source. An optional run-if condition for conditional execution (see Conditionals). WorkflowDef +-- Action Instance: "search_knowledge_base" | +-- Type: search/v2 | +-- Input: query <- workflow_input("user_message") | +-- Output: search_results +-- Action Instance: "generate_response" | +-- Type: call_llm | +-- Input: context <- search_knowledge_base.search_results | +-- Output: response_text +-- Workflow Output: "response" <- generate_response.response_text The DAG Model The engine compiles a workflow definition into a DAG by inspecting the set of action instances and their bindings: Nodes are action instances. Edges are bindings -- each edge represents a data dependency from one action's output to another's input. Topological ordering ensures that every action runs only after all of its dependencies have completed. Parallel Execution Actions that have no data dependencies between them can execute in parallel. In the following example: Trigger --> A --> B \-> C B, C --> D Actions B and C both depend only on A, so they run in parallel after A completes. Action D waits for both B and C before executing. Cycle Detection The engine rejects workflow definitions that contain cycles. A cycle means an action depends (directly or transitively) on its own output, which would create an infinite loop. Workflow Definition Structure A workflow is defined as a WorkflowDef protobuf message containing: FieldDescriptionAction instancesThe set of action calls and their bindingsTriggerThe entry point that activates the workflowWorkflow outputsNamed outputs bound to specific action outputs (see Named Inputs and Outputs)Shared configurationPersona widgets and resources available to all actions Execution Flow When a workflow is invoked: Input assembly: The engine receives the invocation request (e.g., a user message) and maps it to workflow inputs. Graph traversal: The engine walks the DAG in topological order. Action execution: For each action instance: Assemble input data from upstream outputs, workflow inputs, constants, or persona widgets. Evaluate the run-if condition (if present). Skip the action if the condition is false. Invoke the action provider (typically via RPC). Store the output for downstream consumers. Output collection: Once all actions have completed (or been skipped), the engine collects the configured workflow outputs and returns them. Not every invocation is guaranteed to return all configured outputs. Conditional branches may cause some actions (and their outputs) to be skipped. See Conditionals for details. Action Providers The workflow engine itself does not implement individual action logic. Instead, it delegates to action providers -- remote services that host the actual code for each action. The engine is responsible for: Orchestrating the order of execution and data flow. Mediating data between actions (type-checking, binding resolution). Handling conditional logic and skip propagation. The actual reasoning, search, or API call logic lives in the action provider services. Next: Conditionals

================================================================================
# Workspaces and Tenants
URL: https://builder.ema.ai/core-concepts/workspaces-tenants
================================================================================

Workspaces and Tenants Ema's platform uses a multi-tenant architecture to provide secure, isolated environments for partners and their customers. A workspace (also called a tenant) is the fundamental unit of data isolation on the Ema platform. Each workspace has its own: Users and roles -- Managed independently; access to other workspaces must be explicitly granted. AI Employees -- Operate within that workspace's data boundaries. Data, workflows, and configurations -- Fully isolated from every other workspace. Workspace-Level Roles Workspace roles govern what a user can do across the workspace as a whole. RoleWorkspace ManagementBuild AccessDefault AI Employee RoleAdminCan invite users, view metricsCan build new AI EmployeesAI Employee AdminManagerCan invite users, view metricsNo accessAI Employee ManagerBuilderNo privilegesCan build; receives Admin role for AI Employees they createNo access (unless invited)GuestNo privilegesNo accessNo access (unless invited) AI Employee-Level Roles AI Employee roles govern what a user can do within a specific AI Employee. All users can use the AI Employee; these roles control management privileges. RoleAI Employee ManagementWorkflow AccessAudit LogsAdminCan invite users, view metricsCan editCan viewManagerCan invite users, view metricsCan view (read-only)Can viewProject UserNo privilegesNo accessNo access A user's workspace role determines their default AI Employee role. However, users can be granted different roles for specific AI Employees independently. For example, a user with the Guest workspace role could be given the Builder role for a particular AI Employee. Parent-Child Workspace Relationships Ema supports hierarchical workspace relationships where a parent workspace can have one or more child workspaces. Key Rules CapabilityDirectionDetailsUser AccessDownwardParent users can access child workspaces, but only on explicit invitation. Access is never automatic.Template SharingDownwardParent workspaces can share AI Employee templates to child workspaces.MetricsUpwardAggregated metrics roll up from child to parent. No PII or log data moves upward. -- metrics rollup may still be in development.Data and LogsNoneNo data flows between workspaces in either direction. Constraints A child workspace can only have one parent. Workspace hierarchies can be multiple levels deep -- child workspaces can have their own children. Only a parent workspace's users can be invited to its direct child workspaces. You cannot skip levels (a grandparent user must first be added to the parent, then to the child). Workspace Management Models Partners can organize their customer workspaces using one of four models. Model 1: Standard (Recommended) Each customer gets its own workspace with full data isolation. Best when: Each customer requires full data isolation. Customers may log into the Ema platform directly. You need clear boundaries between customer environments. Model 2: Multiple Workspaces for the Same Company Internal separation by region, department, or business unit. Limitation: Every workspace requires a unique domain. Additional workspaces for the same company must use a non-standard/placeholder domain (e.g., company-us.co instead of company.com). Model 3: Single Workspace Across Multiple Companies All customers operate within the partner's single workspace. Best for: Customers that interact via embedded chatbots, SDKs, or APIs (not the Ema UI). Small customers or lightweight use cases. Scenarios where the partner fully manages all AI Employees. Data separation is achieved at the AI Employee level (data does not flow between AI Employees unless explicitly connected) and at runtime (individual workflow executions are isolated). Model 4: Data Localization Across Geographies For data residency and compliance requirements, separate Ema environments must be provisioned in each target region. Sub-workspaces do NOT solve data localization. All workspaces within the same environment share the same underlying infrastructure. True data localization requires a completely separate Ema environment in the target geography. Separate environments have no cross-environment template sharing, metrics aggregation, or user access. Choosing the Right Model CriteriaStandardMulti-WorkspaceSingle WorkspaceGeo-LocalizedData isolationFullFullAIE/RuntimeFull (per env)Customer logs into UIYesYesNoYesSetup complexityLowMediumLowestHighestBest customer sizeAnyLarge (internal sep.)Small/EmbeddedAny (global) Decision guide: Does the customer log into the Ema UI? If no and no dedicated isolation is needed, use Model 3. If yes, does the same company need internal separation (region/department)? If no, use Model 1. If internal separation is needed, are there data residency requirements? If no, use Model 2. If yes, use Model 4. Switching Workspaces Current state: When a partner user needs access to a child workspace, they must use an email alias (e.g., admin1+acme@partner.com) and log out/log in to switch between workspaces. Future state (Workspace Switcher): An upcoming update will eliminate alias-based access: Same email/user ID works across all workspaces. Workspace switcher dropdown in the UI -- no log out/log in required. Access to child workspaces still requires explicit invitation. -- The workspace switcher feature may have shipped since this documentation was drafted. Check the current release notes for availability. FAQs What is the smallest unit of data isolation? The workspace. AI Employees also have data separation, and individual workflow executions have runtime isolation. Do child workspaces inherit users from the parent? No. Users must be explicitly invited to each child workspace. Can templates be shared upward from child to parent? No. Templates can only be shared downward. How do I prevent a customer from building AI Employees? Assign the customer's users as Manager or Guest (no build access). Next: GWE Overview

================================================================================
# Builder Guides
URL: https://builder.ema.ai/builder-guides
================================================================================

Builder Guides This section contains hands-on tutorials for building AI Employees with Ema's Generative Workflow Engine (GWE). Complete each tutorial in order for the best learning experience. When and How to Get Started Ema offers easy-to-use templates for a powerful suite of pre-built AI Employees. In most cases, you can select a template, add your data and integrations, customize it with natural language instructions, and quickly launch an AI Employee for your customers. However, there are situations where you may need to go beyond templates: Minor customizations to an existing template that cannot be achieved with natural language changes. Creating a brand-new AI Employee for a workflow Ema has not solved before. In these cases, you will use the Generative Workflow Engine (GWE) AI Employee Builder. While it is a no-code, intuitive platform for new and non-technical users, we recommend completing all tutorials in this section first. Each tutorial presents a clear problem statement and includes sample data so you can follow along, practice, and quickly learn best practices. The pre-built AI Employee Library provides detailed documentation on each agent. Use it as a glossary to find relevant agents for workflow steps that are not covered in the tutorials. Key Questions to Answer Before You Begin Can I modify an existing template, or do I need to start from scratch? Search the templates in your Ema workspace or in the Pre-built AI Employees section of these docs. You may find a workflow that is a good starting point -- even if it is from another industry or domain. Use Autopilot to find relevant templates with Ema's help. What is the best user interface for my use case? Choose between: Chat Dashboard (including bulk analysis) Document Generation Voice Conversational Email For API based workflows, a dashboard is often the best choice due its ability to validate against specific inputs and outputs. Do I clearly understand the problem and the agentic steps involved? Read the Discovery section in these docs for frameworks on defining a use case. Ensure you have high-quality test data: input data, test queries, and "golden" outputs. Tutorials in This Section Chat AI Employees Creating Your First Workflow -- Build a simple RAG workflow from scratch. Adding Workflow Branches -- Use intent classifiers and document categorizers to route queries. Writing Effective Instructions -- Principles for writing clear, effective agent instructions. Improving Chat Performance -- Build embeddable chatbots with conversation context and multi-branch logic. Dashboard AI Employees Creating a Dashboard AI Employee -- Build a Document Intelligence Suite for bulk analysis. Creating Dashboard Triggers -- Configure structured input fields for dashboard workflows. Publishing to Dashboard -- Publish agent outputs to the dashboard table view. Dashboard Features -- Core capabilities of the Agentic Dashboard. Document Generation Document Generation -- Create section-by-section document generation workflows with Doc Writer. Voice AI Employees Creating a Voice AI Employee -- Configure multilingual, low-latency voice agents. Conversational Email Creating a Conversational Email AI Employee -- Automate inbox monitoring and intelligent reply generation. Advanced Topics Using AI Employees as Agents -- Embed one AI Employee inside another's workflow. Integrating External Systems -- Use Intelligent Actions for 200+ pre-integrated connectors. Creating AI Employee Templates -- Package workflows as reusable templates. Customizing In-Progress Messages -- Show live status updates during chat workflow execution. Scraping Web Links -- Crawl and ingest content from web pages as data sources. Workflow Version History -- View, compare, and revert workflow versions. End-to-End Examples Employee Assistant -- HR assistant with intent classification, personalization, and document search. Sales Intelligence Assistant -- Market intelligence reports from web search and document generation. Resume Ranker -- Bulk resume scoring with the Document Intelligence Suite.

================================================================================
# Using AI Employees as Agents
URL: https://builder.ema.ai/builder-guides/advanced/ai-employees-as-agents
================================================================================

Using AI Employees as Agents This guide explains how to embed one AI Employee inside another's workflow. This capability enables sophisticated, multi-step workflows by chaining specialized AI Employees -- for example, having a conversational agent trigger a document generation process. Supported AI Employee Types AI Employee TypeEnabledChatYes (only with named outputs)DocGenYesDashboardYes (only with named outputs) Part 1: Making an AI Employee Callable (Callee Configuration) This feature must be explicitly enabled on the callee AI Employee: Ensure the AI Employee is enabled. Navigate to the Permissions tab of the AI Employee. Turn on the option Enable this AI Employee as an agent in your workspace. This step generates an agent that can be used in other AI Employees' workflows. Part 2: Invoking the AI Employee (Caller Configuration) Within the workflow of the calling AI Employee (the caller), add the agent generated from the callee AI Employee and create the appropriate connections: Navigate to the caller AI Employee's workflow canvas. Open Add an Agent in the top-left corner of the canvas. Navigate to the AI Employees category in the agent list, where you will find the callee AI Employee. Add the callee to the canvas. You will now be able to create connections. Disabling a Callee AI Employee To disable the callee AI Employee's callable configuration: Navigate to the Permissions tab of the callee AI Employee. Turn off the option Enable this AI Employee as an agent in your workspace. This will prevent the AI Employee from showing up in the agents section, mark the existing usages as "unavailable," and fail the execution of these workflows.

================================================================================
# Creating AI Employee Templates
URL: https://builder.ema.ai/builder-guides/advanced/creating-templates
================================================================================

Creating AI Employee Templates Templates allow you to package an AI Employee's workflow and configurations into a reusable starting point. Other builders in your workspace can then create new AI Employees from your template, preserving the workflow structure, agent instructions, and settings. How to Create a Template Step 1: Build the Source AI Employee Create an AI Employee that has the workflow and configurations (such as instructions) that you want to reuse. Step 2: Create the Template Click on the three dots beside the AI Employee's name to find the option Create AI Employee Template. Step 3: Fill in Template Details A modal will appear. Provide: Template Name -- A clear name for the template. Description -- A brief summary of what the template does. AI Employee Category -- The category assigned to AI Employees created from this template. About Template -- A longer description explaining the use case and workflow. Step 4: Add Supporting Information Optionally provide new values for: Value Propositions -- What benefits the template offers. How to Use -- Steps for users to get started with the template. Additional Context -- Any extra information to help template users. We recommend skipping Advanced Settings unless you are familiar with workflow and persona configurations. Step 5: Navigate to the Template Navigate to the template by searching for it or by clicking on the success message after creation. Step 6: Edit or Delete the Template You can edit or delete the template by clicking on the three dots. These features are only available for templates that were created in your tenant. Templates provided by Ema or your parent tenant cannot be edited or deleted.

================================================================================
# Integrating External Systems
URL: https://builder.ema.ai/builder-guides/advanced/external-systems
================================================================================

Integrating External Systems The Intelligent Actions agent (formerly External Tool Caller) lets an AI Employee execute concrete actions -- such as creating a ServiceNow ticket, filing PTO in Workday, or updating a Salesforce opportunity -- directly inside the target system, without writing code. More than 200 pre-integrated connectors are available. Common Scenarios ScenarioExample SystemsTypical OutcomeEmployee AssistantWorkday, JiraSubmit time-off requests; open or update IT ticketsFinance and AuditCoupa, SAP, NetSuiteGenerate purchase orders; reconcile ledgersSales IntelligenceSalesforce, HubSpotEnrich leads; advance opportunity stages Intelligent Actions Agent Anatomy ElementDescriptionInputsUser query and, if needed, conversation historyConfigurationAllowed apps and tools (for example, Create Ticket in ServiceNow) plus high-level instructions that help the AI Employee choose the correct actionOutputRaw JSON returned by the external system; downstream agents transform this into end-user-friendly text The decision engine inside the agent evaluates the request, selects the appropriate tool, fills required parameters, executes the call, and returns the result for post-processing. Using Pre-Built Tool Support Step 1: Connect the App Open the Integrations page and choose the target application (for example, ServiceNow). Select Connect against the "Intelligent Actions integration" field and complete OAuth or key-based authentication. When the connector card shows Connected, the application is available for use within the current tenant. Step 2: Enable Specific Tools Within the same application panel, switch to the Tools tab and enable only the desired actions (for example, Create Ticket, Update Ticket Description). This gives you granular control over which actions are in scope per application within your tenant. Step 3: Add Intelligent Actions to Your Workflow Drag the Intelligent Actions agent onto your workflow canvas. Connect it to the appropriate input source -- typically the workflow trigger or a prior logic block that handles user queries. To display the output of the tool call, link the Respond with Tool Result agent immediately downstream. This response agent interprets both the original input query and the raw output from the Intelligent Actions agent, applying your configured instructions to return a user-friendly response. Step 4: Configure the Intelligent Actions Agent Once the agent is selected, a configuration panel appears on the right. Click + Add to open the tool selection menu. Choose your target application and select the specific tool actions you want to enable. A single Intelligent Actions agent can support multiple applications and tools. It selects the appropriate tool within the correct system based on the context of the incoming user query. Step 5: Configure Tool Parameters Each tool may require a different set of input parameters. Click Manage against any tool to open its parameter configuration screen. For each input, you can specify: Fixed value -- Use a specific constant for a parameter (for example, always default the User ID to a predefined value). Enabling Human-in-the-Loop (HITL) Review Ema can pause execution and hand off control to a human reviewer before proceeding with a tool action. When HITL is enabled, the agent will prompt the user with a confirmation step. You can configure: The message text The button labels You may also choose to hide specific parameters from the confirmation view (such as internal fields like User ID) to maintain clarity and protect sensitive data. If your target system is not in the pre-built catalog, see Custom Integrations to connect any external API.

================================================================================
# Customizing In-Progress Messages
URL: https://builder.ema.ai/builder-guides/advanced/in-progress-messages
================================================================================

Customizing In-Progress Messages With In-Progress Messages enabled, users see live progress updates as the AI Employee works -- showing exactly what it is doing in real time instead of a static "Processing your request..." placeholder. You see updates like "Searching knowledge base...", "Generating response..." as each step of the workflow executes. The final answer replaces these updates once the workflow completes. This creates a faster, more transparent experience where users can see that their request is being actively handled. Supported AI Employees Currently supports only Chat SDK and MS Teams chat interfaces. Customize Messages in Agent Configuration You can set custom in-progress messages for any agent when configuring it within your workflow. This allows you to tailor the messages to match your specific use case, brand voice, or the context of what the agent is doing. For example, instead of the generic "Searching the knowledge base," you might set a custom message like: "Looking through your HR policy documents" "Checking the product catalog for matching items" How to Set a Custom Message Open your AI Employee's workflow in the builder. Select the agent you want to customize. In the agent configuration panel, inside Advanced Settings, find the Message displayed during agent execution field. Enter your custom message text. Tips for Writing Effective Custom Messages Keep messages short and easy to scan -- one concise sentence works best. Write from the user's perspective -- describe what is happening for them, not technical internals. Be specific to your use case. "Reviewing your claim documents" is more helpful than "Processing data." Avoid jargon or internal terminology that end users would not recognize. Benefits Reduced Perceived Wait Time You see continuous activity instead of staring at a loading spinner. Even if the actual processing time is the same, the experience feels significantly faster. Transparency You can see exactly what the AI Employee is doing -- searching documents, processing results, generating responses. This builds confidence that their request is being handled properly.

================================================================================
# Scraping Web Links
URL: https://builder.ema.ai/builder-guides/advanced/scraping-web-links
================================================================================

Scraping Web Links This guide explains how to configure an AI Employee to crawl and ingest content from specific web pages. Web scraping lets you use publicly available web content as a data source for your workflows, keeping your AI Employee's knowledge base current with information from websites, help centers, and documentation portals. Prerequisites The specific URLs you wish to scrape and ingest Access to the Ema platform dashboard Part 1: Creating the AI Employee Step 1: Create a New AI Employee Navigate to Ema's AI Employees page via the main dashboard. Click the Create New Employee button. Step 2: Configure the AI Employee Profile Select an AI Employee template (for example, Conversation AI Employee). Fill in the required fields: name, description, and type. Proceed to the configuration area once the basic profile is set up. Part 2: Workflow Configuration and Web Scraping Step 3: Access Shared Configurations On the AI Employee configuration page, navigate to the Workflow Builder. Locate and click the Shared Configurations button in the top-left corner of the interface. Step 4: Add a Web Scraping Data Source In the Shared Configuration modal, click the Add button and select the option to Scrape Web Links. Step 5: Configure Ingestion and Import Settings Paste the specific web links you wish to crawl into the Base URL field. A URL is required to proceed. Before starting the scrape, configure your Import Settings: SettingDescriptionDefaultMaximum pagesThe total number of web pages to import from this URL.200 (minimum: 1)Website navigation depthHow many folder levels deep the crawler should explore. A depth of 2 includes paths like /policies/hr/.2 (minimum: 1) If no custom values are provided, the system uses the defaults listed above. Ema clicks on all links on the page and scrapes downstream pages up to the configured depth. Ema also downloads any documents such as PDFs encountered during the scraping. Step 6: Ingest Web Links After configuring import settings, the system begins processing the URLs to extract and ingest the content. Part 3: Verification and Status Step 7: Verify Completion Wait for the processing status to update. You will see a confirmation status indicating Completed once the scraping process finishes. Web link scraping can take a few minutes depending on the number of pages and depth configured. Part 4: Synchronization Settings Step 8: Configure Sync Options Once the web links have been successfully scraped, you can manage their synchronization frequency to keep the AI Employee's knowledge up to date. Manual sync -- Click the three dots (...) next to the source in the root folder and select Sync Now to refresh data manually. Automatic sync -- Click the Auto Sync dropdown and select a sync interval: 1, 7, 15, or 30 days. For frequently updated websites such as help centers or documentation portals, set automatic sync to 1 or 7 days. For relatively static content, 15 or 30 days is sufficient.

================================================================================
# Workflow Version History Guide
URL: https://builder.ema.ai/builder-guides/advanced/workflow-version-history
================================================================================

Workflow Version History Guide Every time you save a workflow, Ema creates a new version. The Version History panel lets you browse past versions, see exactly what changed between saves, preview any previous version on the canvas, and revert to a prior state when needed. Opening Version History From the workflow builder canvas, click the clock icon (Version History) in the toolbar. A drawer slides in from the right showing all saved versions, ordered from newest to oldest. The total version count is displayed in the drawer header. Browsing Versions Each entry in the version list shows: DetailDescriptionTimestampWhen the version was saved, displayed in a friendly relative format (for example, "2 hours ago").AuthorThe email address of the builder who saved the version.Version badgeA numbered badge such as v12. The current (latest) version is highlighted in green.Revert indicatorIf a version was created by reverting, it displays the source version number (for example, "reverted from v8"). Versions load incrementally as you scroll. When more versions are available, they are fetched automatically as you approach the bottom of the list. Viewing Change Summaries When you select a version or view the latest version, a Change Summary panel appears below the version entry. This panel compares the selected version against the immediately preceding version and shows a list of changes: Added items (green icon) -- New agents, connections, or configuration elements introduced in this version. Removed items (gray icon) -- Agents, connections, or configuration elements that were deleted. Modified items (amber icon) -- Agents or settings whose configuration changed (for example, updated instructions or renamed agents). Each change is displayed as a compact pill showing the change type and a brief description. Hover over any change pill to see additional detail in a tooltip. If more than three changes exist, click See more to expand the full list. Previewing a Past Version Click a version entry to load that version on the canvas. Older versions open as a read-only preview so you can visually inspect the agents, connections, and layout, while the current version remains clickable so you can review its change summary and detailed changes. To exit preview mode, click the close button in the top-right corner of the history previewer. The canvas returns to the live workflow state. Reverting to a Previous Version While previewing a past version, a Revert button appears in the version history panel. Clicking Revert restores the workflow to the state captured in that version. This creates a new version entry (so no history is lost) and the change summary for the new version will show "reverted from vN" to indicate its origin. Reverting replaces the current workflow state with the selected version. Any unsaved changes to the current version will be discarded. Review the change summary and preview carefully before reverting. Best Practices Save frequently -- Each save creates a checkpoint you can return to. Save before and after significant changes so you have clean rollback points. Preview before reverting -- Always preview a version on the canvas to confirm it is the state you want before clicking Revert. Use change summaries to audit -- When collaborating with other builders, use the change summary to understand what was modified in each version without opening every version individually.

================================================================================
# Creating Your First Workflow
URL: https://builder.ema.ai/builder-guides/chat/first-workflow
================================================================================

Creating Your First Workflow This tutorial walks you through building a simple RAG (Retrieval-Augmented Generation) workflow from scratch using the Generative Workflow Engine (GWE). By the end, you will have a working AI Employee that searches uploaded documents and answers questions with source citations. Sample file used in this tutorial: GDPR Document (PDF) Step 1: Access the AI Employee Tab Navigate to the AI Employee section in the Ema App. Scroll down to the "Create an AI Employee" area and click the Create button on the first tile. For this tutorial, select the Chat AI Employee option. Step 2: Name Your AI Employee Provide a distinctive name (for example, "Compliance Analyst") to identify your new AI Employee. Step 3: Launch the GWE Canvas After creation, you will be directed to the GWE canvas. The initial view displays shared configurations and resources accessible to all agents within the workflow. Step 4: Connect Applications and Resources Link the necessary apps so that every agent in your workflow has access to required resources. This feature is currently disabled for beta access users. Add data sources by creating folders. These sources will be available to agents that require specific data. You can create two types of folders: File upload folders -- Upload files from your local system or from linked file storage apps. Linking your file storage app will not make it available to other users in your workspace. Files and folders uploaded from linked apps refresh nearly real time (up to 10-minute delay). Web scraping folders -- Web link scraping can take a few minutes to complete. Ema clicks on all links on the page and scrapes the downstream pages as well, up to two children depth from the main link you provide. Ema also downloads any documents such as PDFs encountered during the scraping. Ema does not re-scrape these files after the first time. For detailed web scraping configuration, see Scraping Web Links. Supported file formats: Ema can currently ingest and understand DOCX, PDF, TXT, PPT, XLSX, HTML, and common image files. Step 5: Configure Default Settings Set up the default EmaFusion™ configuration that applies to all agents. This setting can later be overridden at the individual agent level. Step 6: Add a Basic Respond Agent Click Save to return to your blank workflow canvas. Navigate to the "Frequently Used Agents" section in the agent library and select Respond to a Query. You can also use the search bar to find this agent. Step 7: Establish Agent Connections Input the query that a user might provide by clicking on the Query input in the Respond to a Query agent. This query will be processed by the LLM agent. Clicking on an input with a dropdown symbol shows you all eligible values on the canvas that can be connected. Alternatively, click on an output from an agent and use the plus icon to explore eligible agents for connection. If there are none, use the Connect a New Agent option to view and add agents capable of utilizing the output. Step 8: Adjust Agent Placement and Inputs Drag agents onto the canvas and click on their inputs to review available outputs for connection. Ensure the data flow is logical. Step 9: Configure Agent Instructions Click on an agent to open its configuration panel on the right-hand side. Provide specific instructions as needed, for example: Set the language tone to professional Request bullet-point formatting Define the response length Step 10: Incorporate Data Search Functionality To update the LLM's knowledge with current data, add a File Search agent that queries the data sources you have set up. Use the same query as the user's input and assign your data sources to this agent in its configuration drawer. Step 11: Update and Replace Agents if Necessary Remove any temporary agents that are no longer needed, such as the Respond to a Query agent. Add a new agent to process and respond using the search results from the File Search agent. Step 12: Finalize the Workflow Output Assign the query to the new agent to process the search results. Select the final LLM response as the output to be published. Eligible outputs will have the option to publish as workflow output. Certain outputs such as Search Results cannot be published directly to the user. Step 13: Publish and Save the Workflow Publish the workflow output and save your changes to complete the AI Employee setup. Step 14: Enable Your AI Employee Return to the AI Employee configuration page and toggle the switch to enable the AI Employee. Your AI Employee is now ready for use in chat. Step 15: Test the AI Employee Interact with your AI Employee by asking questions (for example, "What is a DPO?"). The AI Employee will search through connected files and links and provide an answer, including precise source citations such as page numbers and paragraphs. Click Show Work to review the detailed steps and source references generated by the AI Employee. Read Next Now that you have created a simple RAG workflow on GWE, you can move on to improve the accuracy of such a workflow. The following tutorials cover intent classification, workflow branching, and other techniques: Adding Workflow Branches -- Use intent classifiers to route queries dynamically. Writing Effective Instructions -- Principles for writing clear agent instructions. Improving Chat Performance -- Build embeddable chatbots with conversation context.

================================================================================
# Improving Chat Performance
URL: https://builder.ema.ai/builder-guides/chat/improving-performance
================================================================================

Improving Chat Performance This guide details how to build an embeddable chatbot AI Employee, customize its appearance and behavior, develop a workflow with conversation context, and embed it into your website. It also introduces two agents: the Conversation Summarizer and Static Response. Overview Ema supports in-app chat functionality and also allows you to build a chatbot AI Employee that can be embedded directly into your website. This guide covers the full process: creating the chatbot, customizing it, building the workflow, and embedding it. Step 1: Initiate Chatbot Creation Locate the tile labeled GWE Chatbot AI Employee within the Ema interface. Assign a name to your new AI Employee (for example, "Compliance Chatbot"). Click Create. Step 2: Access the Chatbot Configuration Page Upon creation, you are directed to the chatbot configuration page with various widgets, including the chatbot SDK configuration. This page allows you to assign a unique name and set up initial parameters for your embeddable chatbot. Step 3: Customize Branding and Appearance Set the chatbot name (for example, "Compliance Chatbot"). Choose your brand's color to match your website's theme. Provide a welcome message that greets users when they interact with the chatbot. Update the logo by supplying a public URL for your brand's logo. Step 4: Save and Preview the Chatbot After making your customizations, click Save. A sample chatbot preview will show how the chatbot will appear on your website with your configured name, brand color, and welcome message. Step 5: Obtain the Embed Code Scroll down the configuration page to locate the embed code snippet. This code is used to insert the chatbot into your website's body, enabling it to appear on your site. Step 6: Develop the Chatbot Workflow Navigate to the Workflow Builder to develop the conversation flow. The trigger for the chatbot is the same as that used for the Ema webapp chat, but this workflow will incorporate additional context from the full chat conversation. Step 7: Enhance the Workflow with Conversation Context Since relying solely on the user query can limit context, integrate a Conversation Summarizer agent: Supply the summarizer agent with dialogue from the trigger to automatically generate a summarized version of the conversation. Optionally specify a context window by setting the number of conversation turns (for example, the last 10 messages) that should be referenced. Step 8: Implement Search and Response Mechanisms Add a search-and-respond mechanism that uses the summarized conversation to improve response accuracy. Best practices include: Employ an Intent Classifier that examines the full conversation and categorizes the query (for example, into GDPR or HIPAA categories). Provide the classifier with the entire conversation. Define clear question categories along with descriptions and potential user phrases. Optionally change the default category. If the classifier cannot categorize to one of the provided categories, it falls back to this default. Step 9: Configure Category-Specific Workflows Create specific branches within the workflow for each category: GDPR branch -- Set up search actions triggered only when the intent classifier identifies a GDPR question. Rename the search agent to "GDPR Search." HIPAA branch -- Add a dedicated Static Response agent. This agent always outputs the text it is provided with, regardless of the context or query. Rename it appropriately. Step 10: Provide Context in Query Inputs In the search query inputs, include the summarized conversation to provide additional context beyond just the latest query. Step 11: Publish Workflow Outputs Set the output of the search-and-respond mechanism by providing the summarized conversation and publishing this as the workflow output. Ensure that the response for each category is published as a workflow output so the correct response is consistently delivered when that category is triggered. Step 12: Activate the Chatbot Once the workflow is fully configured and published, return to the AI Employee configuration. Activate the chatbot to enable its functionality on your website. Step 13: Test the Chatbot Test the embeddable chatbot within the Ema web app chat to ensure it is functioning as expected. Verify that the branding, workflow, and response behaviors are correctly implemented.

================================================================================
# Adding Workflow Branches
URL: https://builder.ema.ai/builder-guides/chat/workflow-branches
================================================================================

Adding Workflow Branches This tutorial explains how to design a workflow that dynamically branches based on user input or specific output values. By integrating an intent classifier, you can ensure that queries are categorized accurately and directed to the appropriate agents. This capability enables your AI Employee to handle diverse user intents -- such as GDPR-related questions, HIPAA inquiries, or general queries -- with targeted responses. You can also follow these same instructions to branch your workflow using a Document Categorizer agent. Apart from user queries, branching can also be done based on the value or quality of agent outputs, external data points, or LLM reasoning. Step 1: Add a Categorizer or Intent Classifier To enable differential responses based on user input, incorporate a branching mechanism in your workflow using a categorizer or an intent classifier. The intent classifier analyzes the entire conversation data and determines the appropriate category for the query. Step 2: Define Categories Set up distinct categories within the classifier. For example: GDPR Questions -- Include clear descriptions and example phrases such as "What is a DPO?", "Tell me about GDPR compliance requirements." HIPAA Questions -- For compliance-related inquiries about healthcare data protection. General Inquiries -- A catch-all category for queries that do not fall under specific compliance topics. Include detailed descriptions and example phrases for each category to improve categorization accuracy. Step 3: Integrate the Intent Classifier Integrate the intent classifier into your workflow so that it processes the full conversation to identify the user's intent. Based on the identified category, the classifier directs the workflow to branch accordingly. For example, if a conversation is categorized as "GDPR questions," subsequent tasks such as a file search will be focused solely on GDPR data. Step 4: Create Workflow Branches At the point in your workflow where a branch is required: Click on the relevant agent block. Open the agent's options (via the three dots) and choose Trigger When. Select the classifier you want to use for branching. Choose the specific category that should activate the agent. For instance, selecting "GDPR questions" means the associated agent activates only when GDPR-related inquiries are detected. Step 5: Set Up Additional Branches To add another branch (for example, for HIPAA inquiries): Add a new search agent. Rename this agent to HIPAA Search. Create a new folder for HIPAA-related files, upload the relevant documents, and rename the folder to HIPAA Files. Verify that the HIPAA search agent is connected to the HIPAA files. Step 6: Connect Query Inputs and Outputs Provide a query input for the HIPAA search agent and connect it so that the agent can respond using the search results from the HIPAA Files. Submit a query and publish this output as part of the workflow. Step 7: Incorporate a General LLM Response Flow For queries that do not fit the compliance categories, integrate a simple LLM response flow. This flow directly processes the query and publishes the output without additional branching. Step 8: Finalize and Test the Workflow Ensure that the HIPAA branch is properly configured to trigger when the intent is identified as HIPAA. Confirm that the general inquiry flow is also correctly set up. Save your changes. Test your AI Employee using a sample query (for example, "What is Taylor Swift's birthday?"). Observe that the intent classifier accurately identifies the query category and routes the request to the appropriate LLM model. By following these steps, you can create an intent-based workflow that dynamically branches based on user input. This approach ensures that each inquiry is handled by the most relevant agents, providing accurate and context-specific responses.

================================================================================
# Writing Effective Instructions
URL: https://builder.ema.ai/builder-guides/chat/writing-instructions
================================================================================

Writing Effective Instructions These principles help you create clear, concise, and effective instructions for Ema's AI Employees across different use cases. Following them ensures better accuracy, faster outcomes, and less back-and-forth when building workflows. Core Principles for All Agents Clarity and Specificity Be exact about what you want. Instead of: Search sales Say: Search sales reports for Q1 2023 in PDF format. Include Relevant Context Tell the AI Employee why or where to look. Example: Retrieve recent competitive analysis from Gartner published in the last six months. Be Concise but Complete Aim for short, direct instructions that still give enough detail. Instead of: Go through these and see if there's anything interesting Say: Summarize the main findings from these documents. Structure Your Request Organize multi-part instructions with bullet points. Example: Search for competitor analysis Search for market trends Search for customer feedback Define the Desired Output Tell the AI Employee exactly what format and length you expect. Example: Generate a one-page summary of key market insights. Specify Feedback and Iteration Points Let the AI Employee know if you want interim results before final output. Example: Present initial search results before proceeding to detailed analysis. Agent-Specific Principles File Search Specify the file type or content type: Find references to sustainability initiatives in 2022 annual reports. Use metadata filters: Retrieve only Excel files uploaded after January 2023. Web Search Indicate if recency matters: Find the latest product reviews published within the last month. Specify sources if needed: Search only Forbes and TechCrunch articles. Market Research Define audience or market: Analyze recent trends in the North American fitness market. Specify insight focus: Identify emerging competitors and consumer behavior shifts. Structured App Search Be clear about filters: List open tickets from ServiceNow for priority 1 issues from the past week. Define output fields: Provide only ticket ID, summary, and status. Intent Classifier and Text Categorizer State categories upfront: Classify chat messages into complaint, request, or feedback. Explain how to handle ambiguities: If unclear, label as "other" and flag for manual review. Rule Validation State rules precisely: Flag transactions above $10,000 without documented approval. Provide exceptions: Allow deviations if marked as Executive Override. Chart Builder Define the dataset and comparison: Plot monthly sales figures comparing product A and product B from January to June. Specify chart type: Create a pie chart showing market share percentages by competitor. Document Categorizer Define categories and give examples: Categorize documents as financial report, technical manual, or marketing brochure. Clarify differences: Financial reports contain quarterly or annual financial data. Generate Document Specify language and variant: Translate document from English to Spanish (Latin America). Indicate tone and style: Maintain formal business language suitable for executives. By applying these principles, you will create instructions that help Ema's AI Employees deliver accurate, efficient, and on-brand results every time.

================================================================================
# Creating a Dashboard AI Employee
URL: https://builder.ema.ai/builder-guides/dashboard/creating-dashboard-ai-employee
================================================================================

Creating a Dashboard AI Employee Ema's Document Intelligence Suite empowers you to perform bulk analysis and reasoning over unstructured data by creating a dashboard-based AI Employee. This guide walks you through building a workflow using GWE, categorizing documents, extracting key data, and validating rules on documents. The following instructions use a financial use case -- analyzing invoices and purchase orders -- as an example. Agents Used Document Categorizer Entity Extraction with Documents Step 1: Locate the Dashboard AI Employee Tile Scroll down to find the tile labeled GWE Dashboards Persona. Step 2: Create a New Dashboard AI Employee Click Create on the tile and assign a name to your new AI Employee. In this example, the workflow demonstrates a financial use case. Step 3: Access the Configuration Page You will be directed to the configuration page where no agents are present initially. Notice the new tab labeled Table, which contains an empty dashboard with a single input column for documents. Output columns will appear as the workflow is developed. Step 4: Open the Workflow Builder Proceed to the Workflow Builder. In the builder, you will see a new trigger type where the output is the document uploaded by end users on the dashboard. Step 5: Integrate Document Intelligence Agents Search for the Document Categorizer agent and integrate it into your workflow. Configure its input to accept documents from the designated trigger. Step 6: Create Document Categories Set up categories to classify the uploaded documents. For this financial use case, create categories for Invoice and Purchase Order. For each category, provide detailed descriptions and example phrases to improve categorization accuracy. Step 7: Create Workflow Branches for Each Category Establish distinct branches in the workflow based on the document categories. For invoices, the workflow will extract specific values such as the invoice number and supplier name. Step 8: Configure Data Extraction for Invoices Locate the agent named Entity Extraction with Documents. Pass the documents from the trigger to this agent. Configure the columns to extract the required data. For instance, add a column for Invoice Number. Provide example phrases and instructions, specify the expected output format, and indicate if the value is text, numeric, or Boolean. Use Advanced Settings to restrict outputs to a predefined list of values if necessary (for example, defining short or long invoice types). Add an additional column for Supplier Name. Step 9: Rename and Publish the Invoice Extraction Agent Rename this agent to Invoice Extractor. Set the trigger conditions so that this agent activates only when the document category is identified as an invoice. Publish the extraction columns' outputs to display them on your dashboard. Step 10: Set Up Extraction for Purchase Orders Repeat the configuration steps for purchase orders: Create a branch that activates when the document category is Purchase Order. Integrate an agent to extract the Purchase Order Number and Supplier Name. Rename this agent to Purchase Order Extractor. Configure the inputs and trigger conditions appropriately and publish the agent's outputs as workflow results. Step 11: Display Extracted Data on Your Dashboard Once the extraction agents are configured and their outputs published, the new columns (such as invoice number, supplier name, purchase order number) will appear in the dashboard's table view. Step 12: Activate the Dashboard AI Employee After completing the workflow setup, ensure that the AI Employee is activated so end users can log in and view the dashboard with the extracted data. Multi-Line Extraction To extract multiple values for one or many columns (for example, item name, item quantity, item price), follow these steps during the column setup in the extraction agent configuration. Example: Extract supplier name, supplier address, item name, item quantity, and item price from a purchase order. For a given purchase order, some columns (item name, item quantity, item price) can have multiple values. Follow Steps 1 through 4 as described above. Locate the Entity Extraction with Documents agent and pass documents from the trigger. Enter the column name and description. Select group as the output format. On selection, sub-columns will appear. Select the multi value checkbox. Add sub-column names and descriptions. To add more sub-columns, select Add sub columns. Publish the outputs to display the new columns in the dashboard's table view. Next Steps Creating Dashboard Triggers -- Configure structured input fields for dashboard workflows. Publishing to Dashboard -- Publish agent outputs to the dashboard table view. Dashboard Features -- Explore the core capabilities of the Agentic Dashboard.

================================================================================
# Dashboard Features
URL: https://builder.ema.ai/builder-guides/dashboard/dashboard-features
================================================================================

Dashboard Features The Agentic Dashboard is Ema's AI-first interface for analyzing unstructured data through structured, repeatable workflows powered by multi-agent intelligence. It allows users to upload inputs (such as documents), run extraction and validation workflows, and view results in a tabular, editable format designed for scale and collaboration. Built for use cases like audits, claims processing, and contract compliance, the dashboard supports human-in-the-loop interventions, full source traceability, and integration with enterprise tools. Example Use Cases Contract Compliance -- Extract terms and validate against regulations. Claims Processing -- Check documents for missing information and rule alignment. Bid Evaluation -- Standardize RFP inputs and evaluate based on configured rules. Prior Authorization -- Extract policy rules, validate against patient records, and flag gaps to reduce delays and prevent denials. Core Capabilities Data Ingestion Supports multiple types of inputs (documents, text, fixed values, and more). Upload single or bulk files in various formats (PDF, DOCX, and others). Support for ingestion via APIs. Workflow Execution Run each row to trigger workflow execution. Run workflow for all rows to support bulk workflow execution. The output will appear on the dashboard in the configured columns on the GWE canvas. AI-Human Collaboration HITL support -- Humans can edit or approve the output on the dashboard. Ensure HITL is enabled for the agent from the GWE canvas. Full traceability -- Supports sources and reasoning for rule validation output on the dashboard. View the detailed validation report to access this information. Feedback support -- Supports feedback in rule validation reports. Confidence scores -- For agents with confidence scores enabled, the dashboard displays cells with high or low accuracy, which the user can edit. Data Operations Add or delete rows (bulk or single). Download structured outputs in CSV. Sort within the dashboard. Create filtered views of the main dashboard as sub-dashboards.

================================================================================
# Creating Dashboard Triggers
URL: https://builder.ema.ai/builder-guides/dashboard/dashboard-triggers
================================================================================

Creating Dashboard Triggers Dashboard triggers allow external systems or users to initiate GWE workflows directly from the Ema dashboard using structured, customizable input fields. Dashboard workflows can also be triggered via APIs. Key Features Multiple input types -- You can define Text, Number, Boolean, Enum (dropdowns), and Document inputs for each trigger, allowing rich data intake tailored to workflow needs. Custom names and descriptions -- You can assign custom names and descriptions to each input. Inputs tied to mandatory fields in the workflow are auto-marked as required, and additional fields can be marked manually to enforce data integrity. API invocation -- Triggers can be invoked via externally exposed APIs, enabling seamless integration with external apps or systems. Each API call creates or updates a dashboard row and returns all published inputs and outputs as part of the response. How to Set Up Step 1: Select the Template Select the GWE Dashboard Persona template and create an AI Employee. Step 2: Add Inputs in the Workflow Builder Go to the Workflow Builder and add inputs. Step 3: Configure Each Input Provide an input name and an input type. Hit Save. Supported input types include: Text Number Boolean Enum (dropdown with predefined values) Document Step 4: Build the Workflow Connect each input to the desired agent by building the workflow on the GWE canvas. Step 5: Use the Dashboard Go to Use AI Employee to land on the Dashboard. Add a row. For each row added, provide the inputs. Hit Save. Step 6: Run the Workflow You are all set. Run the workflow to process the inputs and generate outputs.

================================================================================
# Publishing to Dashboard
URL: https://builder.ema.ai/builder-guides/dashboard/publishing-to-dashboard
================================================================================

Publishing to Dashboard Any GWE agent can publish its output to the dashboard. Ensure that the GWE Dashboard Template is selected when creating the AI Employee. The output will be published in a tabular interface on the dashboard with columns configured in the respective agents on the GWE canvas. How to Publish to Dashboard Step 1: Select the Template Select the GWE Dashboard Persona template. Step 2: Create an AI Employee Create an AI Employee using the dashboard template. Step 3: Set Up the Workflow Set up the GWE workflow by connecting the dashboard trigger(s) to the respective agents' input fields. Step 4: Publish Agent Outputs For each agent, select Publish as workflow output. Based on the agent type, the output will appear on the dashboard when the workflow is run. The published outputs will appear as columns in the dashboard's table view, providing a structured, tabular interface for reviewing results.

================================================================================
# Document Generation
URL: https://builder.ema.ai/builder-guides/document/document-generation
================================================================================

Document Generation This guide explains how to set up a Document Generator AI Employee that uses GWE workflows to generate high-quality documents section by section, with collaboration, versioning, and governed downloads. You will learn how to configure the AI Employee, design the workflow, and hand off to end users who create documents with an outline and runtime inputs, then review, regenerate, and download from Doc Writer. Key Terms GWE (workflows and agents) -- Ema's workflow system where you connect agents (file search, web search, charting, research) and define triggers/inputs. In document generation, the workflow runs once per document section. Document instructions -- End-user guidance collected at creation, used for AI outline generation and applied to every section's content (topic, tone, format). Section instructions -- Per-section content guidance extracted from the file used to generate the outline. Outline -- List of section titles. Can be uploaded by the admin and enforced, or generated/uploaded by end users. Style guide -- Visual formatting (headers, footers, font sizes/colors) extracted and applied at download. Can be enforced by the admin or added by the end user. Config-time inputs -- Items provided during AI Employee configuration (admin-uploaded outline, style guide, data sources). Runtime inputs -- Default trigger inputs (Document Instructions, Section Title, Section Instructions) plus any builder-added fields that end users supply at creation, shared across all sections. Key Features Modular, section-level generation -- The workflow triggers for each section, letting you source content from files, the web, research agents, or charts as needed. This enables mixed strategies within the same document. Shared configuration with governance -- Admins can provide a default outline and style guide, enforce their use, configure EmaFusion™ models, enable copyright checking, and enable the AI Employee. End-user authoring in Doc Writer -- Users create documents, generate or modify content per section, leave comments, tag peers, provide feedback, view or restore versions, and download in DOCX or PDF. Runtime inputs at creation time -- Builders expose dynamic inputs in the workflow trigger; end users fill them during document creation (for example, competitor name or extra context files). Show Work from GWE -- Using a GWE workflow for section generation lets Doc Writer surface "Show Work" without re-building that capability. Multimodal responses -- You can upload images in DOCX, PDFs, HTMLs, or native image files, and they will be used as part of the responses based on relevance. You can also add or replace images inline on the Document Generator page. How to Use 1. Create the Document Generator AI Employee Go to AI Employees and click + New AI Employee. Choose Create a Custom AI Employee and select Document Generator. A new AI Employee is created and you are redirected to the workflow builder. This creates the AI Employee with a pre-built workflow that has a trigger and a Document Synthesis Agent (DSA). The inputs and outputs are already configured. If you want to rely completely on LLMs to generate content, you are all set. To improve focus: Update the search-and-respond instructions to fit your needs. Update the LLM and choose what works best for you. If you want content generation to be more nuanced (for example, needing file search or web search for different user queries), design the workflow by adding the right nodes. 2. Design the Workflow Understand the per-section trigger. The workflow runs once per section and includes default inputs: Document instructions, Section title, Section instructions. You can add more runtime inputs as needed. Add a categorizer. Use combinations of section title and instructions to choose paths (file search vs. web search vs. charting). Connect agents and author instructions. Wire up file search, web search, market research, and charting. Provide clear prompts to each node and ensure the categorizer selects the correct branch. Prepare data source folders. Create the folders you will bind later in configuration. Example workflow: Consider a scenario where a user is creating a comparison document with a competitor. Some sections about the user's company are generated using provided file sources. Sections about the competitor are generated using web search. A few sections need charts. The categorizer should route to the correct path based on section title and instructions. 3. Configure the AI Employee Data sources -- Link the folders created in the workflow's search nodes. The admin can update sources at any time. Style guide (optional or enforced) -- Upload a default style guide and optionally enforce its usage. Visual elements (headers, footers, font sizes/colors) apply at download. Outline (optional or enforced) -- Upload a default outline and optionally enforce its usage. If enforced, end-user options are disabled and a guidance banner appears. EmaFusion models -- Select models to be used in the AI Employee. Copyright checker -- Choose whether Ema-generated documents must pass a copyright check before download. Enable the AI Employee for usage. 4. Document Creation Step 1 -- Basic Details: Enter the document name and document instructions (global tone/format guidance). Step 2 -- Outline Setup: If not enforced by the admin, choose one of: Generate with AI from your document instructions Use admin-uploaded outline Upload a file to extract the outline Click Generate Outline and move to the next step. Step 3 -- Additional Details: Provide an optional style guide and any workflow dynamic inputs (fields originating from your GWE workflow trigger). Click Finish Setup. 5. Authoring and Collaboration in Doc Writer On the Doc Writer page, users can: View each section's content Regenerate a section by editing instructions View or restore versions Comment and tag teammates Provide feedback Download in DOCX or PDF (style guide formatting applied) Section generation uses the GWE path, including Show Work. Regeneration Regeneration allows you to refine or rewrite parts of your generated document without starting from scratch. Regenerate a Selected Portion Highlight a specific part of a generated section to regenerate only that portion. This is faster and avoids unintended updates to surrounding content. Regenerate Using Selected Files Open the file selector dropdown and choose files. The regenerated content will reference only those selected files. Use this when you need content based on a particular dataset. Regenerate with Web Search Include a phrase like "use web search to find..." in your regeneration query. Web search is used only when explicitly requested. Regenerate with Images Request images in your regeneration query (for example, "insert the product diagram here"). Images must exist within your uploaded documents. Images from web search are not supported for regeneration. Approving or Rejecting Changes Regenerated content does not apply automatically. After regeneration, review the updated text and click Approve to apply changes or Reject to discard them and regenerate again. Document Generation AI Employee as an Agent A Document Generation AI Employee can be embedded as an agent inside any GWE canvas, enabling it to both consume instructions from other agents and produce document outputs that flow downstream through the workflow. Enabling as an Embedded Agent Navigate to the Permissions tab of a configured DocGen AI Employee. Enable the toggle that allows this AI Employee to be embedded as an agent. Provide a clear description so other builders understand its purpose. Once enabled, the DocGen AI Employee appears in the AI Employees section of the agent list inside the GWE canvas. Input and Output Behavior The default input is document instructions, used to generate an initial outline and provide contextual guidance. The output is always a Document, which can be consumed by downstream agents or published as the final workflow output. Human-in-the-Loop (HITL) Flow DocGen AI Employees have HITL enabled by default. Once document generation begins: The workflow triggers HITL and routes the user to the doc-writer page. The user can regenerate sections, manage versions, and collaborate. After all sections are approved, control returns to the parent GWE workflow. Style Guide Notes Supported DOCX style guides are supported and applied during download. Common Google Docs and Microsoft fonts work reliably. Fonts are embedded in downloaded files. DOCX-to-PDF conversion preserves formatting via LibreOffice. Headers, footers, logos, page numbers, and basic graphics are preserved. Known Limitations PDF style guides are not supported. Only a fixed set of fonts is supported. Custom or rare fonts may fall back to defaults. Text alignment (center/right) defined in the style guide is currently ignored. Title styles are often treated as Heading 1. Avoid defining a separate "Title" style. Heading levels may shift in some cases. Practical Guidance Use DOCX style guides only. Prefer standard Google Docs or common Microsoft fonts. Expect high-quality but not pixel-perfect fidelity between the editor and the downloaded document.

================================================================================
# Creating a Conversational Email AI Employee
URL: https://builder.ema.ai/builder-guides/email/conversational-email
================================================================================

Creating a Conversational Email AI Employee Ema's Conversational Email AI Employee automatically monitors your email inbox, understands incoming messages, and sends intelligent, context-aware replies on your behalf. It transforms email handling from a manual process into an automated, always-on operation that responds in minutes instead of hours. The AI Employee reads each incoming email thread, summarizes the conversation, categorizes the request, and generates a personalized reply using your organization's knowledge base and configured workflows. It works directly within your existing Gmail or Outlook inbox, replying on the same thread so the experience is seamless for your customers. Key Features Automated email monitoring -- Connect your Gmail or Outlook inbox and select specific labels, inboxes, or folders to monitor. Ema continuously watches for new emails and processes them automatically with no manual triage required. Intelligent reply generation -- Each incoming email is analyzed through a configurable workflow that summarizes the conversation, categorizes the request, and generates a relevant, accurate reply using your organization's knowledge and policies. Same-thread replies -- Replies are sent directly on the original email thread, maintaining conversational continuity. Draft mode -- Choose to send replies automatically or save replies as drafts for human review before sending. Abstain when uncertain -- When the AI cannot confidently answer a question, it deliberately abstains rather than sending an incorrect response. Open tracking -- Optionally track when recipients open your replies. View open rates and engagement metrics from your dashboard. Internal email filtering -- Ema automatically detects and skips emails from your own organization's domain, preventing auto-reply loops. Continuous monitoring -- New replies from customers on previously answered threads are treated as new requests and answered individually. How to Use Step 1: Create Your AI Employee Click Create AI Employee and select the Conversational Email template. This creates a pre-configured AI Employee with essential workflow components already in place. Step 2: Build Your Workflow Customize the AI Employee's workflow to control how emails are processed and answered. A typical workflow includes: Email Trigger -- Receives incoming email content including subject, body, sender, and conversation history. Thread Summarizer -- Condenses the email thread into key points for context. Thread Categorizer -- Classifies the request type such as billing question, technical support, or general inquiry. Respond / Fixed Response -- Generates the reply using your knowledge base, policies, and configured response rules. You can add, remove, or reorder workflow steps to match your support process. Upload knowledge base documents, FAQs, and policy guides so the AI Employee can generate accurate, up-to-date responses. Key Workflow Settings SettingWhat It DoesAnswerThe reply text sent back to the customer. If the workflow cannot produce an answer, no reply is sent.AbstainWhen enabled, overrides the answer and deliberately sends no reply. Use this for escalation-required topics or sensitive cases.Make Response PublicControls whether the reply is sent as a real email or saved as a draft for review. Step 3: Connect an Email Inbox From your AI Employee settings: Click Connect Email and complete authentication with Gmail or Outlook. Select labels, inboxes, or folders to monitor. Only emails in selected locations will be processed. At least one must be selected. SettingDescriptionEmail ProviderGmail or OutlookLabels / Inbox / FoldersSelect which labels, inboxes, or folders Ema should monitor. At least one must be selected. Step 4: Enable Your AI Employee Set your AI Employee to Enabled. Ema begins monitoring selected labels, inboxes, or folders within approximately 60 seconds. New emails are processed automatically and replies are generated. What to Expect Replies typically appear within a few minutes of receiving an inbound email. Each new customer reply in a thread is treated as a new request and answered. Emails from your organization's domain are automatically skipped. If the AI cannot confidently produce an answer, no reply is sent and the email remains available for human follow-up. Example Use Cases ScenarioApproachExpected ResultsCustomer Support InboxMonitor support inbox, categorize requests, and auto-reply using FAQs and help documentationInstant responses to common questions, reducing response time from hours to minutesSales Inquiry HandlingMonitor sales inbox, identify inquiry type, and respond with product information and next stepsFaster lead engagement with consistent messagingIT Helpdesk EmailMonitor IT support emails, classify issues, and provide troubleshooting steps or escalation guidanceImmediate resolution for common IT issues, freeing helpdesk staff for complex casesHR Policy QuestionsMonitor HR inbox and answer employee policy questions from handbook documentationConsistent and accurate policy information delivered instantly Benefits Faster response times -- Reduce email response time from hours or days to minutes. 24/7 availability -- Monitor and respond around the clock across all time zones. Consistent quality -- Replies are generated from approved knowledge sources, ensuring accurate and on-brand communication. Human oversight -- Use draft mode to review replies before sending. Safe by default -- The AI abstains when uncertain to prevent incorrect responses. Seamless customer experience -- Replies stay within the same email thread for natural conversations. Engagement insights -- Track open rates and response engagement. Scalable operations -- Handle growing email volume without increasing support headcount proportionally. Easy integration -- Works directly within your existing Gmail or Outlook inbox. Requirements A Gmail or Outlook email inbox At least one label, inbox, or folder selected for monitoring Knowledge base documents, FAQs, or policy guides uploaded A workflow configured with an answer-producing action

================================================================================
# Example: Building an Employee Assistant
URL: https://builder.ema.ai/builder-guides/examples/employee-assistant
================================================================================

Example: Building an Employee Assistant This walkthrough builds a complete Employee Assistant AI Employee using Ema's Employee Experience Suite. The finished assistant handles greetings, answers personalized HR policy questions, and falls back to document search for general queries. What You Will Build A chatbot AI Employee that: Classifies incoming messages by intent (greetings versus policy questions) Summarizes conversation context for multi-turn interactions Extracts personalization tags (country, band) from the user profile Rewrites queries for optimal document retrieval Searches uploaded HR documents and returns cited answers Prerequisites Access to the GWE platform One or more HR policy documents (PDF, DOCX, or TXT) ready to upload Locate the Chatbot Template Tile Navigate to the GWE platform. Locate the tile labeled GWE Chatbot Persona. Click Create and save and assign a name to your assistant (for example, "Employee Assistant"). Access the Workflow Builder Click Go to Workflow builder on the confirmation screen. A Chat Trigger block is automatically present. This block handles all incoming user conversations. Step 1: Add a Categorize Conversations and Route Agent The Categorize Conversations and Route agent classifies incoming queries so the workflow can route them to the correct path. Add the Categorize Conversations and Route agent to the canvas. Connect the chat trigger's chat conversation output to the conversation input of the categorizer. Open the categorizer's configuration panel on the right. Click Add a Category and define the following intents: Greetings/Feature Inquiries -- example phrases: "Hi", "What can you do?", "Hello there!" Fallback (default category) -- catches any query that does not match a defined category. In this example, fallback handles general HR questions that require document lookup. Step 2: Maintain Context with a Conversation Summarizer The Conversation Summarizer condenses the chat history so downstream agents receive concise context instead of the full transcript. Add the Conversation Summarizer agent. Connect the chat trigger's chat conversation output to its conversation input. Set a Trigger When condition so this agent runs only when the Fallback category is active: Click the agent, select Add Trigger When, and choose the Fallback category from the categorizer. Step 3: Extract Personalization Tags The Tag Extractor pulls metadata such as country and band from the user's profile, enabling personalized responses. Add the Tag Extractor agent. Connect the chat trigger's chat conversation output to its conversation input. Step 4: Respond to Greetings Add a Respond to a Query agent to handle queries in the Greetings category. Connect the chat trigger's user query to this agent's query input. In the configuration panel, write instructions that provide a friendly introduction and list the assistant's capabilities. Rename the agent to something descriptive (for example, "Greetings Responder"). Set a Trigger When condition so this agent fires only for the Greetings/Feature Inquiries category. Step 5: Rewrite the Query for the Fallback Path A Query Rewriter reformulates the user's question using conversation context and personalization tags, producing a search-optimized query. Add a Respond to a Query agent and rename it Query Rewriter. Write instructions that tell the agent to act as a query rewriter -- combining the summarized conversation and user tags into a single, coherent search query. Connect the summarized conversation output from the Conversation Summarizer to the Query Rewriter's query input. Connect the user tags output from the Tag Extractor to its user tags input. Step 6: Perform Knowledge Search Using the Rewritten Query Add the Knowledge Search agent. Connect the query output from the Query Rewriter to the Knowledge Search agent's query input. Upload relevant HR documents: In the configuration panel, click Add Data Source. Select Upload Documents and upload your files (for example, leave policies, travel guidelines, performance processes). After upload, click Manage next to the document folder to add or remove documents and assign metadata tags for improved retrieval accuracy. Step 7: Respond Using Search Results Add a Respond to a Query agent. Connect: Query from the Query Rewriter User Tags from the Tag Extractor Search Results from the Knowledge Search agent Write instructions that define the assistant's tone and formatting. For example: "You are a helpful and professional HR assistant. Use a conversational tone. Format the response with clear bullet points when listing policies or steps." Step 8: Publish Workflow Outputs Publish the final outputs so they appear in the chatbot's response interface: Select the Greetings Responder agent and enable Publish this as a workflow output. Select the Respond to a Query agent (from Step 7) and enable Publish this as a workflow output. The correct output is rendered to the end user based on which intent path the query follows. Step 9: Save and Activate Review all connections and agent configurations. Click Save Changes in the workflow builder. Activate the AI Employee for testing. Step 10: Customize the Assistant Identity On the Configuration Page, personalize your AI Employee: Assistant Name -- click the name field to rename (for example, "HR Buddy" or "AskEma"). Icon -- click the avatar to upload a custom icon. Welcome Message -- edit the message first-time users see (for example, "Hi! I'm here to help with your HR questions."). Conversation Starter Buttons -- add buttons that appear alongside the welcome message to simplify common queries. Step 11: Test Your Employee Assistant Click the chat icon at the bottom-right of the screen to open the preview window. Try different queries to verify: The categorizer routes greetings and policy questions correctly. Search results are accurate and well-formatted. Personalization tags influence the response when expected. Iterate on agent instructions as needed before going live. Next Steps Writing Effective Instructions -- refine your agent prompts for better output quality. Adding Workflow Branches -- add more intent categories beyond greetings and fallback. Improving Chat Performance -- optimize response quality with conversation summarizers and static responses.

================================================================================
# Example: Building a Resume Ranker
URL: https://builder.ema.ai/builder-guides/examples/resume-ranker
================================================================================

Example: Building a Resume Ranker This walkthrough builds a Dashboard AI Employee that accepts job descriptions, matches them against a repository of candidate resumes, and produces scored, ranked candidate recommendations. What You Will Build A dashboard-based AI Employee that: Accepts a job description document as input Extracts required skills, qualifications, and experience from the job description Searches a repository of candidate resumes for matches Scores and ranks each candidate against the job requirements Outputs the top candidates with detailed justifications Prerequisites Access to the GWE platform One or more candidate resume files (PDF, DOCX, or TXT) A job description document for testing Create a New AI Employee Navigate to the GWE platform. Scroll to the bottom of the AI Employees page and locate the template for GWE Dashboard Persona. Click Create, fill in the AI Employee details, and click Create & Save. Click Go to Workflow Builder to start building. Create the GWE Workflow Add Entity Extraction for Job Description Analysis Add an Entity Extraction with Documents agent. This agent extracts the skills and experience required by the job description. Add Extraction rules that define what to pull from each job description. For example, create a rule to extract the number of years of experience required, mandatory skills, preferred skills, and education qualifications. Convert Extracted Data to a Search Query Add a Generate Query from Agent Outputs agent. Connect the output from the Entity Extraction agent to this agent's input. This agent converts the structured extraction output into a format that downstream agents can query against. Build the Search Query Add a Respond to a Query agent and rename it (for example, "Query Builder"). Connect the extraction output to this agent's input. Write instructions that convert the extracted skill metadata into a natural-language search query. Example instructions: "You are an expert query writer for a file search agent. Convert the given list of skills, qualifications, and experience into a clear natural-language query to find the best matching candidates. Include all provided skills, qualifications, and experience. Be specific and do not generalize. Keep the query under 40 words." Search Candidate Resumes Add a Knowledge Search agent. Connect the query output from the previous agent to the Knowledge Search agent's query input. Upload your repository of candidate resumes: In the configuration panel, click Add Data Source. Select Upload Documents and upload your resume files. Score and Rank Candidates Add a Respond to a Query agent. Connect: The search results from the Knowledge Search agent The query from the Query Builder agent Write detailed scoring instructions. The instructions should define: Scoring criteria -- evaluate each candidate across four parameters (key matching skills, required qualifications, preferred qualifications, certifications and training) on a 0-to-5 scale. Scoring rubric -- define what each score range means (0-1 Unsuitable, 1-2 Below Average, 2-3 Average, 3-4 Good, 4-5 Excellent). Output format -- for each candidate, provide the candidate name, overall match score, individual parameter scores, and a brief justification. Enforcement rules -- do not infer missing details, do not inflate scores, sort by overall match score in descending order. Extract Top Candidates for Dashboard Output Add another Entity Extraction with Documents agent at the end of the workflow. This agent extracts the top candidate name and justification from the scoring output. Enable Publish this as a workflow output so the extraction results appear in the dashboard table. Test the Workflow Click Add in the top-right corner of the dashboard, then select Add single row. To process multiple job descriptions at once, select Add multiple rows instead. Click Add File to upload a job description document. Supported formats include DOCX, PDF, and TXT. Click the play icon to trigger the workflow execution. Processing may take a few seconds. Review the ranked candidate list and explanations in the dashboard output. Next Steps Creating a Dashboard-Based AI Employee -- learn more about dashboard AI Employee fundamentals. Dashboard Triggers -- configure structured input fields for your dashboard. Dashboard Features -- explore bulk operations, HITL review, and data export. Writing Effective Instructions -- refine scoring instructions for more accurate candidate evaluations.

================================================================================
# Example: Building a Sales Intelligence Assistant
URL: https://builder.ema.ai/builder-guides/examples/sales-intelligence
================================================================================

Example: Building a Sales Intelligence Assistant This walkthrough builds a Sales Intelligence AI Employee that accepts a company name and produces a detailed market intelligence report as a downloadable document. What You Will Build A chatbot AI Employee that: Takes a company name as input Searches the web for market intelligence on that company Synthesizes search results into a structured report Generates a downloadable document containing the report Prerequisites Access to the GWE platform Create the AI Employee Navigate to the GWE platform. Locate the tile labeled GWE Chatbot Persona. Click Create and save and assign a name (for example, "Sales Intel Assistant"). Access the Workflow Builder Click Go to Workflow builder on the confirmation screen. A Chat Trigger block is automatically present. This block handles all incoming user conversations. Step 1: Rewrite the User Query for Web Search Add a Respond to a Query agent to the canvas. Connect the chat trigger's user query to this agent's query input. Write instructions that tell the agent to convert the company name into an effective web search query. For example: "Given a company name, generate a search query that will return recent market intelligence, financials, competitive landscape, and news about the company." Step 2: Add the Deep Web Search Agent Add the Deep Web Search agent. Connect the response output from the Respond to a Query agent (Step 1) to the Deep Web Search agent's query input. The Deep Web Search agent executes a live web search and returns relevant results. Step 3: Consolidate Search Results Add a Respond to a Query agent. Connect the Deep Web Search agent's output to this agent's input. This agent formats and consolidates the raw search results into structured content that downstream agents can use. Step 4: Generate the Market Intelligence Report Add another Respond to a Query agent. Connect the output from the previous agent to this agent's query input. Write instructions that tell the agent to produce a comprehensive market intelligence document. For example: "Using the provided search results, write a detailed market intelligence report covering company overview, recent news, financial highlights, competitive landscape, and strategic outlook. Use clear section headings and bullet points." Step 5: Generate a Downloadable Document Add a Publish Document agent. Connect the response output from Step 4 to the Publish Document agent's input. Configure the document name (for example, use the company name as the file title). The Publish Document agent converts the text response into a downloadable document file. Test the Workflow Click Use AI Employee in the top-right corner of the workflow builder. This redirects you to a chat window. Enter a company name (for example, "Salesforce" or "Stripe"). The workflow will execute all steps and produce a downloadable market intelligence document. Next Steps Document Generation -- learn more about configuring the Document Generator agent and using style guides. Writing Effective Instructions -- improve the quality of generated reports by refining agent instructions. Creating AI Employee Templates -- package this workflow as a reusable template for your team.

================================================================================
# Audit Tab in Voice AI Employee
URL: https://builder.ema.ai/builder-guides/voice/audit-tab
================================================================================

Audit Tab in Voice AI Employee The Audit tab provides a complete, searchable history of every call handled by a Voice AI Employee. Use it to review call transcripts and listen to audio recordings. Where to Find It Open any Voice AI Employee from the AI Employees page, then click the Audit tab at the top of the AI Employee page. What the Audit Tab Shows The Audit tab is a table of every call handled by the AI Employee. Each row represents a single call and includes: ColumnDescriptionPhone numberThe caller's phone number (or SIP identifier).Start timeWhen the call was initiated.DurationTotal call length.Disconnection reasonHow the call ended (caller hangup, AI hangup, transferred, error, etc.).TransferredWhether the call was forwarded to a human agent and, if so, the destination label.Call IDUnique identifier for the call, useful for correlating with logs and support tickets. Inspecting a Call Click any row to open the call detail drawer. The drawer shows: Full transcript -- Turn-by-turn conversation between the caller and the AI Employee, with timestamps. Audio playback -- Listen to the original recording.

================================================================================
# Call Forwarding
URL: https://builder.ema.ai/builder-guides/voice/call-forwarding
================================================================================

Call Forwarding Call Forwarding (also called Dynamic Call Forwarding) lets a Voice AI Employee transfer an in-progress call to a human agent or another destination. Forwarding is workflow-driven -- the AI Employee decides when and where to transfer based on the logic you build in GWE, instead of using static per-number routing. How It Works You define a set of destinations in Voice Settings > Call Forwarding, each with a label (for example, HR, Sales, Customer Support) and a phone number. In the workflow, a Fixed Response Agent at the end of a branch emits a message like Transfer the call to {destination.label}. At runtime, the Voice AI Employee matches the destination label in the response to the configured number and transfers the call. How to Configure 1. Add Call Forwarding Numbers In the Voice AI Employee, go to Configurations > Voice Settings > Call Forwarding widget and add the destination label and phone numbers that calls can be transferred to. 2. Configure Call Forwarding in the Workflow In the workflow, add a Fixed Response Agent with a response template: Transfer the call to {destination.label}. Examples: "Transfer the call to HR" "Transfer the call to Customer Support" "Transfer the call to Sales" Quick Example chat_trigger -> categorizer -> [hr] -> fixed_response("Transfer the call to HR") -> [sales] -> fixed_response("Transfer the call to Sales") -> [self_serve] -> knowledge_search -> respond Only branches that should transfer emit a transfer message; other branches respond directly. Best Practices Do Always ensure the workflow publishes output from only one agent in a workflow run. Always place the Fixed Response Agent at the end of a branch so no other agent overrides the transfer instruction. Use clear and consistent destination labels that exactly match the labels configured in Voice Settings. Use other agents (Categorizer, Knowledge Search, Intelligent Actions, etc.) before the Fixed Response Agent to route calls based on category, search results, or intelligent action outputs. Do Not Do not add multiple Fixed Response Agents in the same branch. Do not use a single Fixed Response Agent to forward calls to multiple destinations. Do not use phone numbers in fixed responses; always use configured destination labels.

================================================================================
# Creating a Voice AI Employee
URL: https://builder.ema.ai/builder-guides/voice/creating-voice-ai-employee
================================================================================

Creating a Voice AI Employee This guide explains how to set up a Voice AI Employee -- an AI Employee that communicates naturally, supports multiple languages, executes complex actions, and intelligently transfers calls to human agents for escalation or handoff. Key Capabilities Multilingual conversations -- Supports 30+ languages, enabling seamless switching between languages without losing context. Low latency -- Built to deliver real-time, natural speech interactions without delay. Natural voice -- Ema's voice library includes empathetic, warm, and human-like tones designed for clarity and emotionally intelligent responses. Complex action handling -- Your Voice AI Employee can perform complex actions end to end, from deep knowledge search to creating ServiceNow tickets or sending emails. Security and compliance -- Includes data masking and data protection options for transcripts, audio, and agent data. You can choose whether to store call data or disable it entirely. Call forwarding -- Transfer calls to a specified human agent for escalation or handoff. Setting Up Your Voice AI Employee Step 1: Start from the Voice AI Employee Starter Template Select the Voice AI Employee Starter Template from the templates. This template provides sample instructions in the configuration page and an empty workflow to set up your AI Employee. Step 2: Configure Your Voice AI Employee Voice Settings Choose a voice that fits your brand or use case from Ema's voice library. Conversational Behaviors Configure the following sections to define how your Voice AI Employee communicates: How should the call start? -- Set a short, friendly opening line that plays when the caller connects. By default the greeting is non-interruptible; use the Allow callers to interrupt the greeting checkbox next to the field if you want callers in a hurry to be able to speak over it. Best practices for the opening greeting: Identify the organization Introduce the assistant Ask how you can help Keep the greeting short Example: "Hello, you've reached HR Services at [company name]. I am [voice_name], your virtual HR assistant." Define your AI Employee's identity and purpose -- Describe how the AI behaves throughout the conversation. You should define: Who the Voice AI represents (identity) Its responsibilities (role) Communication style (guiding principles) Conversation structure (conversation flow) Specific pronunciation rules (language handling) If you prefer to start from a draft, click Generate in the top-right of the field. Ema prompts you for a couple of lines describing what the Voice AI Employee should do and uses that to produce a starting identity and purpose that you can refine. A recommended structure for this section: ## Identity You are Ema, the HR virtual assistant for XYZ Corporation. ## Role Assist employees with HR-related questions such as benefits, payroll, leave balances, and employee verification. ## Guiding Principles Communicate clearly and professionally. Be friendly and patient. Ask clarifying questions when requests are unclear. ## Language Handling Always respond in the caller's language. If the caller switches languages, continue in that language. ## Conversation Flow 1. Greet the employee 2. Identify the request 3. Verify the employee if required 4. Perform the requested action 5. Confirm resolution 6. Escalate if necessary Define what actions your AI Employee can perform -- List the actions available to the Voice AI Employee. Actions typically correspond to the capabilities inside the workflow -- primarily the intents it can handle. Each action should describe the scenario, when the action should trigger, and the expected outcome. Click Generate in the top-right of the field to have Ema inspect the current workflow and draft the action list from the intents and tools it finds. Review the generated entries and edit them to match your exact triggers and parameters. Example: Case 1: Employee Identification Trigger When: The caller provides their Employee ID. Instruction: "Intent" for the tool call: "Employee Identification" Required parameters: { "emp_id": "" } Case 2: Create a Case Trigger When: The caller says they want to create a case. Instruction: "Intent" for the tool call: "Create a case" Required parameters: { "inquiry": "" } When should the call end? -- Define when the AI Employee should hang up, such as after confirming task completion, user satisfaction, or a polite goodbye. Advanced Settings Data storage settings -- Manage how transcripts and audio recordings are stored. You can enable or disable storage based on compliance or project needs. Voice activity detection settings -- Configure detection settings to control when the AI Employee listens and responds during a call. Enable Bias caller transcription to primary language here to improve speech-to-text accuracy when most callers speak the AI Employee's primary language; leave it off for deployments where callers regularly speak other languages. Call forwarding settings -- Set up call forwarding to a human number for escalation. AI Employee Settings These function the same way as any other AI Employee, allowing you to add data sources, select the EmaFusion™ models, and more. Phone Number Settings Connect a phone number only if you want to enable real inbound calling for this AI Employee. Only a limited set of numbers are currently available. For assistance, contact your Ema representative. Step 3: Build the Workflow This functions the same way as any other AI Employee. Refer to Creating Your First Workflow for guidance. Step 4: Test the Voice AI Employee Enable your AI Employee. Click Test Voice AI Employee to simulate a phone call. View real-time call transcriptions.

================================================================================
# Metrics Tab in Voice AI Employee
URL: https://builder.ema.ai/builder-guides/voice/metrics-tab
================================================================================

Metrics Tab in Voice AI Employee The Metrics tab surfaces aggregate KPIs for a Voice AI Employee so you can monitor usage, deflection, and call quality over time. All metrics update as new calls are handled and support the same date range filters as the Audit tab. Summary Metrics The top of the Metrics tab shows headline numbers for the selected date range: MetricDescriptionTotal callsTotal number of calls received.Unique callersTotal number of distinct callers.Avg call duration (mins)Average duration of calls.Total call duration (hrs)Total cumulative call duration.Deflection ratePercentage of calls that were not transferred to a human agent. Trend Charts Below the summary, the Metrics tab renders time-series charts so you can see how your Voice AI Employee is performing over the selected range: ChartDescriptionTotal calls over timeNumber of calls over time.Unique callers over timeNumber of distinct callers over time.Avg call duration over time (mins)Trend of average call duration over time.Deflection rate over timeTrend of deflection rate over time.Distribution of disconnection reasonsBreakdown of reasons for calls being disconnected. Filters Date range -- Presets (last 24 hours, 7 days, 30 days) and a custom range selector apply to every metric and chart on the page. Metrics are computed only from calls placed to a connected phone number. Test calls initiated from the Builder UI are not included in any of the totals or charts above.

================================================================================
# Agent Reference
URL: https://builder.ema.ai/agent-reference
================================================================================

Agent Reference Agents are the building blocks of every Ema workflow. Each agent performs a specific task -- searching knowledge bases, generating responses, classifying input, calling external tools, or validating results. You compose agents into workflows by connecting their inputs and outputs on the Generative Workflow Engine (GWE) canvas. This reference catalogs every agent available on the Ema Builder Platform, organized by function. Agent Categories CategoryDescriptionExample AgentsSearch & RetrievalFind information from knowledge bases, the web, or connected applicationsKnowledge Search, Agentic Search and Respond, Deep Web Search, Document SynthesisResponse GenerationProduce text responses grounded in context, search results, or templatesRespond to a Query, Respond using Search Results, Fixed Response, Custom AgentClassification & RoutingCategorize inputs and route workflows based on contentCategorizer, Categorize Conversations and Route, Thread CategorizerData ProcessingTransform, extract, and combine data between workflow stepsConvert to Text, Combine Text, Combine Search Results, JSON Extractor, Extract Entities, Custom Code AgentDocument GenerationCreate formatted documents, charts, and reportsGenerate Document, Chart BuilderExternal IntegrationExecute actions in third-party applicationsIntelligent Actions, App Navigator, Send Email, Sales IntelligenceValidation & QACheck outputs against rules, quality criteria, or business logicResponse Validator, Rule Validation, Abstain from AnsweringHuman CollaborationInvolve human reviewers in the workflowHuman CollaborationSentiment & FeedbackAnalyze tone, sentiment, and feedback signalsSentiment Analyzer, Feedback Sentiment Analyzer Choosing the Right Categorizer The platform offers several classification agents. Use this guide to pick the right one: AgentBest forInput typeKey featureStatusCategorizerMost new workflowsAny (via named inputs)Flexible multi-input classification with rulesCurrentCategorize Conversations and RouteChat-based AI EmployeesChat conversationMulti-intent detection, human collaboration (ask user to pick), example query matchingCurrentThread CategorizerTicketing workflowsSupport ticket threadReads ticket title, description, and recent commentsCurrentText CategorizerSimple text classificationPlain textStreamlined, text-onlyDeprecated (use Categorizer)Document CategorizerDocument classificationDocumentsDocument-only classificationDeprecated (use Categorizer) Rules of thumb: If your input is a chat conversation and you need intent routing, use Categorize Conversations and Route. It supports multi-intent detection and can ask the end user to choose when ambiguous. If your input is a support ticket, use Thread Categorizer. It understands ticket structure (title, description, comments). For everything else -- documents, emails, extracted data, plain text, or any combination -- use the Categorizer. Core Agents Core agents are general-purpose building blocks that apply across industries and use cases. Every Ema workspace has access to all core agents. AgentCategoryDescriptionAbstain from AnsweringValidation & QAStops a workflow branch from producing a response when the AI Employee should not answerAgentic Search and RespondSearch & RetrievalIterative research agent that plans searches, discovers file metadata, and synthesizes answers with citationsApp NavigatorExternal IntegrationBrowser automation agent that navigates web applications and performs UI-level actionsCategorize Conversations and RouteClassification & RoutingClassifies chat conversations into categories and routes to the appropriate workflow branch. Supports multi-intent detection and human collaboration.CategorizerClassification & RoutingFlexible categorization of any input type using named inputs, deterministic rules, and LLM classification. Recommended for most new workflows.Chart BuilderDocument GenerationGenerates charts and visualizations from tabular markdown dataCombine Search ResultsData ProcessingMerges and deduplicates search results from multiple sources with configurable weightingCombine TextData ProcessingMerges multiple text inputs using LLM summarization or simple append modeConversation SummarizerData ProcessingConverts multi-turn chat conversations into concise search queries. Supports both simple concatenation and LLM-powered summarization.Convert to TextData ProcessingDeterministic conversion of any well-known type to plain textCustom AgentResponse GenerationGeneral-purpose LLM agent with configurable inputs, outputs, and instructionsCustom Code AgentData ProcessingExecutes custom JavaScript in a sandboxed environment for data transformation, conditional logic, and LLM callsDeep Web SearchSearch & RetrievalMulti-strategy web search with AI-powered result synthesisDocument CategorizerClassification & RoutingDeprecated. Categorizes documents into predefined categories. Use the Categorizer with document named inputs instead.Document SynthesisSearch & RetrievalAgentic document search with image and table supportExtract EntitiesData ProcessingSchema-driven entity extraction from documents and textFeedback Sentiment AnalyzerSentiment & FeedbackClassifies feedback as positive, negative, or no feedback detectedFixed ResponseResponse GenerationTemplate-based responses with variable substitution from workflow dataGenerate DocumentDocument GenerationCreates formatted .docx documents from markdown with style guide supportHuman CollaborationHuman CollaborationRoutes decisions to human reviewers with conversational, standard form, or custom form modesIntelligent ActionsExternal IntegrationExecutes actions across 200+ connected applications via tool callingJSON ExtractorData ProcessingExtracts values from nested JSON structures into flat key-value pairsKnowledge SearchSearch & RetrievalSearches document knowledge bases using semantic retrieval with configurable data sourcesMark as Public ResponseValidation & QASets a boolean flag indicating whether a response should be publicly visible on ticketsRerank Search ResultsSearch & RetrievalLLM-based reranking of combined search results for improved relevanceRespond to a QueryResponse GenerationGeneral-purpose response generation from any combination of inputsRespond using Action Calling ResultsResponse GenerationFormats and narrates the outputs of external tool executionsRespond using Search ResultsResponse GenerationGenerates responses grounded in search results with source citationsResponse ValidatorValidation & QAValidates generated responses against configurable quality and compliance criteriaRule ValidationValidation & QAValidates documents or data against a defined rule set with pass/fail outputSales IntelligenceExternal IntegrationRetrieves financial and company data from external APIsSend EmailExternal IntegrationSends emails with attachment support, CC/BCC, HTML formatting, and read trackingSentiment AnalyzerSentiment & FeedbackDetailed sentiment classification with nuance and sub-category detectionTag ExtractorData ProcessingExtracts tags from conversations using configurable mapping rulesText CategorizerClassification & RoutingDeprecated. AI-powered text classification. Use the Categorizer for new workflows.Thread CategorizerClassification & RoutingCategorizes support ticket threads based on title, description, and recent commentsThread SummarizerData ProcessingSummarizes support ticket threads into concise overviews covering issue, actions taken, and status Specialized Agents Specialized agents are pre-trained for specific industry or domain tasks. They encapsulate domain expertise and are typically used as drop-in replacements for the Custom Agent when a particular use case is well-defined. See the Specialized Agents Catalog for the full list. Deprecated Agents Some agents have been superseded by newer implementations. See Deprecated Agents for the list and migration guidance. For internal implementation details (action registration, knowledge layer, skill bundles, and agent QA pipeline), see the internal agent reference supplement.

================================================================================
# Abstain from Answering Agent
URL: https://builder.ema.ai/agent-reference/core/abstain-from-answering
================================================================================

Abstain from Answering Agent The Abstain from Answering agent stops Ema from producing a response on a particular workflow branch and returns a short justification. Use it when the AI Employee should explicitly decline to answer -- for example, when a query is off-topic, when search results are insufficient, or when a policy prohibits responding. Use Cases Route sensitive or regulated topics (legal, HR, compliance) away from AI-generated responses. Defer to a human agent when escalation criteria are met. Suppress replies for out-of-scope, duplicate, or spam tickets. Hold responses during incident management or maintenance windows. Inputs InputTypeRequiredDescriptionabstain_reasonStringNoSpecify the reason for Ema to abstain (e.g., sensitive issues). Outputs OutputTypeDescriptionabstain_reasonStringIf abstain_reason is provided, returns "Abstained because - {reason}". If omitted, returns "Abstaining from responding". Configurations None. How to Use This Agent In a support workflow, route off-topic queries to Abstain from Answering instead of generating a response: chat_trigger -> categorizer -> [off_topic branch] -> abstain_from_answering -> workflow_output -> [on_topic branch] -> search -> respond -> workflow_output Related Agents Response Validator -- validates responses against quality criteria; use upstream to decide whether to abstain. Categorizer -- classifies input so you can route to the abstain branch.

================================================================================
# Agentic Search and Respond
URL: https://builder.ema.ai/agent-reference/core/agentic-search-and-respond
================================================================================

Agentic Search and Respond The Agentic Search and Respond agent is an intelligent research assistant that plans and executes multi-step searches, discovers file metadata, performs web searches when needed, and synthesizes a comprehensive answer with citations. Unlike the simpler search-then-respond pattern, this agent iterates: it evaluates intermediate results and decides whether to search again, refine the query, or switch data sources. Use Cases Use CaseExampleMulti-source Q&A"What do our documents say about X, and how has our approach changed over the last two quarters?" The agent searches across multiple files, connects findings, and delivers one unified answer.Research with corroboration"Summarize the key themes across these reports and highlight where they agree or conflict." The agent performs multiple rounds of search and cross-references results.Document + web questions"What does our internal policy say about X, and how does it compare to the latest external guidance?" Searches internal files first, then supplements with web results.Web-only research"What are the latest developments in X?" Operates without internal documents, performing iterative web searches to gather and synthesize information. How is this different from Document Synthesis? Document Synthesis is designed to generate content (drafting, reports, summaries). Agentic Search and Respond is built for answering questions and retrieving information. Use this agent when you need answers; use Document Synthesis when you need to create something. Agent Capabilities The agent has access to the following tools during execution: 1. Discover File Metadata Retrieves a complete list of all uploaded files organized by folder, including associated tags. Helps the agent understand what documents are available before searching. 2. Search Files Searches uploaded documents using intelligent, meaning-based (semantic) search. The agent uses this tool multiple times with different queries to gather comprehensive information. ParameterDescriptionQuerySearch question in plain languageMax ResultsNumber of results to return (default: 10)File Names(Optional) Limit search to specific filesTags(Optional) Filter by document tagsFolders(Optional) Search only within certain folders 3. Web Search Searches the internet for current information not available in uploaded documents. Limited to 2 web searches per iteration. Only available when web search is enabled. ParameterDescriptionQueryWhat to search for on the webMax SourcesNumber of web sources to retrieve (recommended: 3 or fewer)Past Days Range(Optional) Limit results to recent content 4. Ask User Question Pauses the workflow to ask the user a clarifying question, then resumes once the user replies. Only available when Enable Clarifying Questions is on. 5. Final Response Generates the final answer after gathering all necessary information, combining all retrieved content into a single response with source citations. Inputs InputTypeRequiredDescriptionTaskText with SourcesYesThe question or task that drives the research process. Connect to user input, a previous agent's output, or a workflow variable.Additional ContextAny (array)NoExtra information alongside the question, such as outputs from previous workflow steps or reference data.Data SourcesDatastoreConnection (array)NoFolders the agent can search. Only files within linked folders are accessible. Either data sources or web search (or both) must be provided. The agent requires at least one source of information to operate. Top-level folders must have distinct names. If multiple data sources share the same folder name, the agent may not distinguish between them. Outputs OutputTypeDescriptionResponseText with SourcesThe synthesized response with inline citations and source references. Configurations ParameterDescriptionDefaultResponse InstructionsInstructions that guide how the agent generates its final answer, including formatting preferences, protocols, or rules.None (sensible defaults)Search InstructionsInstructions that guide how the agent searches, including strategy, order of steps, or constraints. You can reference file names, folders, and tags.None (auto-determined)Enable Web SearchWhether the agent can search the internet for information beyond uploaded documents.Off Advanced Settings ParameterDescriptionDefaultReasoning LevelDepth of model reasoning: None, Low, Medium, High, or Default. Higher levels improve answer quality but increase latency.DefaultMaximum IterationsMaximum research iterations before the agent must deliver its answer. The agent finishes early if it gathers enough information.10Number of Search ResultsMaximum results returned per file search call. When unset, the agent decides how many results to retrieve per search.UnsetNumber of Surrounding ChunksNumber of previous and next chunks retrieved alongside each search result for additional context.1Enable Clarifying QuestionsWhen on, the agent can pause to ask the user a clarifying question before responding. The workflow resumes once the user replies.Off Latency considerations: Higher reasoning levels, more iterations, more search results, and more surrounding chunks all increase processing time. For time-sensitive workflows, use Low reasoning and keep defaults. Reserve High reasoning for complex questions where answer quality justifies the extra time. How to Use This Agent For a policy research AI Employee that answers complex compliance questions: chat_trigger -> agentic_search_and_respond -> workflow_output The agent will: Analyze the question and plan an initial search strategy. Execute searches against configured knowledge bases. Evaluate results. If insufficient, refine the query and search again. Optionally search the web for supplemental information. Synthesize a final answer with citations to source documents. Viewing Work Logs After the agent completes its task, you can review its work in the Work Log tab. Steps are organized by iteration and include: Named input validation: validates provided inputs Processing named inputs: prepares named inputs for the agent, including converting search results to documents when needed Iteration N: Asking EmaFusion™ to select a tool: shows agent reasoning and tool selection Iteration N: Tool call X: shows each tool execution (Discover File Metadata, Search Files, Deep Web Search, Ask User Question) Iteration N: Re-requesting tool call: shown when the agent responded without selecting a tool and is prompted to try again Iteration N: Reached max iteration: shown when the iteration limit is hit and the agent is asked to deliver its final answer Generating final response: compiles the final answer with source citations Related Agents Knowledge Search: simpler single-pass search; use when questions are straightforward. Deep Web Search: dedicated web search; the agentic agent can invoke this internally. Respond using Search Results: generates a response from pre-fetched results; use in non-agentic workflows. Document Synthesis: for content generation from documents rather than question-answering.

================================================================================
# App Navigator Agent
URL: https://builder.ema.ai/agent-reference/core/app-navigator
================================================================================

App Navigator Agent The App Navigator agent enables AI Employees to interact with web applications through automated browser control, allowing them to complete complex workflows across any web-based system without requiring API integrations. Use Cases You need to automate a workflow in a web application that does not offer an API (e.g., SAP, Workday, ServiceNow, Oracle, NetSuite, or internal tools). You want browser-based form filling, navigation, or data extraction as part of a larger GWE workflow. You need auditable, recorded browser sessions for compliance. Inputs InputTypeRequiredDescriptionqueryTextNoThe user's request that triggered this browser automation.instructionsStringNoAdditional instructions that apply across all tasks in this run.named_inputsAny[]NoData to pass to the browser automation agent -- employee IDs, project codes, form values, or any other data the automation needs. Outputs OutputTypeDescriptionresultTextThe automation result, including structured data extracted from the web application. Tool Configuration The App Navigator requires at least one navigation tool to be configured before it can run. Each tool defines a named automation task with one or more steps. FieldRequiredDescriptionnameYesThe name of the navigation tool (typically the target application name, e.g., "ServiceNow").stepsYesA list of steps. Each step has a title (required) and optional instructions describing what the agent should do at that step.hitl_enabledNoWhether Human-in-the-Loop is enabled for this tool. Default: true.max_wait_time_hoursNoMaximum time (in hours) to wait for a human to intervene before timing out. Default: 3. Without a configured tool, the App Navigator will not run. The workflow will be marked as not runnable and the agent will have no tools available at runtime. Note: The App Navigator uses its own tool configuration system, which is separate from the External Tool Caller's tool configuration. Do not use configure_external_tools for App Navigator nodes. Features Browser-based automation -- behaves like a skilled user (clicking, typing, navigating, filling forms) to complete workflows directly in web apps. Intelligent navigation -- uses an application-level map and reasoning over the live page rather than fixed scripts or hard-coded selectors. Stable across minor UI changes, though major UI redesigns, MFA flows, CAPTCHAs, or heavy async rendering may require tool reconfiguration. Human-in-the-loop support -- teams can pause, take over, and resume at any step. Secure, isolated execution -- runs in sandboxed, isolated browser sessions. Auditability -- every action is logged with session recordings available for review, QA, and compliance. Scalable infrastructure -- can spin up hundreds of parallel browser sessions for enterprise workloads. Supported AI Employee Types Currently available on Dashboard and Conversational (Chat) AI Employees. Video Tutorials Dashboard setup -- https://app.trupeer.ai/view/M2lZbdwDT Chat setup -- https://app.trupeer.ai/view/0v4oCqbGl Related Agents External Tool Caller -- for API-based integrations when the target system has an API. Uses a different tool configuration system.

================================================================================
# Categorize Conversations and Route Agent
URL: https://builder.ema.ai/agent-reference/core/categorize-conversations-and-route
================================================================================

Categorize Conversations and Route Agent The Categorize Conversations and Route agent classifies incoming chat conversations into user-defined categories and routes the workflow down the corresponding branch. It combines deterministic rule-based filtering with LLM classification for flexibility and accuracy. Formerly known as the Intent Classifier. Use Cases A chat-based AI Employee needs to handle multiple types of requests (e.g., billing questions, technical support, general inquiries). You want to route conversations to different workflow branches based on intent. You need both deterministic keyword matching and LLM-based classification. You want to let the end user choose when a message could match multiple categories. Inputs InputTypeDescriptionchat_conversationConversationThe chat conversation to classify. The agent considers the most recent messages (see context window below). Outputs OutputTypeDescriptioncategoryCategoryThe assigned category name. Each category becomes a named output edge on the GWE canvas, enabling direct branching. Configurations ParameterDescriptionDefaultCategoriesList of category definitions. Each category has a name, description (up to 1,000 characters), and optional example queries and qualification criteria.RequiredFallback categoryCategory assigned when no rule matches and the LLM cannot confidently classify the message. Defaults to "Fallback" and cannot be changed once set."Fallback"Context windowNumber of recent messages the agent considers when classifying. Older messages are ignored.10Human collaborationWhen enabled, if the agent detects multiple matching categories, it presents the end user with buttons to choose the correct one instead of guessing.OffAdditional instructionsCustom guidance for the LLM classifier (e.g., "Treat refund requests as billing, not complaints").None Configuring Categories Each category in the list supports: Name -- a clear, descriptive label (e.g., "Billing", "Technical Support"). Must be unique within the agent. Description -- tells the LLM when to assign this category (up to 1,000 characters). Be specific: "Questions about invoices, charges, payment methods, or subscription billing" is better than "Billing stuff". Example queries -- sample messages that belong to this category. These help the agent match similar messages, and on exact match the agent assigns the category instantly without calling the LLM. Qualification criteria -- deterministic rules that force a category assignment without LLM evaluation. Requires a JSON Extractor agent connected upstream to supply structured data for rule evaluation. How Classification Works Exact match check: If the user's message exactly matches an example query, that category is assigned immediately. Qualification criteria: If rules are configured and structured data is available from an upstream JSON Extractor, the rules are evaluated. A match assigns the category without calling the LLM. LLM classification: If no deterministic match occurs, the agent sends the recent conversation (limited by context window) to the LLM along with your category descriptions and instructions. Multi-intent handling: If the LLM detects the message could match multiple categories and human collaboration is enabled, the end user sees clickable buttons to choose. Otherwise, the agent picks the best match. Fallback: If no category matches, the fallback category is assigned. How to Use This Agent A customer service AI Employee with three intents: chat_trigger -> categorize_conversations_and_route -> [billing] -> search_billing_kb -> respond -> workflow_output -> [technical] -> search_tech_kb -> respond -> workflow_output -> [other] -> general_respond -> workflow_output Tips Write detailed category descriptions. The LLM relies on these to distinguish between categories. Vague descriptions lead to misclassification. Add example queries for high-volume, unambiguous intents. Exact matches bypass the LLM entirely, reducing latency and cost. Enable human collaboration for workflows where getting the category wrong is costly (e.g., routing a complaint to sales). The small friction of asking the user to click a button is worth the accuracy gain. Use qualification criteria when you have structured data (from a JSON Extractor) that reliably determines the category -- for example, routing based on a ticket priority field or customer tier. Keep the context window at 10 unless your conversations are unusually long. More context means higher LLM cost and can introduce noise from earlier, unrelated parts of the conversation. Related Agents Categorizer -- more flexible categorization that works with any input type, not just conversations. Text Categorizer -- categorizes plain text rather than conversation objects.

================================================================================
# Categorizer Agent
URL: https://builder.ema.ai/agent-reference/core/categorizer
================================================================================

Categorizer Agent The Categorizer is the most flexible classification agent on the platform. It accepts any combination of inputs -- documents, emails, extracted entities, conversations, or plain text -- via the named inputs system, and assigns one of your defined categories. Each category becomes a separate branch on the GWE canvas. If you're unsure which categorizer to use, start here. The Categorizer handles the widest range of input types and is the recommended choice for new workflows. Use Cases You need to route a workflow based on the content of any input -- documents, emails, extracted entities, or custom data. You want a single agent that handles both deterministic rule matching and LLM-based classification. You need to classify based on multiple inputs at once (e.g., both an email body and its extracted metadata). You need multi-level categorization (chain multiple Categorizer agents for hierarchical classification). Inputs The Categorizer uses named inputs, meaning you can wire any combination of data from upstream agents. Common inputs include: Named InputTypeDescriptionTextTextPlain text to classify.DocumentDocumentA document to classify.EmailEmailAn email message to classify.ConversationConversationA chat conversation to classify.EntitiesJSONExtracted entities or structured data to classify. You can provide multiple named inputs simultaneously. The agent considers all of them when making its classification decision. Outputs OutputTypeDescriptioncategoryCategoryThe assigned category name. Each defined category also produces a branch edge on the GWE canvas. Only the matching branch executes. Configurations ParameterDescriptionDefaultCategoriesList of categories. Each has a name, description (up to 1,000 characters), optional example queries, and optional qualification criteria.RequiredFallback categoryCategory used when no match is found. Defaults to "Fallback" and cannot be changed once set.RequiredCategorization instructionsCustom guidance for the LLM (e.g., "Prioritize the email subject over the body" or "Treat anything mentioning 'urgent' as high priority")."Use all the inputs available and categorize into the most appropriate category."Process entire documentWhen a document is provided as input, controls whether the full document is sent to the LLM or just the relevant snippets.OffQualification criteriaDeterministic rules per category. Requires a JSON Extractor agent connected upstream to supply structured data.None Configuring Categories Each category supports: Name -- a unique, descriptive label. Cannot be changed after creation. Description -- tells the LLM when this category applies. Up to 1,000 characters. Be specific about the criteria. Example queries -- sample inputs that belong to this category. Helps the agent recognize similar inputs. No duplicates allowed. Qualification criteria -- deterministic rules evaluated before the LLM. If a rule matches, the category is assigned immediately without LLM evaluation. Rules require structured data from an upstream JSON Extractor. A category description is optional if qualification criteria are provided (since the rules handle classification), but recommended for clarity. How Classification Works Qualification criteria: If rules are configured, they are evaluated first. A matching rule assigns the category immediately. LLM classification: If no rule matches, the agent sends all named inputs to the LLM along with your category descriptions and instructions. Fallback: If the LLM cannot confidently assign a category, the fallback category is used. How to Use This Agent Categorize inbound emails by department: email_trigger -> categorizer -> [sales] -> sales_workflow -> [support] -> support_workflow -> [hr] -> hr_workflow -> [other] -> general_workflow Tips Wire all relevant context as named inputs. The more information the agent has, the better it classifies. For example, wire both the email body and extracted entities from a JSON Extractor. Use qualification criteria for deterministic routing. If a structured field reliably determines the category (e.g., a "department" field from extracted data), add it as a rule. This is faster and more predictable than LLM classification. Keep categories mutually exclusive. Overlapping descriptions lead to inconsistent results. If two categories are similar, add distinguishing criteria in the description. Enable "Process entire document" only when the full document content matters for classification. For large documents, leaving it off reduces latency and cost. Related Agents Categorize Conversations and Route -- specialized for chat conversations with multi-intent detection and human collaboration. Document Categorizer -- deprecated; use the Categorizer with document named inputs instead. Text Categorizer -- simpler text-only classification (v0, deprecated).

================================================================================
# Chart Builder Agent
URL: https://builder.ema.ai/agent-reference/core/chart-builder
================================================================================

Chart Builder Agent The Chart Builder Agent reads tabular data inside your markdown content and renders bar or line charts from it based on the plotting instructions you provide. The rendered charts are inserted into the same markdown, either alongside the source tables or in place of them. Use Cases Visualizing trends and patterns from tabular data. Creating quick, chart-based reports for presentations. Converting markdown tables into charts. Generating performance summaries with visual elements. Creating research reports with embedded data visualizations. Inputs InputRequiredDescriptionTexts with MarkdownYesOne or more inputs that contain markdown text with tables. Typically supplied by an upstream agent whose output is markdown, such as a search or retrieval step.Runtime plotting instructionsNoPlotting guidance that can vary per run, usually wired from a user input or another upstream agent. Overrides or refines the config time plotting instructions for that run. Outputs OutputDescriptionTexts with chartsThe original markdown content with rendered bar or line charts placed inline. When Replace Existing Tables is on, tables are replaced by the charts. When off, the charts follow each table. Configurations ParameterRequiredDescriptionConfig time plotting instructionsYesStatic plotting guidance set when building the workflow. This is the primary place to describe what charts you want and how they should look. Advanced Configurations ParameterDescriptionDefaultReplace Existing TablesWhen on, source tables are replaced by the rendered charts. When off, charts are added alongside the tables.OffEnable LLM Table ParsingNormalize messy or irregular tables before charting. Improves results for tables with merged headers or inconsistent rows.OffEnter figure height (in mm)Height of each chart image.150Enter figure width (in mm)Width of each chart image.250Show data point annotationsPrints the numeric value next to each plotted point.OnDecimal places for data point annotationsPrecision used when showing point values.0Show average linesAdds a reference line at the mean of the plotted values.OffDisplay legendShows the chart legend.On How to Use This Agent After a knowledge base search returns a response that includes a markdown table of quarterly revenue: chat_trigger -> knowledge_search -> respond_agent -> chart_builder -> workflow_output Related Agents Respond Agent, often used upstream to produce the markdown response that contains the tables. Generate Document, for producing full documents that may embed charts.

================================================================================
# Combine Search Results Agent
URL: https://builder.ema.ai/agent-reference/core/combine-search-results
================================================================================

Combine Search Results Agent The Combine Search Results agent merges search results from multiple upstream search agents into a single, deduplicated, and weighted result set. Use it when a workflow searches across several knowledge bases or search strategies and needs to present unified results to a downstream response agent. Use Cases Your workflow runs multiple Knowledge Search agents against different data sources in parallel. You need to deduplicate and rank results from heterogeneous sources. You want to assign different weights to different sources (e.g., internal docs weighted higher than web results). Inputs InputTypeDescriptionsearch_results_1SearchResultsResults from the first search agent.search_results_2SearchResultsResults from the second search agent.search_results_NSearchResults(Optional) Additional result sets. Accepts any number of named search result inputs. Outputs OutputTypeDescriptioncombined_resultsSearchResultsThe merged, deduplicated, and ranked result set. Configurations ParameterDescriptionDefaultweightsPer-source weight multipliers for ranking. Higher weight = higher priority.Equal weightsmax_resultsMaximum number of results in the combined output.10 How to Use This Agent Search both an internal HR knowledge base and a public benefits FAQ, then combine: chat_trigger -> knowledge_search_hr --------\ -> knowledge_search_benefits ----> combine_search_results -> respond_using_search_results -> workflow_output Related Agents Knowledge Search -- the primary search agent whose outputs feed into this agent. Rerank Search Results -- for LLM-based reranking after combining. Respond using Search Results -- typically the downstream consumer.

================================================================================
# Combine Text Agent
URL: https://builder.ema.ai/agent-reference/core/combine-text
================================================================================

Combine Text Agent The Combine Text agent merges multiple text inputs into a single coherent response based on user-defined instructions. It consolidates information while maintaining clarity, source attribution, and contextual flow. It supports two modes: LLM mode (intelligently synthesizes texts based on your instructions) and append mode (concatenates texts as-is without processing). Use Cases Research Synthesis -- Merge multiple search results or document excerpts into one summarized answer. Content Aggregation -- Combine knowledge base entries, chat logs, or reports into a unified text. Document Creation -- Automatically generate summaries or stitched documents from segmented inputs. Knowledge Consolidation -- Pull together fragmented insights while retaining source references. Inputs InputTypeRequiredDescriptiontexts_with_sourcesList of TextsYesA collection of text segments from other agents or external sources.instructionsStringYesUser-defined guidance on how the texts should be combined (e.g., summarize, merge seamlessly, or retain structure). Outputs OutputTypeDescriptioncombined_text_with_sourcesText With SourcesA single, unified text that merges all inputs. Includes consolidated sources when provided and preserves logical flow according to your instructions. Configurations None. Advanced Configurations ParameterDescriptionAppend Input Values As-IsDirectly concatenates all text inputs in order, skipping LLM processing. Useful for creating raw, unprocessed combined documents.Configure EmaFusionUses Ema's intelligent fusion to combine multiple LLM outputs. Optionally allows selecting specific LLMs or integrating custom models. How to Use This Agent Merge a ticket summary and a knowledge base answer before sending a response: ticket_trigger -> thread_summarizer ----\ -> knowledge_search -> respond_using_search_results ---> combine_text -> send_email Related Agents Combine Search Results -- for merging search result objects rather than plain text. Convert to Text -- for converting non-text types to text before combining.

================================================================================
# Conversation Summarizer Agent
URL: https://builder.ema.ai/agent-reference/core/conversation-summarizer
================================================================================

Conversation Summarizer Agent The Conversation Summarizer agent converts a multi-turn chat conversation into a concise search query that captures the user's current intent. It distills the conversation history so downstream search agents receive a focused query rather than the entire conversation. Important: By default, this agent does not use an LLM. It concatenates recent messages into a formatted string. Enable LLM mode in the agent's configuration if you need intelligent summarization that interprets context and resolves references across turns. Use Cases Your workflow handles multi-turn conversations and needs to search a knowledge base based on the user's latest intent. Passing the full conversation to a search agent degrades search quality, and you need a distilled query instead. The user's most recent message alone lacks enough context for an accurate search (e.g., "What about the second one?"). Inputs InputTypeDescriptionchat_conversationConversationThe multi-turn chat conversation to summarize. Outputs OutputTypeDescriptionqueryTextA concise search query derived from the conversation.tagsList of TextExtracted tags, if tag extraction is configured. Configurations ParameterDescriptionDefaultLLM modeWhen enabled, uses an LLM to intelligently summarize the conversation into a search query. When disabled, simply concatenates recent messages.OffContext windowNumber of recent messages to include. Older messages are excluded.10InstructionsCustom guidance for the LLM (e.g., "Focus on the most recent question" or "Ignore greetings"). Only applies when LLM mode is enabled.NoneGlossaryCompany-specific terms and definitions to help the LLM interpret domain language correctly.NoneTag extractionRules for extracting tags from the conversation alongside the search query.None How the Two Modes Work Default Mode (LLM off) The agent takes the most recent messages (up to the context window) and concatenates them with speaker labels: User: I need help with my subscription Bot: Sure, I can help. What's the issue? User: I was charged twice this month This is fast and cost-effective, but the output is a formatted transcript -- not an optimized search query. LLM Mode The agent uses an LLM to interpret the conversation and produce a focused search query. For the same conversation above, it might output: duplicate subscription charge billing issue Use LLM mode when the conversation involves context-dependent references, topic shifts, or when downstream search quality matters. How to Use This Agent In a multi-turn chat workflow, place the Conversation Summarizer before a search agent: chat_trigger -> conversation_summarizer -> knowledge_search -> respond_using_search_results -> workflow_output Tips Start with the default mode. Switch to LLM mode only if you notice search quality degrading on multi-turn conversations. If your conversations are typically short (1-2 turns), you may not need this agent at all -- wire the conversation directly to your search agent. Use the instructions field to steer LLM summarization for your domain: "Focus on the product name and issue type" or "Treat the last user message as the primary query." The context window of 10 messages works well for most support conversations. Increase it if your users have long-running threads where early context matters. Related Agents Knowledge Search -- the typical downstream consumer of the summarized query. Thread Summarizer -- summarizes support ticket threads rather than chat conversations.

================================================================================
# Convert to Text Agent
URL: https://builder.ema.ai/agent-reference/core/convert-to-text
================================================================================

Convert to Text Agent The Convert to Text agent converts any number of named inputs of various types into a single text string. It automatically detects input types and converts them to text format, then combines them in connection order. This is a deterministic operation that does not use LLMs. Use Cases Converting diverse agent outputs (documents, extraction results, search results) into a single text format for downstream processing. Generating query strings from agent outputs for use in search or other text-based operations. Preparing multiple inputs for LLM consumption by converting them to a unified text format. Combining structured and unstructured data into a single text output. Inputs InputTypeRequiredDescriptionnamed_inputsAny (multiple)YesFlexible inputs from other agents. Supports Documents, Search Results, Extraction Columns, Rule Sets, Text with Sources, plain text, primitives, structured data (JSON), and lists of any supported type. Outputs OutputTypeDescriptiontext_with_sourcesText With SourcesCombined text from all inputs (separated by delimiters), with consolidated source references and confidence set to 1.0. Configurations This agent has no additional configuration. The conversion is determined entirely by the input type. Conversion Behavior by Type Input TypeConversionDocumentsConverts using document formatting to extract text content.Search ResultsExtracts text and sources from search results.Extraction ColumnsConverts to JSON string representation.Rule SetsConverts to JSON string and extracts associated sources.Text with SourcesExtracts text directly.PrimitivesNumbers, booleans, and strings converted to string representation.Structured DataJSON objects and lists converted to JSON string format.ListsRecursively processes each element according to its type. How to Use This Agent Convert an email to text before passing to a categorizer that expects text input: email_trigger -> convert_to_text -> text_categorizer -> [branch] -> ... Related Agents Combine Text -- for merging multiple text values.

================================================================================
# Custom Agent
URL: https://builder.ema.ai/agent-reference/core/custom-agent
================================================================================

Custom Agent The Custom Agent is a general-purpose LLM agent that accepts any combination of inputs and produces text or structured outputs. It is the most flexible agent in the platform -- use it when no specialized agent fits your needs, or when you need to implement custom logic with LLM reasoning. Use Cases No existing agent covers your specific task. You need a flexible LLM step with custom instructions. You want to prototype a new capability before requesting a dedicated agent. You need to transform, analyze, or reason about data in a way not covered by other agents. You need structured (typed/JSON) output from an LLM step. Inputs InputTypeRequiredDescriptionrole_instructionsTextYesRole instructions defining the agent's behavior and personality (e.g., "You are a legal contract reviewer").task_instructionsTextNoSpecific instructions for the task to accomplish. Use this for per-invocation guidance that is separate from the agent's role.named_inputsAny[]YesAt least one input must be provided. Accepts any type: text, search results, documents, conversations, entities, etc.output_fieldsExtractionColumn[]NoDefine a structured output schema. When set, the agent returns typed fields instead of free-form text -- useful for downstream agents that expect structured data. Outputs OutputTypeDescriptionresponse_with_sourcesTextThe LLM-generated output based on your instructions, with source attribution when available. Configurations ParameterDescriptionDefaultrole_instructionsThe primary prompt that defines the agent's behavior and personality. Set this in the agent's configuration panel.Requiredtask_instructionsPer-task instructions that supplement the role. Useful when the same agent handles different tasks via different workflow paths.Nonemodel_configOverride the EmaFusion model selection for this agent. Auto-wired from the AI Employee's EmaFusion configuration unless overridden.EmaFusion default Advanced Configuration ParameterTypeDescriptionprocess_entire_documentBooleanWhen enabled, processes the full content of input documents rather than chunking.use_citation_based_filteringBooleanEnforces citation grounding -- the agent must ground its response in the provided sources.disable_sourcesBooleanRemoves source attribution from the output.glossaryGlossaryItem[]Custom terminology definitions to ensure consistent, domain-accurate language in the response.user_tagsString[]User metadata tags for prompt personalization (e.g., country, role, department).data_protection_configDataProtectionConfigPII handling configuration -- controls how sensitive data is obfuscated before being sent to the LLM. How to Use This Agent A custom agent that extracts action items from meeting notes: document_trigger -> custom_agent("Extract all action items with assignee and deadline from these meeting notes. Return as a numbered list.") -> send_email -> workflow_output A custom agent that rewrites a knowledge base answer for a specific audience: chat_trigger -> knowledge_search -> respond_to_a_query -> custom_agent("Rewrite the response for a non-technical audience") -> workflow_output Related Agents Respond to a Query -- similar but optimized for response generation with source grounding. Extract Entities -- for structured entity extraction; prefer this over Custom Agent for that task. Custom Code Agent -- for deterministic JavaScript logic; prefer this when you do not need LLM reasoning. Specialized agents in the Specialized Agents Catalog -- pre-trained Custom Agent variants for specific domains.

================================================================================
# Custom Code Agent
URL: https://builder.ema.ai/agent-reference/core/custom-code-agent
================================================================================

Custom Code Agent The Custom Code Agent lets you write and execute custom JavaScript or TypeScript directly inside your workflow. When no existing agent fits your use case -- or you need precise data transformation or conditional logic -- the Custom Code Agent gives you full programmatic control without leaving the canvas. Scripts run inside a secure, sandboxed environment powered by the script-executor service. Each execution is isolated, resource-limited, and logged so you can debug failures quickly. Use Cases Data transformation -- reshape, filter, or enrich structured data (CSV, JSON) before passing it downstream. Custom LLM prompts -- call the built-in call_llm() function with a dynamically constructed prompt. Branching logic -- use if/else or switch based on data values. String manipulation -- regex extraction, formatting, encoding/decoding (Base64, UUID generation). Lightweight computation -- calculations, aggregations, or rule-based classification that don't require a full agent. Format conversion -- parse CSV into JSON, serialize an object to a string, encode binary data. Limitations Limited external network access -- direct HTTP requests are not supported, but outbound calls are available through configured integrations via call_ema_connector(). See Custom Integrations. No file system access -- you cannot read from or write to disk. No long-running processes -- execution is bounded by a strict time limit. No calling other agents or workflows -- chaining to other canvas nodes from inside the script is not supported. JavaScript and TypeScript -- both JavaScript and TypeScript are supported (select via the script_language input, with valid values "JavaScript" and "TypeScript"). No stateful side-effects -- each invocation is fully stateless; nothing persists between runs. No async/await -- the sandbox runs synchronous JavaScript only. Inputs Required Script: JavaScript code to execute. The script must define a main function with the following signature: function main(inputs) { // your logic return "result"; } Required function signature: The function name must be exactly main, it must accept exactly one argument named inputs, and it must return a value (preferably a string). Using async is not supported. Optional: Named Inputs Data from other agents passed into the script. Each input is converted to a script-executor type and exposed under inputs.<name>. Input names are sanitized to valid JavaScript identifiers (spaces become underscores; a leading underscore is added if the name starts with a digit). The inputs object is frozen -- your script cannot modify it. Supported Input Types Input TypeJavaScript ValueNotesStringstringPassed as-isNumbernumber (float64)Use directly; no parsing neededBooleanbooleanCompare with === true / === falseDocumentObject with .text, .filenameAccess via inputs.doc_name.textSearch ResultObject with .text, .source, .matches.matches is an array of stringsListArrayOrdered; use .forEach, indexing, etc.MapObjectString-keyed; use dot or bracket notationNullnullCheck with === null before use Other well-known types may not be supported as Custom Code Agent inputs and can cause an error if used. Output The agent returns the script's result as Text with Sources. The main function must return a value that can be converted to a string; the returned value becomes the agent's output via JavaScript's .toString(). Always return a string explicitly to control format: return "done"; return JSON.stringify({ status: "ok", count: 42 }); return Base64.encode(inputs.raw_data); If you return an object without stringifying it, .toString() yields "[object Object]". Downstream agents receive this string; if you return JSON, the receiving agent must parse it. Script Environment Supported Libraries The following libraries are available as globals (no require() needed): LibraryGlobalUse CasepapaparsePapaCSV parsing and serializationuuiduuidUUID generation (uuid.v4(), etc.)lodash_Utility functions for arrays/objectsbase64Base64Base64 encoding/decoding Built-in globals: JSON, Math, crypto (e.g., crypto.getRandomValues()). Calling the LLM call_llm(user_prompt, system_prompt?) is available as a global function. It is synchronous -- no await needed. Time spent in call_llm() is excluded from the script's time limit. Each call is tracked in the Show Work panel (cost, latency, token counts). ParameterTypeRequiredDescriptionuser_promptstringYesThe user message sent to the LLM. Must be a non-empty string.system_promptstringNoOverrides the default system prompt. Use to control persona, output format, or constraints. // Using the default system prompt var summary = call_llm("Summarize:\n\n" + inputs.text); // Using a custom system prompt var result = call_llm( "Extract all dates from the following text:\n\n" + inputs.text, "You are a precise data extractor. Return only a JSON array of ISO 8601 date strings. No explanation." ); Calling External Integrations call_ema_connector(integrationId, method, path, body?, headers?) is available as a global function when external integrations are configured on the persona. It is synchronous and its execution time is excluded from the script's time limit. Returns an object with ok (boolean), status (number), body (string), headers (object), and request_log_id (string). See Custom Integrations for setup. Work Logs (Show Work) Use log.info(), log.warning(), and log.error() to emit work logs. These appear in the Show Work panel. For objects or arrays, pass the result of JSON.stringify() for clear output. Type Hints for Code Generation The script editor displays auto-generated type hints at the top of every script once you add named inputs and connect them. These hints tell the LLM exactly what inputs exist and their types. When asking an LLM to generate code, paste the full type-hint block first: // Libraries: lodash (_), uuid, papaparse (Papa), base64-js (Base64) // call_llm(user_prompt, system_prompt?) -> string // log.info(msg) / log.warning(msg) / log.error(msg) // /** @param {{ query: string; csv: { text: string, filename: string}[]; // Document inputs are arrays }} inputs * @returns {string} */ function main(inputs) {} Testing Scripts The Custom Code Agent includes a testing mode that lets you run your script against test data in real time before saving the workflow. Test runs execute real call_llm() and call_ema_connector() calls, so they incur the same cost as a live run. Running a Test Click the Test button above the script editor to open the test modal. The script editor appears on the left and the test panel on the right. Edit the Test inputs JSON in the right panel. A template is pre-populated based on your configured named inputs. Tip: You can copy real inputs from a previous workflow run to use as test data. Open Show Work → Execution logs → Script Inputs on any past run and paste them into the test input panel. Click Run Test. The script executes against the provided inputs. Review results in the panel: the Output section shows the value returned by main() or the error message, and the Work Log section shows execution steps, log messages, and LLM call details (prompt, response, cost, latency). Test Input Format Test inputs are a JSON object keyed by named input name. Types must match what the script expects: TypeJSON FormatString / Number / BooleanJSON primitiveDocument{ "text": "...", "filename": "..." }Search Result{ "text": "...", "source": "...", "matches": [] }ListJSON arrayMapJSON objectNullnull Test results are not saved after you close the modal. Time and Memory Limits LimitValueNotesTime100 msWall-clock for script execution; call_llm() time is excludedMemory24 MB initial / 128 MB maxHeap for the scriptLLM calls40 per executionMaximum number of call_llm() invocations per script runExternal connector calls20 per executionMaximum number of call_ema_connector() invocations per script run Exceeding the time limit returns a TimeLimitExceeded error; exceeding memory causes the runtime to terminate execution. Common Failure Modes ErrorCauseFixMemory Limit ExceededScript accumulates large structures in memory.Reduce payload size or avoid accumulating large structures.Wrong arguments to call_llm()First argument is not a non-empty string, or an object was passed.Ensure user_prompt is a string: call_llm("Summarize: " + inputs.text).TypeError: Cannot read properties of undefinedAccessing a field on an input that may be null or undefined.Guard optional fields: if (inputs.user) { var name = inputs.user.name; }.Time Limit ExceededScript processing takes longer than 100 ms.Reduce data volume per run or offload heavy work upstream.Invalid script result formatScript executor returns an unexpected shape.Check Show Work for details; ensure main returns a string. Open the Show Work panel after a failed run for stack traces and log output. Add log.info() at key points to trace where execution stopped. Examples Simple greeting: function main(inputs) { return "Hello, " + inputs.first_name + " " + inputs.last_name + "!"; } Parse and filter CSV data (document input): // Named input "csv_data" is a list of documents -- use csv_data[0].text function main(inputs) { var result = Papa.parse(inputs.csv_data[0].text, { header: true, skipEmptyLines: true }); var filtered = result.data.filter(function(row) { return row.amount >= 10; }); return Papa.unparse(filtered); } LLM summarization: function main(inputs) { var summary = call_llm("Summarize in 2 sentences:\n\n" + inputs.content); return summary.trim(); } UUID generation and Base64 encoding: function main(inputs) { var id = uuid.v4(); return Base64.encode(JSON.stringify({ id: id, data: inputs.query })); } Related Agents Custom Agent -- for LLM-powered reasoning; use when the task requires natural language understanding rather than deterministic code. JSON Extractor -- for extracting fields from JSON without writing code. Convert to Text -- for simple type conversion without custom logic.

================================================================================
# Deep Web Search Agent
URL: https://builder.ema.ai/agent-reference/core/deep-web-search
================================================================================

Deep Web Search Agent The Deep Web Search agent performs multi-strategy web searches using AI to find, evaluate, and synthesize information from the public internet. It goes beyond simple keyword search by trying multiple query formulations and evaluating result quality. Use Cases Your workflow needs real-time information from the internet that is not in your knowledge base. You want to supplement internal knowledge with public data (market research, competitor analysis, news). The user's question requires up-to-date information that may not exist in pre-indexed sources. Inputs InputTypeRequiredDescriptionQueryText with SourcesYesThe main search query. Can be a question, topic, or specific information request.InstructionsTextNoOptional guidance prepended to the query (for example, "Focus on official sources" or "Find recent news about"). Outputs OutputTypeDescriptionWeb Search ResultsSearch Results (array)Web research results. Each result contains the source URL, title, and scraped content. Results may include both AI-synthesized answers and directly scraped web content, combined and reranked for relevance. Configurations ParameterDescriptionDefaultMaximum SourcesMaximum number of web sources returned.5Number of days to filter by to find the latest resultsOnly return results from within this many days. When set, forces normal web search and disables AI search.0 (no filtering)Allow Google SearchWhen on, uses Google as the search engine. When off, uses DuckDuckGo with SearXNG as fallback.OffEnsure Ema always cites source web linksWhen on, disables AI search so every result comes from a scraped web source with an explicit URL.OffReturn relevant links with brief summaries; skip full scrapingWhen on, returns titles, URLs, and snippets only (fast). When off, scrapes full page content for each result (slower, more comprehensive).OffEnable query preprocessing and classificationWhen on, runs LLM preprocessing to classify the query and extract site filters before searching. Turn off to search the query as-is.On How to Use This Agent A competitive intelligence AI Employee that combines internal data with web research: chat_trigger -> knowledge_search ->\ combine_search_results -> respond_using_search_results -> workflow_output -> deep_web_search ->/ Related Agents Agentic Search and Respond: can invoke web search as part of its iterative research; use this for autonomous research. Knowledge Search: for internal knowledge base search. Combine Search Results: for merging web and internal results.

================================================================================
# Document Categorizer Agent
URL: https://builder.ema.ai/agent-reference/core/document-categorizer
================================================================================

Document Categorizer Agent Deprecated. This agent has been superseded by the Categorizer agent, which accepts documents and any other input type via named inputs. Existing workflows using Document Categorizer continue to work, but new workflows should use the Categorizer instead. The Document Categorizer agent classifies documents into predefined categories based on their content. It analyzes the document text and assigns the most appropriate category from your configured list. Use Cases A document-processing workflow needs to route documents to different handling paths based on type (e.g., invoices, contracts, reports). You want to auto-tag incoming documents for downstream processing. You need to triage a document inbox by content type. Inputs InputTypeDescriptiondocumentsDocumentsOne or more documents to categorize.text_inputText (optional)Supplemental text to consider alongside the documents. Useful when metadata or extracted fields should influence categorization. At least one of documents or text_input must be provided. Outputs OutputTypeDescriptioncategoryCategoryThe assigned category name. Each category produces a branch edge on the GWE canvas. Configurations ParameterDescriptionDefaultCategoriesList of category definitions with names and descriptions.RequiredFallback categoryCategory assigned when no category matches with sufficient confidence. Set to "Fallback" and cannot be changed once set.RequiredQualification criteriaDeterministic rules for categories. Requires a JSON Extractor agent connected upstream.None How to Use This Agent Route incoming documents to the correct processing pipeline: document_trigger -> document_categorizer -> [invoice] -> extract_entities -> accounting_workflow -> [contract] -> extract_entities -> legal_review -> [report] -> document_synthesis -> respond -> [other] -> human_collaboration Migrating to Categorizer The Categorizer agent replaces Document Categorizer with broader input support. To migrate: Replace the Document Categorizer node with a Categorizer node. Wire your document source to the Categorizer's named inputs. Re-create your category list and fallback category. Test the workflow to verify classification behavior is preserved. Related Agents Categorizer -- the recommended replacement. Accepts any input type via named inputs. Text Categorizer -- for plain text classification. Thread Categorizer -- for support ticket thread classification.

================================================================================
# Document Synthesis Agent
URL: https://builder.ema.ai/agent-reference/core/document-synthesis
================================================================================

Document Synthesis Agent The Document Synthesis agent performs agentic document search with support for images and tables within documents. Unlike the simpler Knowledge Search, it can understand and reference visual elements in documents, making it suitable for searches over richly formatted content. Use Cases Your knowledge base contains documents with important images, charts, or tables that affect the answer. You need the agent to interpret visual elements alongside text when retrieving information. Standard text-based search misses answers that are embedded in tables or figures. Inputs InputTypeRequiredDescriptionuser_requestText with SourcesYesThe search query or question.named_inputsAny (array)NoAdditional context as reference materials (e.g., documents, text, search results).datastore_configsDatastoreConnection (array)NoKnowledge base data sources to search. Outputs OutputTypeDescriptiondocument_synthesis_resultText with SourcesThe synthesized response with references to source documents, including image and table citations. Configurations ParameterDescriptionDefaultuse_web_searchWhether the agent can search the internet for information.falseuse_image_searchWhether to search for images in preuploaded documents.falseuse_code_interpreterWhether to enable code execution for analysis and visualization.falseuse_web_scrapingWhether to enable full web page scraping with content extraction.falsereasoning_levelDepth of model reasoning: None, Low, Medium, High, or Default.Defaultmaximum_iteration_limitMaximum number of agent iterations before forcing a final response.15search_instructionsInstructions that guide how the agent searches.Nonerespond_instructionsInstructions that guide how the agent formats the response.None How to Use This Agent A compliance AI Employee that needs to reference policy documents containing tables and flowcharts: chat_trigger -> document_synthesis -> workflow_output Related Agents Knowledge Search -- simpler text-based search; use when documents are text-only. Agentic Search and Respond -- for multi-step research across multiple sources.

================================================================================
# Extract Entities Agent
URL: https://builder.ema.ai/agent-reference/core/extract-entities
================================================================================

Extract Entities Agent The Extract Entities agent performs schema-driven entity extraction from documents and text. You define an extraction schema -- a list of columns with names, types, and descriptions -- and the agent uses an LLM to fill each column from the input, returning structured values with source citations. Use Cases You need to pull structured data from unstructured documents (invoices, contracts, resumes, forms). A downstream agent or integration requires specific fields extracted from a document. You want to populate a database, CRM, or ticketing system with data extracted from incoming documents. You need to combine a document with additional context (e.g., extracted entities from an upstream agent) before extraction. Inputs InputTypeRequiredDescriptiondocumentsList of DocumentsNoThe documents to extract from. Provide either documents or text_input.text_inputText With SourcesNoPlain text to extract from. Provide either documents or text_input.named_inputsAny (multiple)NoAdditional context from other agents. Shown in the builder as Additional Context. Supports Text with Sources, Text, Search Results, JSON, Extraction output, Documents, and Enum. Outputs OutputTypeDescriptionextraction_columnsList of Extraction ColumnsThe populated extraction columns -- each column from your schema returned with its extracted value and source citation. Configurations ParameterDescriptionDefaultExtraction ColumnsThe schema defining what to extract. Each column has a name, description, and type. See Configuring Extraction Columns below.RequiredInstructionsAdditional extraction guidance for the LLM (e.g., "Dates should be in ISO format" or "Treat all prices as USD").None Configuring Extraction Columns Each extraction column supports: Name -- a unique field name used as the output key. Description -- tells the LLM how to find this value. Be specific: "The total amount due on the invoice, including tax" is clearer than "Amount". Type -- the data type expected for the extracted value. Supported types: Text -- a string value. Number -- an integer or decimal. Boolean -- true or false. Group -- a nested object with its own sub-columns. Useful for extracting structured sub-records (e.g., a list of line items on an invoice). Enum mode -- optional toggle that restricts the extracted value to a fixed set of possible values you define. Advanced Configurations ParameterDescriptionFusion Model ConfigSelects the LLM and reasoning settings used for extraction.Data Protection ConfigPrivacy controls that filter or mask sensitive content before sending to the LLM.Send entire documents as search resultWhen enabled, sends the full document to the LLM rather than snippets matched to each column. Useful for short documents or when full context matters; increases token usage.Disable SourcesWhen enabled, clears source citations from the output. The extraction still uses the source documents, but no citation links are returned. How to Use This Agent Extract key fields from an invoice and create a record: document_trigger -> extract_entities -> intelligent_actions("Create record in accounting system") -> workflow_output Related Agents JSON Extractor -- for extracting values from already-structured JSON, not from unstructured text. Custom Agent -- for ad-hoc extraction when you do not need a formal schema. Tag Extractor -- for extracting tags/labels rather than structured entities.

================================================================================
# Feedback Sentiment Analyzer Agent
URL: https://builder.ema.ai/agent-reference/core/feedback-sentiment-analyzer
================================================================================

Feedback Sentiment Analyzer Agent The Feedback Sentiment Analyzer agent reads structured feedback from the last message of a chat conversation and classifies it as positive, negative, or no feedback detected. It returns the sentiment a user selected when rating a prior response (for example, thumbs up, thumbs down, or a guided feedback option). It does not perform free-text sentiment analysis -- for that, use the Sentiment Analyzer agent. Use Cases You want to branch a workflow based on whether the user rated the previous AI Employee response positively or negatively. Your workflow escalates to a human (or swaps agents) when a user submits negative feedback. You are building a feedback loop that only triggers on explicit user ratings. Inputs InputTypeDescriptionconversationChatConversationThe chat conversation to analyze. The agent inspects the last message and returns its feedback type. Outputs OutputTypeDescriptioncategoryEnum (feedback_type)One of: FEEDBACK_TYPE_POSITIVE, FEEDBACK_TYPE_NEGATIVE, or FEEDBACK_TYPE_NO_FEEDBACK. Returns FEEDBACK_TYPE_NO_FEEDBACK if the last message is not a feedback submission. Configurations This agent has no configurable parameters. The classification categories are fixed, and the agent does not call an LLM. How to Use This Agent After responding to a user, check if their next message is feedback: chat_trigger -> respond_using_search_results -> (wait for user reply) -> feedback_sentiment_analyzer -> [negative] -> human_collaboration -> workflow_output -> [positive] -> workflow_output -> [no_feedback] -> continue_conversation Related Agents Sentiment Analyzer -- for LLM-based sentiment analysis of free-text messages, not limited to explicit feedback ratings. Categorize Conversations and Route -- for broader intent classification.

================================================================================
# Fixed Response Agent
URL: https://builder.ema.ai/agent-reference/core/fixed-response
================================================================================

Fixed Response Agent The Fixed Response agent returns a pre-configured response with support for template variables. It substitutes placeholder variables with actual values at runtime, making it useful for generating personalized or context-specific responses. No LLM is involved -- the response is deterministic, fast, and cost-free. Use Cases Generating personalized welcome messages with user-specific information. Creating templated email responses with dynamic content insertion. Providing standardized responses with variable data like order numbers or customer names. Building reusable response templates for customer support scenarios. Inputs InputTypeRequiredDescriptionnamed_inputsAny (multiple)NoFlexible inputs from other agents. Supports text responses, tool execution outputs, and primitive values (strings, numbers, booleans). Named Inputs take precedence over Extracted Variables when the same variable name exists in both.extracted_variablesJSONNoKey-value pairs to replace template variables (e.g., {"name": "John", "orderId": "123"}). Outputs OutputTypeDescriptionfixed_response_with_sourcesText With SourcesThe formatted response text with all template variables replaced by their actual values. Configurations ParameterDescriptionDefaultFixed Response TemplateThe template containing {{variable_name}} placeholders. Variables are case-sensitive and must match input names exactly. Supports HTML formatting tags (<br>, <strong>, <em>, etc.).Required Template Syntax Use double curly braces for variable placeholders. Variable names are case-sensitive -- {{Name}} is different from {{name}}. If a variable is not provided, the original placeholder is kept in the output. Dear {{Customer Name}}, Your claim {{Claim Number}} for ${{Amount}} has been {{Status}}. Thank you, {{Company Name}} Support How to Use This Agent Send an acknowledgment after a ticket is created: ticket_trigger -> extract_entities -> fixed_response("Your ticket #{{ticket_id}} is confirmed.") -> send_email -> workflow_output Related Agents Respond to a Query -- for LLM-generated responses when you need flexibility. Custom Agent -- for responses that require LLM reasoning.

================================================================================
# Generate Document Agent
URL: https://builder.ema.ai/agent-reference/core/generate-document
================================================================================

Generate Document Agent The Generate Document agent creates formatted .docx documents from markdown content. It supports style guides to control fonts, headings, spacing, and branding, producing professional documents suitable for external distribution. Use Cases Your workflow needs to produce a downloadable, formatted document (reports, proposals, summaries). You want to convert AI-generated markdown content into a branded Word document. A business process requires document output rather than inline text (e.g., generating SOWs, contracts, or reports). Inputs InputTypeDescriptionmarkdownTextThe document content in markdown format.style_guideDocument(Optional) A reference .docx document whose styles are applied to the output. Outputs OutputTypeDescriptiondocumentDocumentThe generated .docx file. Configurations ParameterDescriptionDefaulttitleDocument title (used in metadata and optionally as a header).None How to Use This Agent Generate a weekly summary report: scheduled_trigger -> knowledge_search -> custom_agent("Write a weekly summary report in markdown") -> generate_document -> send_email -> workflow_output Related Agents Custom Agent -- often used upstream to generate the markdown content. Chart Builder -- generates charts that can be included in documents.

================================================================================
# Human Collaboration Agent
URL: https://builder.ema.ai/agent-reference/core/human-collaboration
================================================================================

Human Collaboration Agent The Human Collaboration agent routes decisions to human reviewers, pausing the workflow until a human provides input. It supports three interaction modes: conversational (free-form chat), standard form (predefined fields), and custom form (builder-defined fields and layout). This is the primary mechanism for human-in-the-loop (HITL) workflows on the Ema platform. Use Cases A workflow step requires human judgment before proceeding (approvals, quality review, sensitive decisions). You need a human to provide additional information that the AI Employee cannot determine on its own. Regulatory or policy requirements mandate human oversight for certain actions. Inputs InputTypeDescriptionrequest_messageTextThe message shown to the human reviewer describing what they need to do.contextText(Optional) Additional context for the reviewer (e.g., the AI-generated draft, extracted data).form_fieldsJSON(Custom form mode) Definition of the form fields the reviewer must fill out. Outputs OutputTypeDescriptionapprovedBooleanWhether the reviewer approved the request.reviewer_responseTextThe reviewer's response text (conversational mode) or form data (form modes). The Human Collaboration agent produces two branch edges -- approved and rejected. You must handle both paths in your workflow. Failing to handle the rejected path leaves the user without a response. Configurations ParameterDescriptionDefaultmodeInteraction mode: conversational, standard_form, or custom_form.standard_formassigneesList of users or groups who can respond to the request.Workspace default reviewerstimeout_hoursHours before the request times out.24timeout_actionWhat happens on timeout: auto_approve, auto_reject, or escalate.escalateinstructionsInstructions shown to the reviewer alongside the request.None Interaction Modes Conversational: The reviewer sees a chat interface and can ask clarifying questions before making a decision. The AI Employee responds to the reviewer's questions using workflow context. Standard Form: The reviewer fills out a predefined approval form with approve/reject and optional comments. Custom Form: The builder defines form fields (text, dropdowns, checkboxes, dates) that the reviewer must complete. The form data is returned as structured output. How to Use This Agent An email-sending workflow with human approval: trigger -> knowledge_search -> respond_to_query -> human_collaboration -> [approved] -> send_email -> workflow_output -> [rejected] -> fixed_response("Your request was reviewed and declined.") -> workflow_output Related Agents Response Validator -- for automated validation that can reduce the need for human review. Categorizer -- route only sensitive categories to human review.

================================================================================
# Intelligent Actions Agent
URL: https://builder.ema.ai/agent-reference/core/intelligent-actions
================================================================================

Intelligent Actions Agent The Intelligent Actions agent executes actions across 200+ connected third-party applications using tool calling. It interprets natural language instructions to determine which tools to invoke, constructs the API calls, and returns the results. A single Intelligent Actions agent can manage tools from multiple applications simultaneously and intelligently selects the appropriate tool based on the user query and conversation context. Formerly known as the External Tool Caller. Use Cases Your workflow needs to read or write data in an external application (CRM, ticketing, HRIS, accounting, etc.). You want the AI Employee to take action in the real world -- creating records, updating statuses, sending notifications. You need to chain multiple API calls across different systems based on LLM reasoning. You want a single agent to orchestrate tools across multiple applications -- for example, looking up a customer in Salesforce, creating a ticket in ServiceNow, and notifying a team in Slack, all within one workflow step. Inputs InputTypeDescriptioninstructionsTextNatural language description of the action to perform.contextText(Optional) Data or parameters needed to complete the action (e.g., extracted entities, user input). You can feed output from other agents using the Additional Context configuration. Outputs OutputTypeDescriptionresultTextThe result of the tool execution in natural language.raw_resultJSONThe raw API response data. Configurations ParameterDescriptionDefaultintegrationsThe connected applications available to this agent. Configured via the workspace integrations page.All workspace integrationsinstructionsAdditional behavioral instructions (e.g., "Always confirm before creating records").Nonemax_tool_callsMaximum number of tool calls per execution.5 Supported Integrations The agent supports 200+ applications across categories including: CRM: Salesforce, HubSpot, Pipedrive Ticketing: Zendesk, Freshdesk, ServiceNow, Jira HRIS: Workday, BambooHR, Rippling Communication: Slack, Microsoft Teams, Gmail, Outlook Productivity: Google Workspace, Microsoft 365, Notion, Asana Accounting: QuickBooks, Xero, NetSuite See Integrations for the complete list. Custom Tool Integrations When the pre-built catalog does not cover a specific system, you can build custom tool integrations using Ema's no-code builder so AI Employees can call any HTTP-accessible API as an Intelligent Action. Custom tools are created as Custom Apps on the Integrations page. Each Custom App can hold one or more actions, and once registered, these actions appear alongside pre-built tools in the Intelligent Actions agent configuration. See Custom Integrations for a step-by-step guide. Multi-Tool Selection A single Intelligent Actions agent can support tools from multiple applications at once. The agent's decision engine evaluates the incoming request, selects the appropriate tool within the correct system, fills required parameters, executes the call, and returns the result for post-processing. This design ensures flexibility and scalability across diverse workflows with minimal manual routing. To add tools, click + Add in the agent configuration panel to open the tool selection menu. Choose the target application (such as ServiceNow) and select the specific tool actions you want to enable -- for example, Create Ticket, Update Due Date, or Add Ticket Comment. Parameter Configuration Each tool may require a different set of input parameters. Click Manage against any tool to open its parameter configuration screen. For each input, you can specify how the value is filled: Fixed value -- A specific constant that should always be used for a parameter. For example, you may want the User ID to always default to a predefined value. Human-in-the-Loop (HITL) You can enable HITL for each tool within the Intelligent Actions agent. When enabled, the agent pauses execution and prompts the user with a confirmation step before executing the tool action. Configuration options include: Message, confirmation button, cancel button -- Customize the text displayed to the user. Hidden parameters -- Select parameters that should be hidden from the end user (e.g., User ID). Mandatory vs. optional HITL -- Mandatory always pauses for approval; optional invokes HITL only when the agent needs more information to proceed. See Intelligent Human Collaboration for full details. How to Use This Agent After extracting invoice data, create a record in the accounting system: document_trigger -> extract_entities -> intelligent_actions("Create an accounts payable entry with vendor={{vendor}}, amount={{amount}}, due_date={{due_date}}") -> workflow_output Multi-tool workflow -- look up a customer, then create a support ticket: chat_trigger -> intelligent_actions("Look up customer {{email}} in Salesforce, then create a ServiceNow ticket with their account details") -> respond_using_action_calling_results -> workflow_output To display the output of a tool call to the end user, link a Respond using Action Calling Results agent immediately downstream. This response agent interprets both the original input query and the raw output from the Intelligent Actions agent to return a user-friendly response. Related Agents Respond using Action Calling Results -- for formatting tool execution results into user-facing responses. App Navigator -- for web UI automation when no API is available. Send Email -- dedicated email-sending agent; prefer over Intelligent Actions for email. Human Collaboration -- for routing to a human reviewer outside of per-tool HITL.

================================================================================
# JSON Extractor Agent
URL: https://builder.ema.ai/agent-reference/core/json-extractor
================================================================================

JSON Extractor Agent The JSON Extractor agent extracts specific values from a nested JSON object (or any agent output) and flattens them into named variables for use by downstream agents. It is a deterministic agent -- no LLM is involved. Use Cases An upstream agent returns complex nested JSON and you need specific fields for downstream processing. You need to flatten a deeply nested API response into a simple, flat structure. You want to expose extracted fields as template variables in a Fixed Response. You want to supply structured data to a Categorizer's qualification criteria. Inputs InputTypeRequiredDescriptioninput_jsonAnyYesThe nested data to extract from. Shown in the builder as JSON. Accepts output from any upstream agent -- JSON objects, lists, Text with Sources, extraction results, and more. Outputs OutputTypeDescriptionoutput_jsonStructA flat key-value object containing the extracted fields. Shown in the builder as Variables. Each extracted field is available as a template variable (e.g., {{variable_name}}) in downstream agents. Configurations ParameterDescriptionDefaultAdd sample inputA sample JSON value used to validate the input shape and populate the JSON Path picker with the list of available fields. You can upload a .json file or paste JSON directly.RequiredJSON Extractor ConfigurationThe list of mapping rules. Each rule defines one output variable. See Configuring Mapping Rules below.Required Configuring Mapping Rules Click Create JSON Mapping to add a rule. Each rule has five fields: Variable name -- the output key. Must start with a letter or underscore and contain only letters, numbers, and underscores (camelCase recommended). Cannot be changed once saved. Data type -- the expected type of the extracted value. Supported types: String, Number, Boolean, Datetime. Cannot be changed once saved. Required -- Mandatory or Optional. A Mandatory field with no matching value and no default raises an error at runtime; an Optional field is skipped or falls back to its default. JSON Path -- the path into the sample input to extract the value from. The builder shows a dropdown of valid paths derived from your sample JSON, filtered by the selected data type. You pick a path from the list rather than typing it. Default value -- optional fallback returned when the path is not found at runtime. Typed according to the selected data type. How to Use This Agent Extract fields from an API response before sending an email: trigger -> intelligent_actions("Look up customer order") -> json_extractor -> fixed_response("Order {{orderId}} for {{customerName}}") -> send_email Related Agents Extract Entities -- for extracting structured data from unstructured text (uses an LLM). Convert to Text -- for converting JSON to a text representation.

================================================================================
# Knowledge Search Agent
URL: https://builder.ema.ai/agent-reference/core/knowledge-search
================================================================================

Knowledge Search Agent The Knowledge Search Agent runs a search over one or more connected data sources and returns a ranked set of passages with source references that downstream agents can cite. Use Cases Your AI Employee needs to retrieve information from uploaded documents, connected data sources, or indexed content. You are building a FAQ bot, policy lookup, or documentation search. You need grounded answers backed by source documents. Inputs InputRequiredDescriptionQueryYesThe search text.Data SourcesNoThe knowledge bases to search. Usually wired at config time, can also be overridden per run.Filter by FilenameNoComma separated file names to restrict the search to specific documents. Quoted names containing commas are supported. Outputs OutputDescriptionSearch ResultsA ranked list of passages. Each entry carries the text snippet, a reference to the source document, and a relevance score used for ranking downstream. Advanced Configurations ParameterDescriptionDefaultNumber of Search ResultsHow many results to fetch from each connected data source before ranking.10Max SourcesMaximum number of source documents included in the final output after ranking.10Max Chunks per ResultMaximum number of content chunks pulled from each matched document.5Number of Previous ChunksNeighboring chunks to include before each match, for surrounding context.0Number of Next ChunksNeighboring chunks to include after each match, for surrounding context.0Disable ImagesTurns off image retrieval. When off, image results are returned alongside text passages.OffMax ImagesMaximum number of image results returned per match.5Enable Filtering by Document Validity DatesOnly returns documents whose validity window covers the current date.Off How to Use This Agent The standard search and respond pattern: chat_trigger -> knowledge_search -> respond_agent -> workflow_output With conversation context for multi-turn: chat_trigger -> conversation_summarizer -> knowledge_search -> respond_agent -> workflow_output Related Agents Respond Agent, the standard downstream agent for generating responses from search results. Conversation Summarizer, converts multi-turn conversations into search queries. Combine Search Results, merges results from multiple search agents. Rerank Search Results, LLM-based reranking for improved relevance. Agentic Search and Respond, for complex research that requires iterative searching. Document Synthesis, for searches that need image and table awareness.

================================================================================
# Mark as Public Response Agent
URL: https://builder.ema.ai/agent-reference/core/mark-as-public-response
================================================================================

Mark as Public Response Agent The Mark as Public Response agent signals that a support response should be published publicly to the end user. It does not perform the publish action itself; instead, it outputs a boolean flag for downstream ticketing systems (e.g., Zendesk, Freshworks, ServiceNow) to determine visibility. Use Cases Publish AI-generated replies as public comments to customers when criteria are met. Automatically post public responses for specific categories (e.g., password resets, FAQs). Route visibility rules in ticketing workflows without custom scripting. Convert an internal draft to a public customer-facing response when confidence is high. Standardize how visibility is decided across multiple ticketing platforms. Inputs None. Outputs OutputTypeDescriptionshould_publish_publiclyBooleanFlag indicating the response should be public. Downstream ticketing connectors consume this flag to publish the reply as a customer-visible comment rather than an internal note. Configurations None. Place this agent behind trigger conditions on specific ticket categories that should allow public responses, and map the should_publish_publicly output to the "Public Response" output of your Agent Assist workflow. How to Use This Agent ticket_trigger -> knowledge_search -> respond_using_search_results -> mark_as_public_response(true) -> workflow_output Related Agents Send Email -- for sending responses via email rather than ticket comments. Human Collaboration -- for routing to a human reviewer before publishing.

================================================================================
# Rerank Search Results Agent
URL: https://builder.ema.ai/agent-reference/core/rerank-search-results
================================================================================

Rerank Search Results Agent The Rerank Search Results agent uses an LLM to combine one or more lists of search results and reorder them by relevance to the query. It also shortlists the top matches, so you can wire in raw search results from multiple upstream agents without a separate merge step. Use Cases Initial search results have good recall but poor ranking (relevant results are buried). You have results from multiple search agents and want a single, intelligently ranked list. The query is complex and simple similarity scores do not capture relevance well. Inputs InputTypeDescriptionsearch_results_listsList of Search Result ListsOne or more lists of search results to combine and rerank. Typically wired from Knowledge Search or other search agents.queryText with SourcesThe query used to score relevance. Outputs OutputTypeDescriptionreranked_resultsList of Search ResultsThe combined, reordered, and shortlisted results. Original result objects are preserved; the agent only changes their order and count. Configurations ParameterDescriptionDefaultmax_resultsMaximum number of results to return after reranking.10user_instructionsAdditional guidance for ranking (e.g., "prefer recent documents").Noneuser_tags(Optional) Tags that describe the user or context (for example, Location:India). The agent prioritizes results that match these tag values.Nonemodel_config(Advanced) Overrides the LLM used for reranking via the Model Config widget.Platform default How to Use This Agent chat_trigger -> knowledge_search_1 ----\ -> knowledge_search_2 -----> rerank_search_results -> respond_using_search_results -> workflow_output Related Agents Combine Search Results -- merges result lists without reranking, when original order should be preserved. Knowledge Search -- the primary source of results to rerank. Respond using Search Results -- the typical downstream consumer.

================================================================================
# Respond to a Query Agent
URL: https://builder.ema.ai/agent-reference/core/respond-to-a-query
================================================================================

Respond to a Query Agent The Respond to a Query agent is the core, general-purpose response agent on the Ema platform. It generates text responses by synthesizing any combination of typed inputs -- search results, documents, conversation history, structured entities, and free-form text -- using LLM reasoning. Unlike specialized response agents that are tuned for a single input type, Respond to a Query uses the full Type System through Named Inputs, making it the right choice whenever no specialized agent fits your specific input combination. Use Cases You need a flexible response agent that can work with any combination of upstream data. You want to generate a response that synthesizes information from multiple sources (e.g., search results plus extracted entities plus conversation history). No specialized response agent fits your specific input combination. You want to route custom typed data (documents, extracted entities, chat conversations) through a single response step without a custom agent. Inputs Respond to a Query uses Named Inputs for its "Additional Context" section, allowing any number of labeled, typed fields to be bound from upstream agents. Common named inputs include: Named InputTypeDescriptionTextTextAny free-form text context.Search_ResultsSearchResultsSearch results to ground the response. The agent reads passages and can cite sources.ConversationConversationChat history for conversational awareness and multi-turn context.DocumentDocumentDocument content to reference in the response.EntitiesJSONStructured data (extracted fields, key-value pairs) to include in the response.Text_With_SourcesTextWithSourcesText paired with citations, formatted for LLM consumption. You can add your own named input fields for any supported type -- see Named Inputs and Outputs for the full list of supported primitive and framework types and instructions for adding custom fields. Outputs OutputTypeDescriptionresponseTextThe generated response. Configurations ParameterDescriptionDefaultinstructionsInstructions that guide the response style, tone, and content.NonemodelOverride EmaFusion model selection.EmaFusion defaulttemperatureLLM temperature.0.0 Type-Aware Input Handling Because Respond to a Query uses the platform Type System, each input type is prepared for LLM consumption according to its type contract: SearchResults are flattened with snippet text, source metadata, and relevance scores so the model can cite specific passages. Documents are passed with their extracted text content; the model can reference sections by name. Conversation history is formatted as turn-by-turn dialogue, allowing the model to track references like "the order I mentioned earlier." Entities (JSON) are rendered as structured key-value pairs the model can embed in the response. Text with Sources is presented with inline citation markers. This means you do not need intermediate formatting agents between typed upstream data and Respond to a Query. Choosing the Right Response Agent Use Respond to a Query when you need to synthesize multiple input types, or when your input combination is non-standard. Use Respond using Search Results when your input is purely search results and you need inline citations out of the box. Use Respond using Action Calling Results when your input is tool execution results from Intelligent Actions. Use Fixed Response when the response is deterministic and template-based. How to Use This Agent Synthesize search results and extracted entities into a single grounded response: trigger -> knowledge_search --------\ -> extract_entities --------> respond_to_a_query -> workflow_output Combine conversation history with a document reference: chat_trigger -> conversation_summarizer ---\ -> document_synthesis ---> respond_to_a_query -> workflow_output Related Agents Respond using Search Results -- optimized for search-grounded responses with citations. Respond using Action Calling Results -- for formatting tool execution results. Custom Agent -- for arbitrary LLM tasks beyond response generation. Fixed Response -- for deterministic, template-based responses.

================================================================================
# Respond using Action Calling Results Agent
URL: https://builder.ema.ai/agent-reference/core/respond-using-action-calling-results
================================================================================

Respond using Action Calling Results Agent The Respond using Action Calling Results agent formats and narrates the outputs of external tool executions into human-readable responses. It takes raw tool call results and produces a clear explanation of what actions were performed and what the outcomes were. This agent is the standard downstream component in the action calling pipeline: Trigger → Intelligent Actions → Respond using Action Calling Results → Output. Use Cases Your workflow calls the Intelligent Actions agent and you need to present the results to a user. You want to convert raw API response data into a natural language summary. The user needs confirmation of actions taken on their behalf. Your Intelligent Actions agent calls tools across multiple applications and you need a unified, readable summary of all results. Inputs InputTypeDescriptionaction_resultsJSONThe raw results from tool executions (typically from the Intelligent Actions agent). When the upstream agent executes multiple tools, this contains all results.contextText(Optional) Additional context about the user's original request. Providing the original query helps the agent frame results in terms the user understands. Outputs OutputTypeDescriptionresponseTextA natural language summary of the actions taken and their results. Configurations ParameterDescriptionDefaultinstructionsAdditional formatting or tone instructions. For example: "Summarize in bullet points", "Use a professional tone", or "Include the record ID in the confirmation."None Building an Action Calling Pipeline The action calling pipeline is a common workflow pattern that connects user intent to external system actions and back to a user-friendly response. The typical pipeline is: Trigger -- A chat message, ticket, or scheduled event starts the workflow. Intelligent Actions -- Interprets the request, selects the appropriate tool(s), and executes the API calls. Respond using Action Calling Results -- Reads the raw tool output and the original request, then generates a clear confirmation or summary for the user. Output -- The response is delivered via chat, ticket comment, or email. This pipeline can be extended with additional agents upstream (e.g., Extract Entities to gather parameters) or downstream (e.g., Response Validator to quality-check the summary before sending). How to Use This Agent Single-tool action with confirmation: chat_trigger -> intelligent_actions("Update customer status to Active") -> respond_using_action_calling_results -> workflow_output Multi-tool action across systems: chat_trigger -> intelligent_actions("Look up order in Shopify and create a return label in ShipStation") -> respond_using_action_calling_results -> workflow_output Related Agents Intelligent Actions -- the upstream agent that produces the action results. Respond to a Query -- for general response generation not tied to action results. Response Validator -- for validating the generated summary before it reaches the user.

================================================================================
# Respond using Search Results Agent
URL: https://builder.ema.ai/agent-reference/core/respond-using-search-results
================================================================================

Respond using Search Results Agent Deprecation Notice: This agent is deprecated. Use the Respond to a Query Agent instead. The Respond using Search Results agent generates a response grounded in provided search results. It combines the query and search results, generates an answer using that context, and returns a single response_with_sources output containing both the response text and the retained sources. Use Cases Your workflow searches a knowledge base and needs to generate a cited response. You want responses that are grounded in source documents, not based on the LLM's training data alone. You want the output to preserve the specific sources used to support the answer. Inputs InputTypeRequiredDescriptionqueryTextWithSourcesYesThe query or prompt to answer. Any sources already attached to the query are merged with search_results.search_resultsSearchResultsYesThe search results used as the grounding context for the response.user_instructionsTextNoOptional instructions for tone, format, or response behavior. Outputs OutputTypeDescriptionresponse_with_sourcesTextWithSourcesThe generated response. The text is returned in text and the retained sources are returned in sources on the same object. Configurations ParameterDescriptionDefaultuser_instructionsAdditional instructions for how the response should be written.Emptyse_guidelinesAdditional hidden search experience guidance appended to the system prompt.Emptyprocess_entire_documentUse entire matched documents instead of only matched segments or chunks.falseglossaryGlossary terms to guide terminology and domain language.Noneuser_tagsUser tags that can help prioritize more relevant results.Nonereranking_percentile_thresholdFilters retained sources by semantic similarity to the generated answer.0 (disabled)use_citation_based_filteringUses structured output so the model identifies which sources it actually used.trueno_search_results_responseFixed fallback response used when no search results are available.Built-in default messageuse_clarifying_questionAllows the model to return a clarifying-question style response when the query is too ambiguous.falseclarify_question_user_instructionsAdditional instructions for clarifying-question behavior.Emptydisable_sourcesClears sources from the final output even though search results are still used during generation.false How to Use This Agent chat_trigger -> knowledge_search -> respond_using_search_results -> workflow_output Related Agents Knowledge Search -- the standard upstream provider of search results. Respond to a Query -- for general response generation from any inputs. Combine Search Results -- for merging results from multiple searches. Rerank Search Results -- for improving result relevance before response generation.

================================================================================
# Response Validator Agent
URL: https://builder.ema.ai/agent-reference/core/response-validator
================================================================================

Response Validator Agent The Response Validator agent validates generated responses against configurable quality and compliance criteria. It evaluates a response and returns a pass/fail judgment with specific issues identified when validation fails. Use this agent as a quality gate in any workflow where AI-generated content must meet defined standards before reaching the end user. Use Cases You need automated quality checks on AI-generated responses before they reach the user. Compliance rules require that responses meet specific criteria (no PII, no unauthorized claims, appropriate tone). You want to gate responses and route failures to human review or a retry loop. You want to validate that action calling results or search-grounded responses meet accuracy and formatting standards before delivery. Inputs InputTypeDescriptionresponseTextThe response to validate.queryText(Optional) The original query, for relevance checking.search_resultsSearchResults(Optional) The source material, for grounding checks. Outputs OutputTypeDescriptionis_validBooleanWhether the response passed all validation criteria.issuesTextDescription of any validation failures. Empty if valid. Configurations ParameterDescriptionDefaultcriteriaList of validation criteria. Each criterion has a name, description, and severity.RequiredinstructionsAdditional validation instructions.None Defining Validation Criteria Each criterion is defined in natural language with a name and description. Common validation patterns include: Grounding -- "The response must be supported by the provided search results. Do not include claims that are not backed by a source." Tone and brand compliance -- "The response must use a professional, empathetic tone. Avoid jargon or overly casual language." PII protection -- "The response must not include personal identifiable information such as email addresses, phone numbers, or account numbers." Relevance -- "The response must directly address the user's query. Flag responses that go off-topic or provide unrequested information." Completeness -- "The response must fully answer the question. If partial information is available, the response should acknowledge what is missing." Quality Gating Patterns The Response Validator is typically used as a quality gate between a response agent and the workflow output. When validation fails, you can: Route to human review -- Send invalid responses to a human reviewer via the Human Collaboration agent. Abstain from answering -- Suppress the response entirely using the Abstain from Answering agent and return a safe fallback message. Branch on severity -- Use the is_valid output as a condition to branch the workflow: valid responses proceed to output, while invalid responses take an alternate path. How to Use This Agent Quality gate with human fallback: chat_trigger -> knowledge_search -> respond_using_search_results -> response_validator -> [valid] -> workflow_output -> [invalid] -> human_collaboration -> workflow_output Validate action calling results before delivery: chat_trigger -> intelligent_actions -> respond_using_action_calling_results -> response_validator -> [valid] -> workflow_output -> [invalid] -> abstain_from_answering -> workflow_output Related Agents Rule Validation -- validates documents or data against rule sets (not specifically responses). Abstain from Answering -- for suppressing responses entirely. Human Collaboration -- for routing failed validations to human review. Respond using Search Results -- a common upstream agent whose output benefits from validation. Respond using Action Calling Results -- validate action summaries before they reach the user.

================================================================================
# Rule Validation Agent
URL: https://builder.ema.ai/agent-reference/core/rule-validation
================================================================================

Rule Validation Agent The Rule Validation agent validates documents or data against a defined set of rules. Each rule is evaluated independently, and the agent returns a pass/fail result for each rule along with an overall verdict. Use Cases You need to check whether a document or dataset complies with a set of business rules. A compliance workflow requires systematic rule-by-rule evaluation. You want structured pass/fail output for auditing purposes. Inputs InputTypeDescriptiondocumentDocumentThe document to validate against the rules.textText(Alternative) Plain text to validate.dataJSON(Alternative) Structured data to validate. Outputs OutputTypeDescriptionoverall_resultBooleantrue if all rules pass, false if any rule fails.rule_resultsJSONPer-rule results with rule name, pass/fail, and explanation. Configurations ParameterDescriptionDefaultrulesList of rules to evaluate. Each rule has a name, description, and evaluation criteria.Requiredfail_on_anyWhether to fail the overall result if any single rule fails.true Deterministic Validation The Rule Validation agent supports deterministic validation -- conditions that evaluate extracted data against rules without using an LLM. This is useful for exact checks like "does the PO amount match the invoice amount?" or "is the date within range?" You can define deterministic validations in two modes: Condition Mode A visual rule builder where you define conditions using extracted variables: LHS (Data field) -- reference extracted fields using double curly braces: {{field_name}}. Chain methods on fields: {{field_name}}.method1(arg1).method2(arg2). Operator -- compatible operators are shown based on the field type. RHS (Value) -- a fixed value, another variable, or a static function like $now(). Examples: {{PO Amount}} == {{Invoice Amount}} {{Invoice Date}}.plus(30, "days") > $now() {{Vendor Name}}.lower() == "acme corp" {{PO Quantity}} >= {{Invoice Quantity}} Currently, you can chain conditions with either ANDs or ORs, but not both in the same rule. Supported operators by type: TypeOperatorsBoolean==, !=Number==, !=, >, >=, <, <=, in, not inString==, !=, substring, not substring, contains substring, does not contain substring, in, not in, substring in any of, substring not in any ofDatetime>, >=, <, <=, in, not in Available functions: FunctionReturnsDescription$now()DatetimeCurrent date and time.day()NumberDay of the month (1-31).month()NumberMonth of the year (1-12).year()NumberThe year.hour()NumberHour of the day (0-23).plus(n, interval)DatetimeAdds a duration (seconds, minutes, hours, days, weeks, months, years).minus(n, interval)DatetimeSubtracts a duration.plus(n) (number)NumberAdds n to the number.minus(n) (number)NumberSubtracts n from the number.lower()StringConverts to lowercase Code Mode For more complex validation logic, switch to the Code tab for a JavaScript editor: Extracted fields are available as inputs.field_name. For boolean rules: return "true" or "false" as a string. For numerical rules: return a number. Use log.info(), log.warning(), or log.error() for Show Work visibility. // Boolean validation with tolerance function main(inputs) { var poAmount = inputs.PO_Amount; var invoiceAmount = inputs.Invoice_Amount; if (poAmount === undefined || invoiceAmount === undefined) { log.warning("Missing amount fields"); return "false"; } var tolerance = 0.01; var passed = Math.abs(poAmount - invoiceAmount) <= tolerance; log.info(passed ? "Amounts match" : "Mismatch: PO=" + poAmount + ", Invoice=" + invoiceAmount); return passed ? "true" : "false"; } // Numerical scoring function main(inputs) { var score = 0; if (inputs.PO_Amount === inputs.Invoice_Amount) score += 40; if (inputs.PO_Quantity === inputs.Invoice_Quantity) score += 30; if (inputs.PO_Unit_Price === inputs.Invoice_Unit_Price) score += 30; log.info("Validation score: " + score); return score; } How to Use This Agent Validate an insurance claim document against policy rules: document_trigger -> rule_validation -> [pass] -> intelligent_actions("Approve claim") -> [fail] -> human_collaboration -> workflow_output Related Agents Response Validator -- for validating AI-generated responses specifically. Extract Entities -- for extracting data from documents before rule validation. Custom Code Agent -- for standalone JavaScript logic outside of rule validation context.

================================================================================
# Sales Intelligence Agent
URL: https://builder.ema.ai/agent-reference/core/sales-intelligence
================================================================================

Sales Intelligence Agent The Sales Intelligence agent retrieves financial and company data from external APIs. It provides access to company profiles, financial statements, news, and market data to support sales research and due diligence workflows. Use Cases A sales or research AI Employee needs to look up company information before outreach. You need to pull financial data for account research, lead qualification, or deal preparation. Your workflow requires real-time company or market data from public sources. Inputs InputTypeDescriptionqueryTextThe company name, ticker symbol, or research question. Outputs OutputTypeDescriptiondataJSONThe retrieved financial or company data.summaryTextA natural language summary of the findings. Configurations ParameterDescriptionDefaultdata_providersWhich financial data providers to query.All configured providers How to Use This Agent trigger -> sales_intelligence("Look up {{company_name}}") -> custom_agent("Draft a personalized outreach email") -> send_email Related Agents Deep Web Search -- for broader web research beyond financial data. Intelligent Actions -- for querying CRM data about existing accounts.

================================================================================
# Send Email Agent
URL: https://builder.ema.ai/agent-reference/core/send-email
================================================================================

Send Email Agent The Send Email agent sends emails with support for attachments, CC/BCC recipients, HTML formatting, and read tracking. It is the dedicated agent for email delivery -- prefer it over the Intelligent Actions agent for sending emails. Use Cases Your workflow needs to send an email as its final action. You need to include attachments, HTML formatting, or read receipts. You want explicit control over email recipients, subject, and body. Inputs InputTypeDescriptiontoTextRecipient email address(es).subjectTextEmail subject line.bodyTextEmail body content (plain text or HTML).attachmentsDocument[](Optional) Files to attach.ccText(Optional) CC recipient(s).bccText(Optional) BCC recipient(s). Outputs OutputTypeDescriptionstatusTextDelivery status (sent, failed, etc.). Configurations ParameterDescriptionDefaultfrom_addressThe sender email address.AI Employee's configured emailhtml_enabledWhether to send the body as HTML.false How to Use This Agent ticket_trigger -> knowledge_search -> respond_using_search_results -> send_email -> workflow_output Related Agents Intelligent Actions -- for other communication channels (Slack, Teams, etc.). Generate Document -- for creating document attachments.

================================================================================
# Sentiment Analyzer Agent
URL: https://builder.ema.ai/agent-reference/core/sentiment-analyzer
================================================================================

Sentiment Analyzer Agent Notice: This agent is not currently registered as a standalone action in the platform. The functionality described may be available through the Custom Agent with appropriate prompt configuration. The Sentiment Analyzer agent performs detailed sentiment classification with nuance and sub-category detection. Unlike the simpler Feedback Sentiment Analyzer, it provides granular sentiment labels and can detect multiple sentiment dimensions in a single input. Use Cases You need fine-grained sentiment analysis beyond positive/negative. Your workflow branches based on specific emotional tones in customer communications. You want to track customer sentiment trends across interactions. Inputs InputTypeDescriptiontextTextThe text to analyze for sentiment.contextText(Optional) Additional context for more accurate analysis. Outputs OutputTypeDescriptionsentimentTextThe primary sentiment label (positive, negative, neutral, mixed).sub_sentimentsJSONDetailed sub-categories with confidence scores. Configurations ParameterDescriptionDefaultcategoriesCustom sentiment categories to classify into.Default set (positive, negative, neutral, mixed)instructionsAdditional analysis guidance.None How to Use This Agent ticket_trigger -> convert_to_text -> sentiment_analyzer -> [frustrated/urgent] -> human_collaboration("Priority escalation") -> workflow_output -> [positive/neutral] -> knowledge_search -> respond -> workflow_output Related Agents Feedback Sentiment Analyzer -- simpler positive/negative/none classification. Categorize Conversations and Route -- for intent-based routing rather than sentiment-based.

================================================================================
# Tag Extractor Agent
URL: https://builder.ema.ai/agent-reference/core/tag-extractor
================================================================================

Tag Extractor Agent The Tag Extractor agent identifies and extracts relevant tags from a given context, such as user queries, chat conversations, or documents. These tags can then be used for categorization, routing, personalization, or downstream automation. The agent supports tag mapping so that extracted values are automatically aligned with predefined dictionaries or default values. Use Cases Search & Retrieval -- Extract tags from queries to improve relevance in knowledge base or document searches. Conversation Intelligence -- Identify key entities (e.g., location, product type, department) from chat transcripts. Personalization -- Extract user preferences and context tags to tailor responses or recommendations. Routing & Categorization -- Direct queries to the right workflows or departments based on detected tags. Analytics -- Enable structured tagging of unstructured text for easier reporting and insights. Inputs InputTypeRequiredDescriptionconversationConversationYesThe text input (e.g., chat conversation or user query) from which tags will be extracted.tag_extraction_configsArray of Tag Extraction ConfigsYesTag dimensions with extraction rules. Each config specifies a tag dimension name and rules containing tag level, extraction key, and default value.tag_mappingsJSONNoOptional dictionary mapping extracted tag values to different values (e.g., mapping "Band" to a dictionary value "band" with a default of "C"). Outputs OutputTypeDescriptiontagsArray of StringsExtracted tags as structured key-value pairs (e.g., Location:India:Bengaluru, Department:Sales). Includes dictionary values and defaults where applicable. Configurations None. Tag extraction behavior is determined entirely by the tag_extraction_configs input and optional tag_mappings. How to Use This Agent ticket_trigger -> convert_to_text -> tag_extractor -> intelligent_actions("Apply tags to ticket") -> workflow_output Related Agents Extract Entities -- for extracting structured data rather than tags. Text Categorizer -- for single-category classification rather than multi-tag extraction.

================================================================================
# Text Categorizer Agent
URL: https://builder.ema.ai/agent-reference/core/text-categorizer
================================================================================

Text Categorizer Agent Note: The original version of this agent (v0) is deprecated. For new workflows, use the Categorizer agent instead, which accepts text and any other input type via named inputs. Existing workflows using Text Categorizer continue to work. The Text Categorizer agent classifies plain text into user-defined categories using AI. It is a streamlined categorization agent for when your input is already in text form and you need single-category classification. Use Cases You have plain text input that needs to be classified into one of several categories. Your text has already been converted from another format (e.g., via Convert to Text) and needs classification. You want simple text classification without the overhead of configuring named inputs. Inputs InputTypeDescriptiontextTextThe text to classify. Required -- the agent returns the fallback category if this is empty.Additional inputsVarious (optional)You can wire additional context from other agents as supplemental inputs. The agent considers these alongside the primary text. Outputs OutputTypeDescriptioncategoryCategoryThe assigned category name. Each category produces a branch edge on the GWE canvas. Configurations ParameterDescriptionDefaultCategoriesList of categories with names and descriptions (up to 1,000 characters each).RequiredFallback categoryCategory assigned when the text is empty or no category matches. Defaults to "Fallback."RequiredInstructionsAdditional classification guidance for the LLM.NoneQualification criteriaDeterministic rules per category. Requires a JSON Extractor upstream to supply structured data.NoneProcess entire documentWhen supplemental document inputs are wired, controls whether the full content is sent to the LLM.Off How to Use This Agent document_trigger -> convert_to_text -> text_categorizer -> [urgent] -> human_collaboration -> [routine] -> knowledge_search -> respond -> [spam] -> abstain_from_answering Text Categorizer vs. Categorizer The Categorizer (v1) supersedes the Text Categorizer (v0). Key differences: FeatureText CategorizerCategorizerPrimary inputPlain text (required)Any type via named inputsMultiple input typesLimited supplemental inputsFull named inputs supportCustom instructionsBasic instructions fieldRich categorization instructionsStatusDeprecated (v0)Current (v1) Related Agents Categorizer -- the recommended replacement. More flexible, accepts any input type. Document Categorizer -- for classifying document objects directly (also deprecated). Categorize Conversations and Route -- for classifying chat conversations.

================================================================================
# Thread Categorizer Agent
URL: https://builder.ema.ai/agent-reference/core/thread-categorizer
================================================================================

Thread Categorizer Agent The Thread Categorizer agent classifies support ticket threads based on their content. It reads the ticket's title, description, and recent comments to assign the most appropriate category from your configured list. Use Cases Your ticketing workflow needs to classify incoming tickets by type (e.g., billing, technical, account). You want to route tickets to different handling workflows based on content. You need to auto-categorize a backlog of existing tickets. Inputs InputTypeDescriptionthreadThreadThe support ticket thread, including its title, description, and comment history.Additional inputsVarious (optional)You can wire supplemental context from other agents (e.g., extracted entities, customer data). This additional context is included alongside the ticket when making the classification decision. What the Agent Reads The agent considers the following from the ticket thread: Title -- the ticket subject line. Description -- the initial ticket body. Recent comments -- the most recent messages in the thread, limited by the context window. Both customer replies and agent responses are included. Additional inputs -- any supplemental context wired from upstream agents. Outputs OutputTypeDescriptioncategoryCategoryThe assigned category name. Each category produces a branch edge on the GWE canvas. Configurations ParameterDescriptionDefaultCategoriesList of categories with names and descriptions (up to 1,000 characters each).RequiredFallback categoryCategory assigned when no category matches. Must be one of the defined categories. Defaults to "Fallback."RequiredContext windowNumber of recent comments to include from the thread. Older comments are excluded.10InstructionsAdditional classification guidance for the LLM.NoneQualification criteriaDeterministic rules per category. Requires a JSON Extractor upstream to supply structured data.None How to Use This Agent ticket_trigger -> thread_categorizer -> [billing] -> billing_search -> respond -> mark_as_public_response -> [technical] -> tech_search -> respond -> mark_as_public_response -> [account] -> human_collaboration -> [other] -> general_search -> respond -> mark_as_public_response Tips Write category descriptions based on ticket content, not workflow actions. Describe what the ticket looks like ("Customer reporting incorrect charges or payment failures"), not what you'll do with it ("Route to billing team"). Wire additional context when ticket content alone is insufficient. For example, if you've already extracted customer tier or product line from a CRM lookup, wire that in as supplemental context. Keep the context window at 10 for most use cases. Long ticket threads often contain back-and-forth that adds noise. Increase it only if early messages carry critical classification signals. Related Agents Categorize Conversations and Route -- for chat conversations rather than ticket threads. Text Categorizer -- for plain text classification. Thread Summarizer -- for summarizing threads rather than categorizing them.

================================================================================
# Thread Summarizer Agent
URL: https://builder.ema.ai/agent-reference/core/thread-summarizer
================================================================================

Thread Summarizer Agent The Thread Summarizer agent reads a support ticket thread and produces a concise summary that captures the customer's issue, actions taken, current status, and any outstanding items. Use Cases A downstream agent needs a concise summary of a ticket rather than the full thread. You want to include a ticket summary in an email notification, Slack message, or escalation. A human reviewer needs a quick overview before deciding on an action. You need to pass ticket context to a search agent without overwhelming it with the full thread. Inputs InputTypeDescriptionthreadThreadThe support ticket thread to summarize, including title, description, and comment history. Outputs OutputTypeDescriptionsummaryTextA concise summary of the ticket thread. Configurations ParameterDescriptionDefaultComment windowNumber of recent comments to include from the thread. Older comments are excluded from the summary.10InstructionsCustom guidance for the summarizer (e.g., "Focus on the resolution status" or "Include any mentioned deadlines").NoneSummarize without LLMWhen enabled, returns a structured representation of the ticket data instead of a narrative summary. Useful when you need raw ticket fields for downstream processing rather than a human-readable summary.Off What the Summary Includes The LLM-generated summary typically covers: Issue -- what the customer reported or requested. Actions taken -- what has been done so far in the thread. Current status -- where things stand (resolved, pending, escalated). Outstanding items -- anything still unresolved or awaiting a response. The exact structure depends on the ticket content and any custom instructions you provide. How to Use This Agent Summarize a ticket before searching for relevant knowledge: ticket_trigger -> thread_summarizer -> knowledge_search -> respond_using_search_results -> workflow_output Include a summary in an escalation notification: ticket_trigger -> thread_summarizer -> send_email (to: escalation team) Tips Use custom instructions to shape the summary for its downstream consumer. A summary feeding a search agent should emphasize the core question, while a summary for a human reviewer should emphasize status and next steps. Keep the comment window reasonable. Very long threads with dozens of back-and-forth messages produce better summaries when the window is limited to the most recent and relevant exchanges. Use "Summarize without LLM" when you need structured ticket data (title, description, comments) passed through without interpretation -- for example, as input to a Custom Code Agent that applies its own logic. Related Agents Conversation Summarizer -- for summarizing chat conversations. Produces a search query rather than a narrative summary. Thread Categorizer -- for categorizing threads rather than summarizing them.

================================================================================
# Deprecated Agents
URL: https://builder.ema.ai/agent-reference/deprecated
================================================================================

Deprecated Agents The following agents have been superseded by newer implementations. They remain available for backward compatibility but should not be used in new workflows. When you open a workflow containing a deprecated agent, a yellow warning banner appears on the agent node. Migration Guide Deprecated AgentReplacementNotesIntent ClassifierCategorize Conversations and RouteRenamed and enhanced with example query matching, multi-intent detection, and human collaboration. Existing workflows continue to work.External Tool CallerIntelligent ActionsRenamed and expanded to support 200+ integrations. Existing workflows continue to work.Text Categorizer (v0)CategorizerThe Categorizer (v1) accepts any input type via named inputs, not just text. Existing Text Categorizer workflows continue to work.Document CategorizerCategorizerThe Categorizer accepts documents via named inputs alongside other data. Existing Document Categorizer workflows continue to work.search/v0Knowledge SearchThe v0 search action is deprecated. Migrate to the current Knowledge Search agent.respond_with_sources/v0Respond using Search ResultsThe v0 respond action is deprecated. Use the current Respond using Search Results agent.combine_search_results/v0Combine Search ResultsMigrate to the current version.combine_text_with_sources/v0Combine TextMigrate to the current version.fixed_response/v0Fixed ResponseMigrate to the current version.custom_agent/v0Custom AgentMigrate to the current version.generate_document/v0Generate DocumentMigrate to the current version.rule_validation_with_documents/v0Rule ValidationMigrate to the current version.json_mapper/v0JSON ExtractorMigrate to the current version.general_hitl/v0Human CollaborationMigrate to the current version. Identifying Deprecated Agents in Existing Workflows When editing a workflow that contains a deprecated agent, the GWE canvas displays a yellow warning banner on the agent node: "You are using an agent version that is deprecated." The validation system also flags deprecated agents during pre-deploy checks. To migrate: Note the deprecated agent's input and output bindings. Replace the action with the recommended replacement from the table above. Rewire the inputs and outputs -- the replacement agents typically accept the same or similar bindings. Test the workflow to verify behavior is preserved. For additional detail on deprecated action versions and migration patterns, see the internal agent reference supplement.

================================================================================
# Specialized Agents Catalog
URL: https://builder.ema.ai/agent-reference/specialized
================================================================================

Specialized Agents Catalog Specialized agents are pre-trained variants of the Custom Agent optimized for specific industry or domain tasks. They encapsulate domain expertise, prompt engineering, and output formatting tailored to particular use cases. Specialized agents accept the same named inputs system as the Custom Agent but come with built-in instructions, domain terminology, and output structures. You can use them as drop-in replacements for a Custom Agent when the use case matches. How Specialized Agents Work Each specialized agent is a Custom Agent with: Pre-built instructions -- domain-specific prompts developed and tested by Ema's team. Optimized output formatting -- structured outputs tailored to the domain (e.g., medical assessments follow clinical formatting, legal analyses follow case citation standards). Domain vocabulary -- the agent understands industry-specific terminology out of the box. You can further customize a specialized agent by adding your own instructions on top of the built-in ones. Catalog Content & Marketing AgentDescriptionEmail WriterGenerates professional, source-grounded emails with configurable tone, format, and audience awareness.Newsletter WriterCreates newsletter content with sections, headlines, and calls to action.Personalized Content GeneratorProduces personalized content variants based on audience attributes and context.PRD WriterWrites comprehensive product requirements documents grounded in search results and product inputs.SOPs BuilderGenerates standard operating procedures from process descriptions and guidelines. Healthcare & Medical AgentDescriptionMedical Assessment CreatorGenerates structured medical assessments from clinical data and patient information.Medical Evidence SummarizerAnalyzes and synthesizes medical literature into structured, evidence-based summaries.Medical Research OrganizerOrganizes and categorizes medical research literature by topic, methodology, and findings.Patient Insights AnalyzerAnalyzes patient data to extract clinical insights and trends. Legal & Compliance AgentDescriptionLegal ExpertProvides legal analysis and guidance based on jurisdiction-specific regulations and case law.Compliance Document AnalyzerAnalyzes documents for regulatory compliance across frameworks (SOC 2, HIPAA, GDPR, etc.).Audit Evidence VerifierVerifies audit evidence through tracing and vouching against transactional data. Finance & Accounting AgentDescriptionFinancial Statement AnalyzerAnalyzes financial statements and produces insights on revenue, expenses, margins, and trends. IT & Security AgentDescriptionTechnical Support SpecialistHandles technical support queries with troubleshooting steps, knowledge base integration, and escalation logic.Cybersecurity ExpertProvides cybersecurity analysis, threat assessment, and security recommendation guidance. Note: The specialized agents catalog is actively expanding. Check your workspace's agent library for the current list of available specialized agents. Using a Specialized Agent To use a specialized agent in a workflow: Add an action to your workflow on the GWE canvas. Select the specialized agent from the agent library. Wire the required named inputs (same as the Custom Agent). Optionally add custom instructions to supplement the built-in behavior. Specialized agents are interchangeable with the Custom Agent. If a specialized agent does not fully meet your needs, you can switch to the Custom Agent and incorporate elements of the specialized agent's approach in your custom instructions.

================================================================================
# Audit Evidence Verifier Agent
URL: https://builder.ema.ai/agent-reference/specialized/audit-evidence-verifier
================================================================================

Audit Evidence Verifier Agent The Audit Evidence Verifier agent analyzes audit evidence by tracing it to transactional records and vouching transactions back to original source documentation. It is designed for audit, assurance, and financial review workflows where evidence validation must be systematic and traceable. Use Cases Tracing audit evidence to transactional records for completeness. Vouching transactions back to original source documentation. Identifying discrepancies, gaps, or unsupported transactions. Supporting audit readiness and compliance verification. Inputs InputTypeRequiredDescriptionqueryTextYesThe audit scope, transaction set, or verification request.search_resultsSearchResultsYesAudit evidence and transactional data from upstream search agents.instructionsTextNoGuidance specifying audit focus or reporting format. Outputs OutputTypeDescriptionresponseTextA structured audit verification report including: traced evidence findings, vouched transaction confirmations, identified discrepancies, and key audit insights. Configurations ParameterDescriptionDefaultno_search_results_responseCustom response when audit evidence is insufficient.None How to Use This Agent document_trigger -> knowledge_search -> audit_evidence_verifier -> human_collaboration -> workflow_output Related Agents Rule Validation -- for deterministic rule-based validation of extracted data. Extract Entities -- for extracting structured audit data before verification.

================================================================================
# Email Writer Agent
URL: https://builder.ema.ai/agent-reference/specialized/email-writer
================================================================================

Email Writer Agent The Email Writer agent generates high-quality, professional email responses grounded in search results. It ensures outbound or reply emails are traceable to source documentation -- company policies, knowledge bases, or trusted references -- rather than relying on the LLM's general knowledge. This agent is typically used as a final step after Search, Web Search, or Combine Search Results agents in email-centric workflows. Use Cases Writing customer-facing or internal email responses grounded in retrieved documentation. Generating professional email replies to inquiries using company knowledge bases. Automating email drafting in support, sales, operations, or partner workflows. Ensuring email communication is accurate, consistent, and traceable to source material. Inputs InputTypeRequiredDescriptionqueryTextWithSourcesYesThe email context or question that needs to be addressed.search_resultsSearchResultsYesRelevant search results used as source material, from Search, Web Search, or Combine Search Results agents.user_instructionsTextNoGuidance for tone, emphasis, or formatting preferences. Outputs OutputTypeDescriptionresponse_with_sourcesTextWithSourcesA fully composed email with subject line (8 words max), greeting, concise body (3-6 sentences), closing, and signature block. Configurations ParameterDescriptionDefaultmodel_configFusion model configuration used to generate the email response.Requiredprocess_entire_documentWhen enabled, processes entire documents instead of only matching segments from search results.None How to Use This Agent Customer support email automation: chat_trigger -> knowledge_search -> email_writer -> send_email -> workflow_output Known Limitations Timezone handling: Date and time references use the system default timezone and do not account for user-specific timezone preferences. Related Agents Respond using Search Results -- for general responses (not specifically email-formatted). Send Email -- for delivering the composed email; use downstream of this agent.

================================================================================
# Medical Evidence Summarizer Agent
URL: https://builder.ema.ai/agent-reference/specialized/medical-evidence-summarizer
================================================================================

Medical Evidence Summarizer Agent The Medical Evidence Summarizer agent analyzes and synthesizes medical literature into structured, evidence-based summaries. It is designed for clinical research, medical writing, and evidence review workflows where accuracy and traceability to source publications are critical. Use Cases Summarizing peer-reviewed medical studies and clinical research articles. Extracting key findings and clinical implications from medical literature. Supporting evidence-based clinical decision-making with concise summaries. Comparing findings across multiple studies. Identifying research gaps and limitations in existing medical evidence. Inputs InputTypeRequiredDescriptionqueryTextYesThe research question, topic, or focus area for the medical evidence review.search_resultsSearchResultsYesMedical literature, study reports, or research articles from upstream search agents.instructionsTextNoGuidance to control depth, audience, or emphasis. Outputs OutputTypeDescriptionresponseTextA structured summary including: study overview, methodology assessment, key clinical findings, clinical relevance, comparison with existing evidence, and identified limitations. Configurations ParameterDescriptionDefaultno_search_results_responseCustom response when no relevant medical literature is available.None How to Use This Agent chat_trigger -> knowledge_search -> medical_evidence_summarizer -> workflow_output Related Agents Respond using Search Results -- for general-purpose responses from search results. Knowledge Search -- for searching medical literature knowledge bases upstream.

================================================================================
# PRD Writer Agent
URL: https://builder.ema.ai/agent-reference/specialized/prd-writer
================================================================================

PRD Writer Agent The PRD Writer agent generates comprehensive Product Requirements Documents grounded in search results. It translates research, proposals, and stakeholder inputs into structured PRDs suitable for cross-functional alignment and product planning. Use Cases Creating complete Product Requirements Documents based on sourced product inputs. Translating research, proposals, and stakeholder inputs into structured PRDs. Standardizing PRD creation across teams and initiatives. Documenting product scope, use cases, and launch considerations using verified inputs. Inputs InputTypeRequiredDescriptionqueryTextWithSourcesYesThe product initiative, feature, or project to be documented.search_resultsSearchResultsYesRelevant product materials (research, proposals, design notes, planning documents) from upstream search agents.user_instructionsTextNoGuidance to control emphasis, structure, or prioritization. Outputs OutputTypeDescriptionresponse_with_sourcesTextWithSourcesA fully structured PRD including: ownership, related documentation, overview (opportunity, background, use cases, success metrics), proposal details with UX descriptions, prioritized features, launch considerations, and references. Configurations ParameterDescriptionDefaultmodel_configFusion model configuration used to generate the PRD response.Requiredprocess_entire_documentWhen enabled, processes entire documents instead of only matching segments from search results.None How to Use This Agent chat_trigger -> knowledge_search -> prd_writer -> generate_document -> workflow_output Related Agents Custom Agent -- for ad-hoc document generation when PRD format is not needed. Generate Document -- for converting the PRD output to a formatted .docx file.

================================================================================
# Autopilot
URL: https://builder.ema.ai/autopilot
================================================================================

Autopilot Tutorial: How to Use Autopilot What is Autopilot? Autopilot is the built-in assistant that lives on every page of the Ema platform. Instead of navigating through menus and settings to configure your AI Employees (AIEs), you can describe what you need in plain language and Autopilot handles the rest — from building and editing AIEs to testing conversations, managing data, and answering platform questions. Autopilot is aware of the page you are currently viewing, so its responses are always grounded in your current context. Whether you are reviewing a list of AI Employees, configuring a workflow, or browsing integrations, Autopilot picks up where you are and works from there. What the documentation covers: What Autopilot is & how to open it — the floating button, side panel, expanded view, recent chats, and starting new conversations Core actions — creating, editing, and testing AI Employees, managing data, generating documents, connecting integrations, organizing groups, and more Permissions & scoping — what Autopilot can access, when it asks for approval, and what happens when something is out of scope Tips, limits & examples — example prompts, keyboard shortcuts, Fast and Thorough mode, file uploads, feedback, and troubleshooting Opening Autopilot You can open Autopilot from anywhere in the platform using the floating button, or from a dedicated entry point on the AI Employees page. The floating button A small green Ema logo button sits in the bottom-right corner of every page. This is the fastest way to reach Autopilot. Look for the green Ema icon in the bottom-right corner of any page. Hovering over it shows the tooltip “Hey, this is Ema Autopilot” with the message “Describe what you want to build — I’ll handle the rest.” Click the button to open the Autopilot side panel on the right side of the screen. From the AI Employees page The AI Employees page offers a second entry point tailored for building from scratch. Navigate to the AI Employees page. Find the banner with the “Build your own AI Employee” button. Click “Build your own AI Employee”. Autopilot opens directly in expanded view and automatically sends the message “Help me build a new AI Employee from scratch.” on your behalf. This entry point skips the side panel and starts you in a full-screen conversation with a clear starting prompt, so you can jump straight into building. The Autopilot interface Autopilot has two viewing modes — a compact side panel for quick tasks and an expanded view for longer conversations — plus built-in history so you never lose your work. Side panel and expanded view When you first open Autopilot from the floating button, it appears as a side panel: a fixed right sidebar that stays visible alongside the page you are working on. This is ideal for short questions or quick edits while you keep your current page in view. For more involved work, switch to the expanded view, which takes over the full screen with a centered chat column. This gives you more room to read long responses, review generated configurations, or work through multi-step builds. To toggle between the two views: Click the Expand button in the side panel header to switch to expanded view. Click the Collapse button in the expanded view header to return to the side panel. Both views share the same conversation, so you can switch freely without losing your place. When the side panel first opens with no active conversation, you see the welcome heading “What are we building?” with the subheading “Describe it, I’ll handle the rest.” Below the heading, three suggestion cards help you get started: Build a sample AI Employee Evaluate and refine an AI Employee Research and explore the platform Click any card to send that suggestion as your first message. Recent chats Every conversation you have with Autopilot is saved automatically. To revisit a past conversation, open the Recent chats list from the Autopilot header. Each entry shows the conversation title along with status indicators: IconMeaning Person iconAutopilot is waiting for your input before it can continue Green dotNew activity has occurred since you last viewed this conversation Exclamation iconSomething went wrong during that conversation Click any conversation in the list to resume it exactly where you left off. Starting a new chat To begin a fresh conversation without losing your current one: Click the New chat button (the plus icon in the header toolbar). A new, empty conversation opens with the welcome screen and suggestion cards. Your previous conversation stays accessible in Recent chats — nothing is deleted. Starting a new chat is useful when you want to switch tasks. For example, if you were debugging an AI Employee and now want to build a completely different one, a new chat gives Autopilot a clean slate. Tip: Autopilot is scoped to your account permissions. If you cannot perform an action manually in the platform, Autopilot cannot perform it for you either. See Permissions & scoping for details. Related sections: Core actions · Permissions & scoping · Tips, limits & examples

================================================================================
# Core actions
URL: https://builder.ema.ai/autopilot/core-actions
================================================================================

Core actions Autopilot carries out real work across the Ema platform on your behalf. Instead of navigating menus and forms, you describe what you want in the chat and Autopilot handles the rest. This section covers every major action, from creating your first AI Employee (AIE) to filing a bug report. ActionWhat it covers Creating an AI EmployeeBuild a new AIE from scratch or clone an existing one Editing an AI EmployeeModify workflows and settings in a safe working session Testing an AI EmployeeChat with an AIE to verify its responses Managing data and knowledgeUpload files, search knowledge bases, work with dashboards Generating documentsProduce polished reports and deliverables Connecting integrationsLink external apps and tools to your AIEs Organizing AI EmployeesGroup and arrange AIEs for easy navigation Asking platform questionsGet answers about Ema capabilities and your account Reporting bugsFile bug reports directly from the chat Creating an AI Employee Every project starts with an AI Employee. Tell Autopilot what you need and it builds the AIE, sets up its workflow, and confirms when it is ready. You can also clone an existing AIE by asking Autopilot to copy it by name. How to create an AI Employee: Open the Autopilot chat from any page. Describe the AI Employee you want — its purpose, the tasks it should handle, and any data it needs. Autopilot creates the AIE and reports back with a summary of the name, description, and configuration. To have Autopilot handle everything end to end, say so in your prompt; it will make all design decisions and confirm when complete. After creation, a version snapshot is saved automatically. You can view the history or roll back at any time. Example prompts: Build me an internal knowledge assistant AI Employee that answers employee questions about company policies, SOPs, processes, and documentation. Then, create a sample policy file, upload it, and test that the AI Employee works as expected. Make all design decisions yourself without asking me for input. Clone my “Customer Support Bot” AI Employee and rename the copy to “Support Bot v2”. Limits: You must have permission to create AI Employees in your workspace. Autopilot asks for confirmation before finalizing creation. Editing an AI Employee Changes happen inside a working session — nothing goes live until you ask Autopilot to deploy. This means you can experiment freely without risk to the live version. If you close the session without deploying, your changes are discarded. How to edit an AI Employee: Tell Autopilot which AIE to change and what you want. Autopilot opens a working session and loads the current workflow. Make as many changes as you like: rename the AIE, add or remove workflow steps, reconnect steps, enable human approval on a step, set a schedule trigger, assign integration tools to a step, configure a per-step model override with EmaFusion™, manage categorizer options, or enable and disable the AIE. Ask Autopilot to check the workflow. It validates the configuration and flags errors. Ask Autopilot to deploy. It will ask you to confirm before pushing changes to production. You can save a version snapshot at any point and roll back to a previous version whenever you need to. Example prompts: Help me analyze and improve an AI Employee to improve its performance. If it is deployed, test it with a few sample queries and analyze their debug trace logs, too. Add a human-approval step to my “Invoice Processor” so someone on the finance team must sign off on payments over $10,000. Limits: Load an AIE’s workflow before making structural changes. Deploying always requires confirmation. Only one working session per AIE can be active at a time. Testing an AI Employee Building an AIE is only half the work. Autopilot lets you open a live conversation with any AIE, send it messages, and review its answers without leaving the chat. How to test an AI Employee: Ask Autopilot to start a conversation with the AIE by name. Send messages as an end user would. Responses may take a moment for complex workflows. Review replies and ask follow-ups to probe different scenarios. List active conversations or delete a test conversation when finished. For structured evaluation, ask Autopilot to generate a test set and run it automatically. Example prompts: Create a 5 question test set for my internal knowledge assistant AI Employee. If the AI Employee doesn’t exist yet, create one first. Then run the test set and report back with the results. Make all design decisions yourself without asking me for input. Start a conversation with my “IT Helpdesk” AI Employee and ask it: “How do I reset my VPN password?” Limits: Conversations are asynchronous — complex workflows may need a moment. Deleting a conversation is permanent and requires confirmation. Managing data and knowledge AI Employees are only as good as the information they can access. Autopilot makes it easy to upload documents, search knowledge bases, and organize data across AIEs. Uploading data Attach files by clicking the “Attach files” button, dragging and dropping into the chat (a blue border appears), or pasting an image directly. Each file can be up to 20 MB. Uploaded files show as a chip with the name, size, and a remove button. Tell Autopilot which AIE the data belongs to and it handles the rest. Searching and organizing data Ask Autopilot to list data sources for an AIE (results are paginated). Search within a knowledge base by keyword. Copy a data source or replicate it to another AIE. Delete a data source (permanent — Autopilot asks for confirmation). Dashboards You can upload dashboard data and trigger workflows from individual rows. Ask Autopilot to view rows, trigger a workflow for a specific row, or refresh the data — useful for batch processing or monitoring structured datasets. Example prompts: Upload the Q4 sales report to my “Revenue Analyst” AI Employee and search it for mentions of APAC. Show me all data sources attached to my “Policy Assistant” AI Employee. Limits: 20 MB per file. Deleting data is irreversible. Paginated results require you to request the next page. Generating documents When you need a polished deliverable — a report, summary, or structured analysis — Autopilot generates it in the background so you can keep working while it runs. How to generate a document: Tell Autopilot what document you need, including the AIE, data, or format to use. Autopilot starts generation and notifies you when it begins. When the document is ready, Autopilot delivers it in the chat. Generation time depends on complexity and data volume. If something goes wrong, Autopilot reports the error and suggests next steps. Example prompts: Generate a summary report of all support tickets handled by my “Support Triage” AI Employee this week. Create a document comparing the performance of my three sales assistant AI Employees over the last quarter. Limits: Generation is asynchronous; complex requests take longer. Output quality depends on the underlying data and AIE configuration — keep your knowledge base current. Connecting integrations Ema connects to over 100 apps and tools so your AI Employees can pull data from or take actions in external systems. How to connect an integration: Ask Autopilot what integrations are available to see the full list. Choose an integration and ask Autopilot to set it up. It walks you through credentials and permissions. Once connected, assign the integration’s tools to individual workflow steps when editing an AIE. Example prompts: What apps and tools can I connect to Ema? Show me the full list of integrations available and how to set them up. Connect my Salesforce account so my “Lead Qualifier” AI Employee can pull in new leads automatically. Limits: Each integration requires its own credentials. Not all integrations support every action — ask Autopilot about specific capabilities. Removing an integration that active AIEs depend on may cause workflow errors. Organizing AI Employees Groups act as folders that let you categorize AIEs by team, function, project, or any scheme that fits your organization. How to organize AI Employees into groups: Ask Autopilot to create a group with a name. Move an AI Employee into the group by specifying both the AIE and group names. Reorganize by moving AIEs between groups, renaming groups, or deleting groups you no longer need. Ask Autopilot to list all groups or list AI Employees with filters like status or type to find what you need quickly. Example prompts: Create a group called “Sales Team” and move my “Lead Qualifier” and “Demo Scheduler” AI Employees into it. List all my AI Employees that are currently active. Limits: Deleting a group is permanent and requires confirmation. AIEs inside a deleted group become ungrouped — they are not deleted. Asking platform questions Not sure what Ema can do or how a feature works? Autopilot doubles as a platform guide. Type your question directly — no special syntax needed. Example prompts: Give me an overview of Ema’s platform capabilities and what I can do as a user. How can you help me through my journey? What is the difference between a scheduled trigger and a manual trigger for an AI Employee? Limits: Autopilot answers based on current platform capabilities. For billing, account limits, or enterprise agreements, it may direct you to Ema support. Reporting bugs If something is not working as expected, you can file a bug report directly from Autopilot without leaving the platform. How to file a bug report: Describe the issue in the chat. Include what you were doing, what you expected, and what happened instead. Autopilot files the report and confirms submission. Example prompt: I found a bug: when I upload a CSV to my “Data Analyst” AI Employee, the upload spinner never stops and the file does not appear. I tried three times with different files. Limits: Provide as much detail as possible — vague reports are harder to act on. Reports go to Ema’s internal tracking; you will not receive a ticket number in the chat, but all submissions are reviewed. Related sections: What Autopilot is & how to open it · Permissions & scoping · Tips, limits & examples

================================================================================
# Permissions & scoping
URL: https://builder.ema.ai/autopilot/permissions-scoping
================================================================================

Permissions & scoping Autopilot works within your account’s boundaries by design. Every session is tied to your login, so Autopilot sees the same AI Employees (AIEs), data sources, integrations, and conversations you see — nothing more. This scoping keeps your work private and ensures that actions taken by Autopilot only affect your environment. When Autopilot needs to do something significant, it asks you first through an approval prompt, giving you full control over what actually happens. In this section you will learn: What data and resources Autopilot can access in your account When and why Autopilot asks for your approval before acting How to respond to approval prompts and follow-up questions What happens when you ask Autopilot to do something outside its reach How your role affects what you see in the Autopilot interface What Autopilot can access Autopilot operates within your tenant — the organization-level account you belong to on the Ema platform. It can read and act on the same resources you can access through the regular interface: ResourceWhat Autopilot can do AI EmployeesView, create, edit, delete, and test any AI Employee in your tenant Data sourcesList, upload, search, and remove data connected to your AI Employees IntegrationsView and configure integrations available in your tenant ConversationsBrowse and manage conversations handled by your AI Employees WorkflowsLoad, edit, validate, and deploy workflows attached to your AI Employees Autopilot also knows which page you are currently viewing. For example, if you are on the configuration tab of a specific AI Employee, Autopilot already has that context — you can say things like “change the greeting message” without specifying which AI Employee you mean. Example prompts: Show me all the AI Employees in my account. What data sources are connected to this AI Employee? Autopilot cannot access AI Employees, data, or conversations that belong to a different tenant. If you are a member of multiple organizations, each Autopilot session is scoped to the tenant you are currently logged into. Approval prompts Some actions have lasting consequences. Before Autopilot carries out anything that cannot easily be undone, it pauses and asks for your explicit approval. This is a safety feature that keeps you in the loop — Autopilot never makes irreversible changes on its own. When Autopilot asks before acting Autopilot presents an approval prompt before performing any of the following: Deleting an AI Employee — Autopilot displays the name of the AI Employee and asks you to confirm before proceeding. Deleting a data source — because this is permanent, Autopilot always asks first. Deleting a conversation — conversation history will be lost. Deleting an AI Employee group — all grouping information will be removed. Deploying a workflow — this pushes changes to your live environment, so Autopilot confirms before proceeding. For routine actions like listing resources or loading a workflow for editing, Autopilot proceeds without interrupting you. Responding to approval requests When Autopilot needs your permission, the chat displays two buttons: “Approve” — click this to let Autopilot carry out the action. Autopilot resumes immediately and completes the task. “Deny” — click this to stop the action. Autopilot acknowledges your decision and does not proceed. After you respond, the chat shows an “Approved” or “Denied” label so you can see at a glance what you decided. If you do not respond within five minutes, the approval prompt times out. Autopilot lets you know that it could not proceed and you can start the request again whenever you are ready. Example: If you type “Delete the Customer Support AI Employee,” Autopilot will show an approval prompt with the AI Employee name before deleting anything. Answering follow-up questions Sometimes Autopilot needs more information rather than permission. In those cases, it asks a follow-up question instead of showing approval buttons. When Autopilot asks a question, you will see: A text area with the placeholder “Type your answer...” where you can write a free-form response A “Send” button to submit your answer In some cases, predefined option buttons that let you pick from a set of choices without typing After you respond, the chat shows an “Answered” label. Like approval prompts, follow-up questions time out after five minutes if left unanswered. Example: If you type “Create a new AI Employee for handling refunds,” Autopilot may ask follow-up questions such as “What tone should this AI Employee use when responding to customers?” before proceeding. What happens when something is out of scope If you ask Autopilot to do something it cannot do, it tells you directly rather than failing silently. Here are the most common scenarios: The resource does not exist. If you reference an AI Employee that cannot be found, Autopilot explains that it could not locate the resource and may suggest checking the name. A required step was skipped. Some actions depend on a prior step. For example, editing a workflow requires loading it first. If you skip ahead, Autopilot explains what it needs to do first and either handles the prerequisite automatically or asks you to confirm. Too many active sessions. Each account has a limit on the number of concurrent Autopilot sessions. If you reach that limit, a persistent banner appears: “Session limit reached — you have [N] active sessions (max [M]). Wait for one to finish or cancel it.” Check your Recent chats for sessions that are still running and close any you no longer need. A session is already in progress. If you try to send a message while Autopilot is still working on a previous request in the same session, it lets you know. Wait for the current task to complete before sending your next message. You can monitor all your sessions from the Recent chats list. Each session shows a status indicator: IconMeaning Person iconAutopilot is waiting for your response to an approval prompt or question Green dotThere are new messages you have not read yet Exclamation iconThe session encountered an error Role-based visibility Your role within the Ema platform determines which features appear in the interface. For Autopilot, this works as follows: If your role includes the permission to create AI Employees, you will see the “Build your own AI Employee” button on the AI Employees page. You can use this button directly or ask Autopilot to create an AI Employee on your behalf. If your role does not include that permission, the button is hidden entirely — it does not appear as a grayed-out or disabled option. All other Autopilot features are available to every authenticated user within the tenant. You can chat with Autopilot, ask questions, browse resources, and manage anything your account can access. In practice, most users have full access to Autopilot’s capabilities. The only difference is whether the option to create a brand-new AI Employee is visible. Everything else — editing, testing, listing, deploying, and asking questions — works the same for all users. Related sections: Core actions · What Autopilot is & how to open it · Tips, limits & examples

================================================================================
# Tips, limits & examples
URL: https://builder.ema.ai/autopilot/tips-limits-examples
================================================================================

Tips, limits & examples Getting the most out of Autopilot starts with how you phrase your request. A specific, well-structured prompt helps Autopilot take the right actions and reduces back-and-forth. This section covers ready-to-use prompts, interface controls, and how to handle common issues. What you will learn in this section: Sample prompts for common tasks you can copy and paste How to use keyboard shortcuts to work faster How to choose between Fast mode and Thorough mode How to switch between Narrative view and Developer view How to attach files to your conversation How to give feedback on Autopilot responses Current limitations and how to troubleshoot common issues Example prompts When you open a new Autopilot session, you will see clickable suggestion cards with pre-built prompts. Select any card to send its prompt instantly: Card labelWhat it does Build a sample AI EmployeeCreates a knowledge assistant AIE, uploads a sample policy file, and tests it end to end — no input needed from you. Evaluate and refine an AI EmployeeAnalyzes an existing AIE, runs sample queries, and reviews trace logs to suggest improvements. Research and explore the platformGives you an overview of Ema platform capabilities and explains how Autopilot can help. Test and analyze performanceCreates a five-question test set for an AIE, runs it, and reports results. Connect to 100+ apps and toolsLists every available integration and explains how to set each one up. View my learnings and insightsSummarizes patterns Autopilot has picked up from your past conversations. Additional prompts to try Beyond the suggestion cards, here are practical prompts you can paste directly into Autopilot: Generate a document: “Draft a one-page onboarding guide for new hires that covers our company’s PTO policy, expense reporting process, and IT setup checklist. Format it with headers and bullet points.” File a bug: “I found an issue where my AI Employee gives outdated answers about our return policy. Log this as a known issue and suggest specific improvements to fix it.” Organize a group: “List all the AI Employees in my workspace, group them by department, and recommend which ones overlap so I can consolidate.” For the full list of actions Autopilot can perform, see Core actions. Keyboard shortcuts You do not need to reach for your mouse to control Autopilot. These shortcuts let you open, resize, and navigate the panel without leaving your workflow. ShortcutAction ⌘EToggle the Autopilot panel open or closed (works anywhere in the app) ⌘⇧EToggle between side panel and expanded view (when the panel is open) EscapeClose the panel (if in side view) or collapse to side panel (if in expanded view) EnterSend your message Shift+EnterInsert a new line in the composer Fast mode and Thorough mode Before you start a session, you can choose how deeply Autopilot reasons through your request. In the composer footer, you will see a “Fast” toggle on the left side. Click it to switch between the two modes: Fast mode gets you a quicker response by streamlining Autopilot’s reasoning. Use it for straightforward tasks like looking up information or listing AI Employees. Thorough mode (the default) gives Autopilot more room to think through complex, multi-step requests. Use it when you are building, testing, or refining an AI Employee. Once your session begins, the mode locks in and cannot be changed mid-conversation. If you chose the wrong mode, start a new session and select the other option before sending your first message. When Fast mode is active, you will see a lightning icon with the label “Fast mode” in the composer footer. Narrative view and Developer view Autopilot defaults to Narrative view, which groups the work it performs into human-readable summaries so you can follow along without technical detail. If you want to see exactly what Autopilot did step by step, switch to Developer view. To toggle views, click the three-dot More actions button in the session header and select “Developer view” or “Narrative view” (the label reflects the view you will switch to, not the one you are currently in). Narrative view is best for most users. It presents Autopilot’s progress as clear, grouped summaries. Developer view is best when you want to inspect individual steps and thinking — useful for debugging AI Employee behavior or understanding exactly how Autopilot carried out a task. This setting applies to your current session only and resets when you start a new one. Uploading files You can attach files to give Autopilot additional context — for example, a policy document you want an AI Employee to learn from, or a spreadsheet of test questions. Three ways to attach a file: Click the “Attach files” button (the plus icon) in the composer to open your file picker. Drag and drop files directly into the chat area. A blue dashed border appears to confirm the drop zone is active. Paste an image directly into the text area. Attached files appear as chips below the composer showing the filename and file size. To remove a file before sending, click the remove button on its chip. Each file must be under 20 MB. If you exceed this, you will see: “File exceeds 20 MB limit. Please upload smaller files.” Providing feedback Your feedback helps improve Autopilot over time. Every response from Autopilot includes action buttons: Thumbs up (tooltip: “Provide feedback”) — marks a response as helpful. Thumbs down (tooltip: “Provide feedback”) — marks a response as unhelpful. Copy (tooltip: “Copy”) — copies the response text to your clipboard. Feedback is per message, so you can rate individual responses within the same conversation. Known limitations No slash commands. You cannot type / commands in the Autopilot chat. Interact using natural language prompts instead. No @ mentions. You cannot tag other users or AI Employees with @ in the chat. Concurrent session limit. Your account has a maximum number of active sessions. If you reach it, you will see: “Session limit reached — you have [N] active sessions (max [M]). Wait for one to finish or cancel it.” Close or cancel a session to free up a slot. Approval prompt timeout. When Autopilot asks for your approval, you have five minutes to respond. After that, the request times out and you will need to send another message to retry. Inactivity timeout. Sessions automatically close after 15 minutes of inactivity. Start a new chat to continue where you left off. For details on what Autopilot can and cannot do based on your role, see Permissions & scoping. Troubleshooting IssueWhat to do “Session limit reached”Wait for an active session to finish, or cancel one from your Recent chats list. Then start a new session. Approval request timed outAutopilot waited for your confirmation but did not receive it within the time limit. Send another message to retry the same action. File upload failedConfirm your file is under 20 MB. Remove the file, re-attach it, and try again. Session shows an error iconA failed session appears with an exclamation icon in Recent chats. Start a new chat to continue. Autopilot seems stuckStatus messages like “Thinking hard...” or “Working through this...” indicate Autopilot is still processing. Wait a moment — complex tasks take longer, especially in Thorough mode. Related sections: What Autopilot is & how to open it · Core actions · Permissions & scoping

================================================================================
# Integrations & Data
URL: https://builder.ema.ai/integrations-data
================================================================================

Integrations & Data Ema's integrations layer provides the infrastructure that enables AI Employees to interoperate with existing enterprise applications. The catalog includes more than 200 native connectors covering CRM, HRIS, finance/ERP, ITSM, and related domains. Each connector supports real-time, two-way data synchronization: when a record is modified in a source system such as Salesforce or ServiceNow, the change is immediately reflected in Ema, and any action executed by an AI Employee is written back to the originating system. This bidirectional flow preserves data integrity and eliminates manual reconciliation. Connector Categories Connectors are available in two categories: Tool-calling connectors (Intelligent Actions) -- Allow AI Employees to perform transactions in external systems (for example, creating tickets, approving purchase orders, or updating opportunity stages) and record the results through the same interface. See Intelligent Actions for details. Data connectors -- Establish secure pipelines that import reference content (policies, tickets, web pages, and similar assets) into Ema while exporting agent-generated insights or annotations to the source repository. This approach ensures responses are context-aware, aligned with brand guidelines, and suitable for analytics. See Data Connectors for details. Key Advantages Accelerated implementation -- Pre-built connectors eliminate custom API development, shortening deployment timelines from months to days. Authoritative data -- Continuous two-way synchronization with granular field-level controls maintains a single source of truth across all systems. Enterprise-grade security -- All connectors inherit Ema's compliance posture (SOC 2, ISO 27001, HIPAA alignment) and enforce encryption in transit and at rest, with role-based access control. Custom Integrations When the pre-built catalog does not cover a specific system, Ema provides two paths for extending the platform: Custom tool integrations -- Build bespoke action connectors using Ema's no-code builder so AI Employees can call any HTTP-accessible API as an Intelligent Action. See Custom Integrations for a step-by-step guide and Custom Tool Integrations for the workflow-building reference. Custom data connectors -- Functionality for creating custom data connectors is under development and will be available soon. Maintenance Mode Ema supports placing individual integrations into maintenance mode when you need to perform scheduled upkeep on a connected system -- for example, rotating credentials, upgrading an on-premises instance, or migrating to a new OAuth application. While an integration is in maintenance mode: Workflows that depend on the integration are paused automatically; they resume once maintenance ends. A banner on the integration card in the Integrations page indicates the maintenance window. Scheduled sync jobs for data connectors are deferred until the window closes, then run immediately to catch up. To activate maintenance mode, open the integration card on the Integrations page, click the three-dot menu, and select Enable Maintenance Mode. You can optionally set an estimated end time so dependent workflows can display an appropriate message to end users. When you are ready, click Disable Maintenance Mode to resume normal operation. In This Section PageDescriptionCustom IntegrationsBuild custom tool integrations for any HTTP APIIntelligent ActionsExternal tool calling in workflowsSalesforce SetupSalesforce-specific integration guideIntegration ListFull catalog of supported connectorsData ConnectorsFile ingestion, cloud sync, and knowledge-base connectorsData Extraction & Rule ValidationDocument Intelligence dashboardsFile TaggingMetadata tags for document searchEmbeddable Chat SDKEmbed a chatbot on your websiteData APIExport conversation data for analytics

================================================================================
# Custom Integrations
URL: https://builder.ema.ai/integrations-data/custom-integrations
================================================================================

Custom Integrations Custom Apps let you connect any external API to Ema so your AI Employees can use it directly. Whether you need to reach an internal system, a niche SaaS product, or a third-party service, you can build a Custom App for it. Once it is set up, you can add as many actions as you need -- and your AI Employees will be able to call them during their workflows. When to Build a Custom Integration You need an AI Employee to call an internal microservice or a niche SaaS product not yet in the Ema catalog. You want to wrap a third-party REST or GraphQL endpoint as a reusable tool that multiple AI Employees can share. You have an on-premises system exposed through an API gateway and want Ema to interact with it securely. Getting Started Getting a Custom App action running takes four steps: Create a Custom App -- Define the integration (name, category, description) on the Integrations page. Connect and configure authentication -- Set up the auth scheme (API Key or OAuth 2.0), define credential fields, and establish a live connection. Build and test actions -- Create actions, write the API call logic using call_ema_connector in a Custom Code agent, define inputs and outputs, and run the persona. Add to an AI Employee -- Add the registered action as a tool in an AI Employee's workflow using Intelligent Actions so it can be invoked at runtime. Key Concepts TermDefinitionCustom AppA user-defined integration backed by an external API. It appears alongside pre-built integrations on the Integrations page and can hold one or more actions.ActionA discrete API operation (for example, "Get User" or "Create Ticket") attached to a Custom App. Each action is configured in the Action Builder, where you define its inputs, outputs, and API call details.ConnectionA set of stored credentials that authenticate Ema against the Custom App's API. A Custom App can have one connection and multiple actions.Auth SchemeThe authentication method used by the Custom App -- either OAuth 2.0 or API Key.Template FieldsAuth-related fields defined at the integration level. These are shared across all connections.Connection FieldsAuth-related fields that each individual connection supplies (for example, the actual API key value or user-specific token).PlacementDetermines where an auth field value is sent in the HTTP request. Options are Bearer Token, Custom Header, Query Parameter, JSON Body, and Form Body.PersonaEvery action is powered by a persona. These personas use Custom App configurations to call external APIs on your behalf. When you create an action, Ema generates a persona (Dashboard persona) that you configure in the Action Builder. Building a Custom Integration Step 1 -- Create a Custom App Navigate to the Integrations page. Click New Custom App in the top-right corner. In the modal that opens, fill in the required fields: Application name -- enter a unique name (letters, numbers, and spaces only). Category -- select a category from the dropdown (for example, CRM, Productivity, Custom). Description -- describe what this integration does. This text is shown on the Integrations page. Click Confirm. The new Custom App appears in the integrations homepage under all apps. App names must be unique across all integrations, including pre-built ones. Step 2 -- Connect and Configure Authentication Authentication setup walks you through defining your auth scheme, filling in credentials, and establishing a connection. The steps differ depending on whether you choose API Key or OAuth 2.0. Start the connection wizard Open the Custom App by clicking its card on the Integrations page. In the Overview tab, locate the Intelligent Actions integration banner and click Connect. A Connection options dropdown appears. Select your auth type: API Key -- for services that authenticate with a static key or token. OAuth 2.0 -- for services that use the OAuth 2.0 authorization flow. Important: Once an auth type is selected and configured, it cannot be changed. Phase 1 -- Define the auth configuration This phase collects the Base URL, scheme-specific settings, and auth field definitions. Refer to your external API's documentation to determine the correct values for each field. In the setup modal, enter the Base URL -- the root URL of the API (for example, https://api.linear.app/graphql). This field is always required. If you selected OAuth 2.0, fill in these additional fields: Auth URL -- the authorization endpoint. Token URL -- the token endpoint. Scopes -- comma-separated OAuth scopes (optional). A read-only Redirect URI is displayed for you to copy and register with the OAuth provider. If you selected API Key, the Connection Fields section is pre-populated with a default field: Field Name: api_key Display Name: API Key Placement: Custom Header Header Name: Authorization Secret: checked You can edit these defaults or add more fields to match your API's requirements. Configure Template Fields and Connection Fields. Both field types share the same structure -- the difference is who provides the value and when: Template Fields are set once during integration setup and shared across all connections. Use these for credentials that belong to the integration itself. Connection Fields are filled in each time a connection is created. Use these for credentials that are specific to a user or environment. Template FieldsConnection FieldsOAuth 2.0client_id, client_secret (provided by the OAuth provider when you register your app)Typically none -- the OAuth flow handles user-specific tokens automaticallyAPI KeyRarely used -- most API key setups only need connection fieldsThe API key value itself (for example, api_key), workspace tokens, or environment-specific secrets For each field, provide: Field Name -- a machine-readable identifier. Check your API documentation for the expected parameter name. Display Name -- the label shown to users. Placement -- where the value is injected into outgoing HTTP requests: Bearer Token -- sent as Authorization: Bearer <value>. Custom Header -- sent as a custom HTTP header (specify Header Name). Query Parameter -- appended to the URL (specify Param Name, for example api_key). JSON Body -- included in the request body as JSON (specify Field Name). Form Body -- included in the request body as form data (specify Field Name). Check Secret to mask the value in the UI. Refer to your API provider's documentation to determine the correct placement. For example, some APIs expect the key in an Authorization header, while others expect it as a query parameter. Click Save & Continue. Phase 2 -- Fill template credentials If your auth scheme has template-level fields, you are prompted to fill in their values. Enter values for each template field shown in the form and click Save & Continue. If no template fields are defined, this phase is skipped automatically. Phase 3 -- Enter connection credentials This is where you provide the actual credentials for the connection: API Key: Enter your API key value in the field shown. OAuth 2.0: Enter any runtime connection fields required by the provider. Click Connect when done. Phase 4 -- Complete the connection API Key: The connection is established immediately. A success toast confirms the connection. OAuth 2.0: A browser popup opens to the OAuth provider's authorization page. Complete the sign-in flow in the popup. Once authorized, the popup closes and the connection is established. On success, the banner button changes from Connect to Disconnect, and your actions can now execute against the API. You can create and configure actions before connecting -- the Actions tab displays an info banner: "Connect this app to run actions. You can still create and configure them." Credentials are validated at runtime. Test the integration in an AI Employee to confirm that authentication works end-to-end. Step 3 -- Create an Action Open the Custom App modal and navigate to the Actions tab. Click New action. Enter a Name and Description for the action. Click Confirm. A new browser tab opens to the Action Builder (GWE canvas) with the configuration modal pre-opened. Action names must be unique within the Custom App. The UI shows an error if multiple actions share the same name within an integration. Build an Action After clicking Confirm, the Action Builder persona opens in a new tab. This is the same GWE canvas used for AI Employees, but scoped to the three agents available in actions: Custom Code Agent, Convert to Text, and Custom Agent. The canvas opens with a pre-configured trigger and a default workflow input called tool_input. You need to complete three things before the action can be saved and registered: define your inputs, write the workflow logic, and declare at least one named output. Define workflow inputs Workflow inputs become the action's input parameters -- the values an AI Employee supplies when it calls this tool. The canvas starts with a default tool_input input. You can edit it or add more. Open the trigger node and click to add or edit a workflow input. For each input, provide: Name and Display name -- the machine name and human-readable label. Description -- helps the AI Employee understand what value to pass. Write this clearly -- it directly affects how well the AI selects and fills this parameter. Type -- select the data type (String, Int, Float, Boolean, Date, DateTime, Object, Array, and others). Required -- whether the AI Employee must provide this value. Optionally, expand Additional parameters to configure advanced settings: Input dependencies -- declare that this input depends on the output of another action within the same Custom App. User ID domain -- indicate that this input represents a user identity (Email or MS Active Directory ID). When set, Ema auto-fills the value from the actioning user's identity. Build the workflow on the canvas Use the visual canvas to define the action's logic. Actions support three agents: Custom Code Agent -- write JavaScript to call the external API and process the response. Convert to Text -- convert any input types into a single text string without using LLMs. Custom Agent -- a configurable agent where you define a role, task instructions, and a structured output schema. The Custom Agent uses an LLM to carry out the described task -- useful for summarizing API responses, classifying data, extracting fields from unstructured text, or making decisions based on returned data. Unlike Custom Code (which runs deterministic JavaScript), the Custom Agent handles tasks that benefit from language understanding. Writing the API call with Custom Code The Custom Code agent uses call_ema_connector -- a built-in JavaScript function that makes authenticated HTTP calls through Ema's proxy. Ema automatically injects your stored credentials (API key or OAuth token) into every request. Function signature: call_ema_connector(integration_id, method, path, body?, headers?) // Returns: { ok, status, body, headers, request_log_id } Parameters: ParameterTypeDescriptionintegration_idstringThe Custom App's integration ID (must be declared in the action's config)methodstringHTTP method: "GET", "POST", "PUT", "PATCH", "DELETE"pathstringAPI path appended to the Base URL (for example, "/tickets")bodystring | null(Optional) Request body -- sent as JSONheadersobject(Optional) Additional HTTP headers Response object: FieldTypeDescriptionokbooleantrue if the HTTP status is 2xxstatusnumberHTTP status codebodystringResponse body (UTF-8 text)headersobjectResponse headersrequest_log_idstringUnique ID for correlating with request logs Restrictions and limits: RestrictionDetailIntegration allowlistThe integration_id passed to call_ema_connector must be declared in the action's Tool Persona Config. Calls to any other integration are blocked with a runtime error.Call limitMaximum 20 call_ema_connector calls per script execution. If your use case requires more, batch your requests or paginate efficiently.Request body sizeCapped at 1 MB per request.Response formatText and JSON only. Binary responses (files, images) and streaming are not supported.TimeoutEach external HTTP call has a 60-second deadline. If the API does not respond in time, the call throws an error.Error behaviorcall_ema_connector does not throw on 4xx/5xx responses. Your script must check response.ok or response.status and handle errors explicitly.Credential injectionYou never pass API keys or tokens in your script. Ema injects credentials automatically based on your Placement config. Do not hardcode secrets. Building the workflow Click the Add Agent button on the canvas to add an agent step. Select Custom Code Agent to write a script, Convert to Text to transform data, or Custom Agent for configurable task execution. Connect the steps with edges to define data flow. Reference workflow inputs in your script using inputs.<input_name>. Return the data you want to pass to downstream steps or to the named output. Define named outputs Named outputs define what the action returns to the AI Employee. At least one named output is required -- without it, the action cannot be saved or registered as a tool. Open the Named Results panel on the right side of the canvas. Add one or more named results. For each, provide: Name -- identifier for the output. Description -- explain what this output contains. Type -- the data type of the returned value. Save and register the action Click Save Changes in the canvas header. On save, Ema automatically registers the action as an external tool in the action registry. No separate publish step is needed. The action is now discoverable by any AI Employee in your workspace. Every subsequent save re-registers the action with any updated inputs, outputs, or logic. Test an Action Actions are fully runnable personas. You can test them in two ways: directly from the Custom Code agent during development, and from the dashboard as a full end-to-end run. Test from the Custom Code agent While building your script in the Custom Code agent, you can run it directly to verify your API calls work: In the Custom Code agent node on the canvas, write or edit your script. Use the Test button within the agent to execute the script. The agent makes live call_ema_connector calls against the real API. Review the script output inline to confirm the response shape and values. This is useful for iterating quickly on your script logic -- checking response parsing, error handling, and field mapping -- without running the full workflow. Test from the dashboard For a full end-to-end test that exercises the entire workflow (trigger, inputs, agents, and named outputs): In the Action Builder canvas, click Use AI Employee in the top-right header. This opens the dashboard view for the action's persona. Add a row with test input values (for example, a sample ticket title or user email). Run the workflow. Ema executes the full flow -- including all call_ema_connector calls -- against the live API. Review the output rows in the dashboard results. Each run produces a row showing the named output values. You can add multiple rows with different input combinations to test various scenarios in a single session. Even when this action runs as an embedded tool inside an AI Employee at runtime, the execution is still recorded. You can return to this persona's dashboard at any time to see rows from all runs -- including those triggered by AI Employees in production. This gives you full visibility into how the action is being called and what it returns. What to verify Correct API calls: Check that the right endpoints are hit with the right method and payload. Use the request_log_id from the response to correlate with request logs. Auth works end-to-end: If you see authentication errors (401/403), verify your connection credentials in the Custom App settings (Step 2). Error handling: Test with invalid inputs, missing fields, and edge cases. Confirm your script handles non-2xx responses gracefully rather than silently failing. Output shape: Verify that the named outputs contain the expected data and types. The output schema is what AI Employees see when they consume this tool. Connection status: The Custom App must be connected for test runs to succeed. If disconnected, the call_ema_connector calls will fail. Credentials are validated at runtime, not at save time. A successful save does not guarantee that API calls will work -- always test with real credentials and inputs. Run an Action in GWE Using Intelligent Actions Once an action is saved and registered, it is available as a tool and must be added to an AI Employee before it can execute in production workflows. Add the tool to an AI Employee Navigate to AI Employees and open any AI Employee of your choice, or create a new one. In the canvas, click to add a tool step. In the Select App modal, find and select your Custom App from the list. The Tools tab opens showing all registered actions for this Custom App. Click the action you want to add. In the Configure Tool modal, set up each input parameter: Auto fill by Ema -- the AI Employee infers the value at runtime based on conversation context. Use this for dynamic inputs like user queries, email content, or extracted entities. Fixed value -- you provide a constant value that is used every time the tool runs. Use this for static config like environment names, default statuses, or fixed IDs. Optionally, enable HITL -- when checked, the AI Employee pauses before executing this tool and presents the proposed parameters for human approval. The tool only runs after the human confirms. Click Save. What happens at runtime When an AI Employee invokes a Custom App action during a workflow: The Intelligent Actions framework identifies that the action matches the current task and calls the action. The Workflow Engine executes the action synchronously. The Custom Code agent runs your JavaScript. Each call_ema_connector call is routed through EmaConnector, which resolves the tenant's stored credentials, injects authentication, and forwards the request to the external API. The external API responds. EmaConnector returns the response to your script. Your script processes the response and returns the result. The workflow's named outputs are returned to the AI Employee as the tool response. The AI Employee uses the returned data in subsequent workflow steps. Runtime behavior and limits BehaviorDetailAuth injectionEma handles credential injection automatically -- API keys are placed per your Placement config, OAuth tokens are refreshed and injected as Bearer tokensConnection scopeOne connection per Custom App, shared across the entire tenantCall limitMaximum 20 call_ema_connector calls per script executionRequest sizeRequest body capped at 1 MBTimeout60-second deadline per external HTTP callSupported contentText and JSON APIs only -- no binary or streaming responsesError behaviorNon-2xx responses do not throw automatically -- your script must handle themVersioningUpdates take effect immediately after save. There is no version historyHuman-in-the-LoopIf enabled, the AI Employee pauses and shows proposed parameters before executing the tool. Execution resumes only after human approval The Custom App must be connected (Step 2) for the AI Employee to execute the action at runtime. You can add and configure tools before connecting, but execution will fail until credentials are in place. Managing Custom Apps Editing a Custom App Open the Custom App modal from the Integrations page. Click the pencil icon (Edit integration) in the header. Update any combination of Application name, Category, Description, Base URL, auth URLs, or auth fields. Click Save Changes. Unsaved changes are discarded if you close the modal without saving. Exporting and importing Export: Open the Custom App modal and go to the Actions tab. Click Export (visible only when the app has at least one action). Follow the export wizard to generate a portable definition of the app's actions. Import: On the Integrations page, click Import in the top-right corner. Follow the import wizard to upload a previously exported definition. The imported Custom App and its actions appear in the integration list. Deleting a Custom App Open the Custom App modal. Click the trash icon (Delete integration) in the header. A confirmation dialog appears. Destructive action: Deleting a Custom App permanently removes the integration and all its connections. Any actions (tools) built on this integration will be marked as deprecated and will no longer execute during AI Employee runs. This cannot be undone. Click Delete to confirm, or Cancel to go back. Best Practices Write clear descriptions. The Intelligent Actions agent relies on tool and action descriptions to decide which tool to invoke. Ambiguous descriptions lead to incorrect tool selection. Define all required parameters explicitly. If a required parameter is missing, the API call will fail at runtime. Test before enabling. Use the Custom Code agent's test button and the dashboard view (Use AI Employee) to catch errors before adding the action to a production workflow. Keep actions granular. Define one action per distinct operation rather than combining multiple operations into a single action. Rotate credentials proactively. Use maintenance mode when rotating API keys or OAuth secrets to avoid transient failures. Always check for API errors in your script. If you do not add error handling, your action might look like it worked even when the API call actually failed -- returning empty or incorrect data without any warning. Write descriptive workflow input descriptions. The AI Employee uses input descriptions to decide what value to pass at runtime. Vague descriptions like "ID" lead to incorrect parameter mapping -- use something like "The unique project ID returned by the Get Projects action." Enable HITL for high-impact write actions. For actions that create, update, or delete data (for example, "Create Ticket" or "Delete User"), enable Human-in-the-Loop so a human can review parameters before execution. Use named outputs with accurate types. The output schema is what AI Employees see when consuming the tool. Mismatched types or vague names cause downstream steps to misinterpret the data. FAQ Can I create a Custom App with the same name as a pre-built integration? No. App names are checked case-insensitively across all integrations -- pre-built and custom. Choose a unique name. What happens to actions if I delete the Custom App? All actions tied to the deleted app are marked as deprecated and will no longer run during AI Employee execution. Any AI Employees consuming those tools are flagged as broken. This is irreversible. What characters are allowed in the app name? Only letters, numbers, and spaces. Special characters and symbols are not permitted. Can I rename the Tool ID after creating an action? No. The tool_id is auto-generated from the action name at creation time and is immutable. If you need a different Tool ID, delete the action and create a new one. Limitations Custom tool integrations currently support HTTP-based APIs only. gRPC, WebSocket, and other protocols are not supported. Custom data connectors (for importing content into Ema's knowledge base) are under development and not yet available. File upload as part of a custom tool action is not supported in the current release. Each Custom App supports only one connection per tenant. You cannot configure multiple connections (for example, for different environments or users) under the same integration. There is no version history for actions. Every save overwrites the previous configuration immediately with no rollback option. Related Custom Tool Integrations (Workflow Building) -- Detailed reference for building custom tools in the workflow builder. Intelligent Actions -- How the Intelligent Actions agent selects and executes tools. Integration List -- Full catalog of pre-built connectors.

================================================================================
# Data API
URL: https://builder.ema.ai/integrations-data/data-api
================================================================================

Data API Introduction Ema's Data API provides a reliable, self-serve way to export message-level chatbot conversation data for a specific AI Employee over a selected UTC date range, delivered as a streamed CSV file. This export is designed for customers who want to take data beyond the Ema product UI and perform deeper analysis in their own analytics stack (for example, Power BI, Tableau, Snowflake, or internal data science notebooks). Using the Data API, you can: Build custom dashboards for adoption and engagement. Run advanced analyses such as sentiment/intent modeling on user queries and AI responses. Independently compute key metrics like sessions, active users, total queries/messages, and feedback rates. The API is read-only and returns raw records (one row per message), allowing full flexibility to define derived metrics and trends. Data is refreshed daily with a 24-hour SLA, and exports are available for dates starting September 1, 2025 onward. Data Dictionary (CSV Schema) Each row represents one message. The following fields are included: FieldFormatDescriptionconversation_idstring (UUID)Groups related messages into a session. Inactivity period is configurable per channel (default: 30 minutes).persona_idstring (UUID)Unique ID assigned by Ema for an AI Employee. (Note: persona_id is a query parameter, not a column in the exported CSV.)conversation_sourcestringHuman-readable channel name (for example, msteams, gchat, chatbot).conversation_created_atISO 8601 (UTC)Timestamp when the first message was sent by the user.conversation_updated_atISO 8601 (UTC)Timestamp of the last message or response in the conversation.message_idstring (UUID)Unique ID assigned to each user message.message_created_atISO 8601 (UTC)Timestamp when the message was sent.message_updated_atISO 8601 (UTC)Timestamp when the message object was last updated.workflow_run_errorbooleanIndicates whether the workflow was successful.user_feedback_typestringFeedback given by the end user: positive, negative, no_feedback_submitted, or empty (feedback was not requested).user_feedback_commentstringActual feedback comment given by the end user.feedback_message_sentbooleanIndicates whether feedback was requested for the response.content_payload_jsonJSON stringMessage sent by the end user.user_contextJSON stringUser attributes such as country, band, etc.unique_source_idsJSON arrayDeduplicated source file IDs seen in citations.countrystringExtracted from user_context (if available; otherwise empty).bandstringExtracted from user_context (if available; otherwise empty).encrypted_user_emailstringBase64-encoded encrypted user email.is_user_messagebooleanWhether this row represents a user message (as opposed to an AI response).external_tool_calledbooleanWhether an external tool was called during this message's processing.external_tool_call_successboolean/stringWhether the external tool call succeeded.external_tool_namestringName of the external tool that was called (if any).events_per_messageJSON arrayArray of events associated with this message. Data Model One session/conversation maps to multiple queries (1 to many). One feedback maps to one query (1:1). One query maps to multiple source IDs (1 to many). Authentication Endpoint Path: /api/metric-data/chatbot/conversations Method: GET Example: https://api.yourcompany.ema.co/api/metric-data/chatbot/conversations Bearer Token Include a Bearer token in the Authorization header: Authorization: Bearer <access_token> Fetching the Access Token curl --location --request POST 'https://api.yourcompany.ema.co/api/auth/generate_access_token' \ --header 'x-ema-api-key: <API-KEY>' Contact your CSM or Support team to request an API key for each tenant. Query Parameters ParameterRequiredFormatDescriptionstart_dateYesYYYY-MM-DD (UTC)Start of the date rangeend_dateYesYYYY-MM-DD (UTC, inclusive)End of the date rangepersona_idYesUUIDThe AI Employee's ID (last segment of the AI Employee URL) Validations and Limits Both dates must match YYYY-MM-DD format. end_date must be >= start_date. Maximum inclusive range: 31 days. Response Status: 200 OK on success. Media type: text/csv; charset=utf-8 Transfer: Streamed response (no fixed Content-Length). Filename pattern: chatbot-metrics-{persona_id}-{start_date}_to_{end_date}.csv Error Responses StatusCause400 Bad RequestInvalid persona_id, invalid date format, end_date earlier than start_date, or date range exceeds 31 days401 UnauthorizedMissing or invalid token, or token lacks tenant_id Sample Request curl -G 'https://api.yourcompany.ema.co/api/metric-data/chatbot/conversations' \ -H 'Authorization: Bearer REPLACE_WITH_TOKEN' \ --data-urlencode 'start_date=2025-11-01' \ --data-urlencode 'end_date=2025-11-15' \ --data-urlencode 'persona_id=<persona-id>' \ -o chatbot-metrics.csv Key Metrics and How to Calculate Them Unique Users / Active Users Count distinct values of encrypted_user_email. Filter by conversation_created_at and conversation_updated_at for a specific date range. Total User Queries / Messages Count all rows where message_id is not empty. Filter by message_created_at and message_updated_at. Total Sessions Count unique conversation_id values whose conversation_updated_at lies within the date range. Positive Feedback Rate Formula: 1 - (negative / (positive + negative + no_feedback_submitted)) Since the majority of users do not explicitly provide feedback, no response is also considered positive implicitly. Segmentation by User Attributes Use the user_context column or pre-populated columns like country and band to group metrics by user attributes. FAQs What is the SLA for new data? Data is refreshed daily at 00:15 AM UTC with a 24-hour SLA. What data quality checks are used? Three types: PII exclusion checks, critical field population rules, and aggregate/trend-based validations against product metrics. What if no data is available? The response body will be empty for the given date range/persona.

================================================================================
# Data Connectors
URL: https://builder.ema.ai/integrations-data/data-connectors
================================================================================

Data Connectors Ema grounds every answer in reliable, current information. Data connectors make this possible by synchronizing internal files -- tickets, policies, wikis, spreadsheets -- and, when needed, carefully selected public-web pages. Together they create a single, continuously refreshed knowledge base that every AI Employee can cite with confidence. File Ingestion Ema offers three options for bringing enterprise documents into the platform. Begin with one and expand as your needs grow. How Ema Brings Data In Local upload -- Drag files onto the Canvas and validate parsing in seconds. Cloud-storage sync -- Connect Google Drive, SharePoint, OneDrive, Box, or Dropbox. Ema keeps its data updated with the linked storage provider. Knowledge-base APIs -- Link Confluence, ServiceNow, and similar platforms to keep wikis and runbooks fresh. The maximum per-file size supported for this ingestion type is 200 MB. All three paths feed a shared pipeline, so a bulk PDF import today and a SharePoint sync tomorrow do not require re-indexing. Knowledge Base APIs must be connected and authenticated from the Integrations page. Once connected, these connectors are available only from the Shared Configuration option. They are not available from specialized AI Employees like Recruiter or Document Generation. Knowledge Base Connector Scope Ema connects at the knowledge base level (or its equivalent in each platform), not at the instance or tenant level. When you connect a knowledge base, Ema ingests all content within it -- articles, folders, attachments, and nested categories -- automatically. Instance-level connections are not supported because they bypass access controls and segmentation, and introduce irrelevant content that degrades AI response quality. Terminology Across Connectors ConnectorEma Connects AtHigher Level (Not Supported)ConfluenceSpaceSite / InstanceSharePointSiteSite Collection / TenantNotionTeamspace or DatabaseWorkspaceServiceNowKnowledge BaseInstance If you need content from multiple knowledge bases or spaces, connect each one individually through the Integrations page. File-Format Support Support LevelFormatsProduction-readyPDF, DOCX, PPTX, TXT, HTML, MDLimitedXLSB, CSV, XLSX, XML, JSON, very long PDFs with complex tablesUnsupportedLegacy Office binaries, source code, audio or video, native Google Docs/Sheets/Slides Scanned documents pass through OCR, but diagrams are not interpreted. Add captions when images matter. OCR capabilities are actively being improved. Preparing for a Connector Roll-out Confirm every file is in a supported format. Set up OAuth scopes or service-account keys with read-only access. Test ten representative files to verify parsing quality and latency. Estimate daily volume and adjust concurrency settings to prevent large syncs from interfering with other operations. What to Expect at Runtime Markdown, HTML, and CSV files ingest almost instantly. Office files and text-only PDFs take a few seconds per megabyte. Image-heavy PDFs and media-rich presentations run three to four times slower. Fully scanned documents require an additional OCR pass. Security Fundamentals The security architecture integrates OAuth 2.0 for cloud sources and service-account credentials for on-premises systems. All webhook callbacks are digitally signed. Connector dashboards clearly display rate limits, enabling you to prevent potential overloads. Known Limitations and Mitigations XLSB files are partially supported. Consider exporting to XLSX format until native parsing becomes available. Very long PDFs with complex tables may flatten. Consider splitting the PDF or converting tables to CSV format. No image-semantic extraction. Include explanatory text adjacent to screenshots. Web Content Scraper Some business questions draw on information outside corporate systems -- partner portals, regulator updates, industry resources. The web content scraper captures this public content and folds it into the same index that serves internal documents. Purpose and Fit Common use cases where web scraping provides critical business value: Regulatory tracking -- Compliance teams reference new agency guidance without manual copy-paste. Supply-chain status -- Operations staff rely on carrier or supplier pages to predict delays. Investor messaging -- Finance groups pull public FAQs and statements to prepare earnings-call answers. How the Scraper Works CapabilityDetailCrawl depthFollows links up to two levels from each seed URLDomain scopeStays on the source domain; external links are skipped except PDFs, which are always downloadedContent typesExtracts HTML text and ingests any discovered PDF filesRefreshRuns on demand; resubmit the URL list whenever needed Supported and Unsupported Sites Site CategoryStatusPublic static HTMLSupportedPages with in-page PDF linksSupportedLight JavaScript sitesPartially supported at two-level depthPassword-protected, paywalled, CAPTCHA, heavy single-page appsNot supported in the current release Implementation Guidance Seed precisely with targeted URLs (for example, /support/faq) rather than the main website homepage to keep crawl times predictable. Stage and validate using a short list first; inspect parsed output in the dashboard, then widen scope. Plan runtime because a two-level crawl can take several minutes; allocate processing windows accordingly. Re-crawl when needed by submitting the URL list again whenever the source site posts significant updates. Connector-Specific Guides Confluence Data Connector

================================================================================
# Confluence Data Connector
URL: https://builder.ema.ai/integrations-data/data-connectors/confluence
================================================================================

Confluence Data Connector This guide describes how to connect your Confluence instance to the Ema platform using OAuth 2.0 and configure an AI Employee to ingest Confluence documents. Prerequisites An active Atlassian account with access to the Confluence spaces you wish to ingest. Administrator permissions on the Atlassian site (required to authorize the OAuth connection). The URL of the specific Confluence space or documents you wish to ingest. Part 1: Establishing the Connection Step 1: Access Integrations Navigate to the Ema platform's Integrations page. Select the All Apps tab and use the search bar to find "Confluence." Step 2: Initiate Connection Locate the Confluence application card. Click the Connect button at the bottom of the modal window. Step 3: Authenticate You will use the OAuth 2.0 flow: A window appears prompting you to sign in to your Atlassian account. You are redirected to the Atlassian authorization page. Review the permissions requested by Ema and click Accept/Authorize. Enter your Atlassian Domain (for example, mycompany.atlassian.net). Once authorized, you are redirected back to the Ema platform with a "Connection Successful" message. Part 2: Creating the AI Employee Step 4: Create New Employee Navigate to Ema's AI Employees page via the main dashboard. Click Create New Employee. Step 5: Configure Employee Profile Select an AI Employee template (for example, Conversation AI Employee). Fill in the required fields: Name, Description, and Type. Proceed to the configuration area once the basic profile is set up. Part 3: Workflow Configuration and Ingestion Step 6: Access Shared Configurations On the AI Employee configuration page, navigate to the Workflow Builder. Locate and click the Shared Configurations button in the top-left corner of the interface. Step 7: Add Data Source In the Shared Configuration modal, click the Add button and select the option to Upload Document or manage sources. Step 8: Select Confluence Search for the Confluence card within the data sources list and click Add Links. Step 9: Ingest Documents Paste the specific Confluence link you wish to ingest into the provided field. The system will begin processing the URL. Ema connects at the space level -- when you provide a space URL, all content within it (articles, nested pages, and attachments) is ingested automatically. Step 10: Verification Wait for the processing status to update. On success, you will see a confirmation indicating the files were successfully ingested. If ingestion fails, verify that: The OAuth connection is still active (re-authorize if the token has expired). The Confluence space URL is correct and accessible with your account. Individual files do not exceed the 200 MB per-file size limit. Part 4: Synchronization Settings Step 11: Configure Sync Options Once documents are ingested, you can manage their synchronization frequency to ensure data remains up to date. Manual Sync -- Click the three dots (...) in the root folder and click the Sync Now button. Automatic Sync -- Click the Auto Sync drop-down menu and select your preferred sync interval: 1, 7, 15, or 30 days. Automatic sync polls Confluence for changes at the selected interval and re-ingests only the pages that have been added, modified, or deleted since the last sync. This incremental approach minimizes processing time and keeps your knowledge base current without manual intervention. Troubleshooting SymptomLikely CauseResolutionConnection fails during OAuthAtlassian session expired or insufficient permissionsRe-authenticate with an account that has admin access to the target Confluence site.Ingestion status stuck at "Processing"Large space with many attachmentsAllow additional time. If it remains stuck for more than an hour, try re-ingesting the space URL.Some pages missing after syncPages were restricted in ConfluenceEnsure the authenticating user has read access to the restricted pages.Sync does not pick up recent editsAuto-sync interval has not elapsedUse Sync Now for immediate updates, or shorten the auto-sync interval.

================================================================================
# Data Extraction & Rule Validation
URL: https://builder.ema.ai/integrations-data/data-extraction
================================================================================

Data Extraction & Rule Validation What Is Document Intelligence? Document Intelligence dashboards are powerful, no-code interfaces that let you harness the full potential of your AI Employees without chatting with them. Think of it as a control panel where you can input data, trigger workflows, and see results structured cleanly, like a spreadsheet. Instead of managing interactions through conversation, dashboards let you run workflows with precision, monitor outputs, and review results -- all in one place. What Can You Do with a Document Intelligence Dashboard? Trigger workflows without chat -- Use the dashboard to run any workflow by directly providing multiple inputs. View outputs instantly -- Results are displayed in a structured, Excel-like table for clarity and monitoring. Stay in control -- Whether you are extracting data or validating rules, you can review and manage the workflow end to end. Example: Dashboard with Validation and Extraction Imagine a dashboard that accepts two inputs (like a document and metadata), runs both a Rule Validation Agent and an Extract Entities Agent, and presents the outputs -- structured entities plus rule-evaluation results -- in a clear table. Supported Agent Types While any agent can be added to a workflow, only select agents can publish outputs to the dashboard: Text Output Agents -- Any agent that generates plain text results. Extract Entities Agent -- Extracts structured entities from documents. Rule Validation Agent -- Evaluates custom rules against text or documents. Extract Entities Agent This agent extracts entities from provided documents based on defined extraction columns. It uses advanced language model configurations to accurately identify and extract relevant entities. Use Cases Extract key information (names, dates, locations) from contracts or legal documents. Automate data extraction from financial reports. Parse research articles to identify significant entities. Column Types For each column, enter the name of the entity and its description. Columns support various types: Text, Number, Boolean Groups -- Extract multiple fields at once (like objects) Multi-Value -- Support for arrays HITL (Human-in-the-Loop) Optional human-in-the-loop review lets users review and approve extractions before they are published. Inputs Documents -- The document you want to use for extraction. Extraction columns -- Create columns and define search instructions for each. The agent extracts and organizes data based on those instructions. Text Input -- Alternate or additional input to documents. Output Each extracted column gets published to the dashboard. You can also enable the confidence score for outputs using feature flags. Rule Validation Agent This agent validates rules against extracted data and documents. It ensures that the rules applied yield accurate and compliant results. Use Cases Validate compliance of documents with predefined standards. Check consistency and correctness of extracted data. Automate quality control processes by verifying rule adherence across documents. Inputs All Rules -- Standalone rules used to validate data quality, formats, and values. Instructions -- Extra guidance or notes if needed. Extraction Column -- Connects with the Extraction Agent to retrieve extracted values. Documents -- The document you want to validate the rules on. Text Input -- Additional text you want to validate your rules on. Output The agent returns a validation result as text, indicating whether the rules passed along with relevant details about the validation process. Nested Rules and Filtering Rule Validation also supports complex nested rules and filtering. These can be set up using the update_persona API call: Nested rulesets -- Set up nested rules for use cases like Prior Authorization. Aggregation expressions -- Combine rules using rule_id and boolean tokens like AND, OR, NOT. Filtering -- Rules can be applied conditionally based on defined filter criteria. Each rule has a field for filter_criteria and nested_rulesets. Optional Inputs for Dashboard AI Employees Dashboard AI Employees support optional inputs, allowing workflows to run even when some inputs are not provided. You can mark any input as optional, giving dashboards the flexibility to handle partial or varying data without blocking execution. ScenarioBehaviorRequired input missingWorkflow does not runOptional input missingWorkflow runs normallyInput used by multiple actionsRequired if any action needs it

================================================================================
# Embeddable Chat SDK
URL: https://builder.ema.ai/integrations-data/embeddable-chat-sdk
================================================================================

Embeddable Chat SDK The Ema Chatbot SDK empowers you to create branded, embedded chat experiences for Conversational AI Employees using just a few lines of code. Whether you are developing a customer support assistant, a sales concierge, an onboarding helper, or an internal team assistant, you have complete control over its appearance and behavior to align with your product's style and tone. Use Cases Brand customization -- Tailor the chatbot with your company's logo and color scheme. Personalized greetings -- Set a custom title and welcome message to greet users effectively. Source transparency -- Configure whether the AI Employee should publish its sources for responses. Domain security -- Whitelist specific domains where the chatbot is permitted to load. Website integration -- Embed a fully configured chatbot onto your website for enhanced user support or as a sales concierge. Configuring Your Chatbot Setting up your chatbot is a straightforward process. Define your branding, whitelist domains, generate your configuration snippet, and embed it into your website. 1. Define Your Branding Customize your chatbot's appearance and welcome behavior to align with your brand. You can also configure whether sources used to answer user queries are displayed. ConfigurationDescriptionExampleLogoURL of the logo displayed in the chat headerhttps://www.example.com/logo.jpgTitleTitle that appears at the top of the chat windowAI AssistantPrimary ColorThe primary theme color for buttons and accents#0a430dWelcome MessageA personalized message displayed when a user opens the chat"Hi there! How can I help you today?"showPoweredByShow "Powered by Ema" brandingtruetheme.baseFontSizeBase font size for the chat widget"14px"theme.fontFamilyFont family for the chat widget"inherit" You can also configure the option to "Hide sources from response", which determines whether the sources used to answer user queries are returned in addition to the response. 2. Whitelist Your Domains Specify the domains where your chatbot will be deployed. This ensures that only whitelisted domains are authorized to load the Conversational AI Employee SDK, enforced via Cloudflare Content-Security-Policy (CSP) rules. You can add multiple domains as needed. Click Add domain, enter the base URL (for example, www.example.com), and click Add. The new domain appears in the whitelist table with options to remove it if needed. Click Save to persist changes to the configuration and update Cloudflare rules. 3. Generate Your Embed Snippet Once your configuration is complete, you can embed the chatbot on your site with a single script tag. From "Add integration snippet to your website", click copy and paste the snippet into your HTML, ideally just before the closing </body> tag. Example snippet: (function (window, document, scriptTag, objectName, scriptSrc, scriptElement, firstScriptTag) { window[objectName] = function () { (window[objectName].q = window[objectName].q || []).push(arguments) } scriptElement = document.createElement(scriptTag) firstScriptTag = document.getElementsByTagName(scriptTag)[0]; scriptElement.id = "EmaChat"; scriptElement.src = scriptSrc; scriptElement.async = 1; scriptElement.type = "module"; firstScriptTag.parentNode.insertBefore(scriptElement, firstScriptTag); })(window, document, "script", "EmaChat", "https://chatbot.ema.co/sdk/widget.js"); window.EmaChat("init", { "projectId": "your-project-id", "personaId": "your-persona-id", "defaultOpen": false }); 4. Build and Iterate You can continuously refine your chatbot's appearance and behavior by updating configuration values or adding advanced options. Experiment with variations of your welcome message, test different AI Employees, and match the color palette to your brand identity. These updates automatically reflect on the deployed chatbot.

================================================================================
# File Tagging
URL: https://builder.ema.ai/integrations-data/file-tagging
================================================================================

File Tagging Tags are metadata labels associated with documents that provide additional context beyond the document's title or content. For example, a document titled "China Shift Policy" can be tagged with country:china. Unlike document titles, which may not always carry over to all chunks of the document, tags are consistently passed along with every chunk. This ensures that no matter where in the document a search lands, the context of what the document is about is preserved. Key Benefits Persistent context -- Tags travel with all document chunks, ensuring search relevance even when headings are not carried forward. Enhanced personalization -- Agents can prioritize results based on user attributes from the Tag Extractor agent (for example, if a user's region is China, documents tagged with "China" are ranked higher). This ensures chunks are most relevant, reducing noise from unrelated documents. Flexible organization -- Files can be grouped logically across multiple dimensions (for example, product, location, band). Features Metadata-based search -- Tags add a structured layer of information, improving precision in search and retrieval. Custom tag creation -- Tags can represent multiple categories like country, product name, or band. Tags can also be multi-level (accepted up to 3 levels). Taggable file uploads -- With the FileUploadWidget, users can associate previously created tags with new documents. Validity dates -- A type of tag that allows users to add a "Valid from" date and/or "Valid till" date for each document. These are auto-extracted when there is a clear "Valid from DD/MMM/YYYY and Valid till DD/MMM/YYYY" line on the first page of the document. They can be manually added as well and are used to expire documents after a certain date or make documents available only after a certain date. How to Use Set Up Tags Manually add all tags and possible levels using the File Tagging Widget (available by default when the EX template is used). Tag Files Manually When uploading files using the FileUploadWidget, assign the tags created earlier with each file. Bulk Tag Files You can also bulk tag files by clicking on Bulk Upload and uploading the file tags in CSV format. Managing Validity Dates Validity dates are auto-extracted from files when there is a clear "Valid from DD/MMM/YYYY and Valid till DD/MMM/YYYY" line on the first page of the document. They can be manually added or edited. Files take one of four states when validity-date-based filtering is activated in the Knowledge Search Agent: Valid FromValid TillBehaviorPresentPresentDocument is valid within the specified date rangePresentAbsentDocument is valid for all dates after "Valid from"AbsentPresentDocument is valid for all dates up to "Valid till"AbsentAbsentDocument is always valid Leverage Tags in Search Tags are always passed alongside content chunks. Agents and retrieval systems can prioritize or filter search results using these tags for higher accuracy and relevance. If "Filtering based on validity dates" is enabled in the file search agent, files that are invalid as of the user query date will not be searched. Documents without validity dates are always searched.

================================================================================
# List of Intelligent Action Integrations
URL: https://builder.ema.ai/integrations-data/integration-list
================================================================================

List of Intelligent Action Integrations This is the current catalog of integrations available for use via the Intelligent Actions agent. Not all integrations may be enabled in your environment or tenant. Contact your Ema representative to enable any that you do not see. CRM Apollo Salesforce HubSpot Kommo Pipeline CRM Dynamics 365 Ticketing ServiceNow Jira Freshdesk Helpdesk HR & Recruiting Workday Greenhouse BambooHR HackerRank Work Ashby SAP SuccessFactors Communication Gmail Outlook Finance Coupa Stripe File Storage Google Drive Communication & Collaboration Slack Slackbot Microsoft Teams Google Meet Zoom Webex Chatwork Agent Mail Zoho Mail RetellAI Project & Work Management Linear Wrike Productboard Process Street Streamtime Breeze Onedesk Asana Monday Documentation & Knowledge Management Notion Confluence Coda Google Docs Writer Design & Whiteboarding Figma Miro Affinity File Storage & Sharing Dropbox OneDrive SharePoint Sales & Revenue Operations Close Salesmate Capsule CRM Forcemanager PersistIQ Marketing & Customer Engagement ActiveCampaign Intercom Gong Mopinion Customer Support & Service Freshservice Helpdesk Servicem8 Plain Finance & Accounting Zoho Books Zoho Invoice Zoho Inventory FreshBooks Xero SevDesk Ramp Flutterwave Square Excel Fixer Analytics & Data Google Analytics Snowflake Snowflake Basic ClickHouse Alpha Vantage Mixpanel SerpAPI Gemini Databases & Backend Infrastructure Ably Developer Tools & DevOps Bitbucket GitLab Docker Hub Identity, Security & Compliance Cloudflare IdentityCheck Ip2Proxy FraudLabs Pro Forms, Documents & E-Signature Formsite Docuseal PdfMonkey Prospecting & Data Enrichment ZoomInfo RocketReach Dropcontact FullEnrich BrightData Stack Exchange Productivity & Task Management Google Tasks Todoist Customer Feedback & Research Mopinion Admin & Productivity Suites Google Admin Google Slides

================================================================================
# Intelligent Actions (External Tool Caller)
URL: https://builder.ema.ai/integrations-data/intelligent-actions
================================================================================

Intelligent Actions (External Tool Caller) The Intelligent Actions agent (previously called External Tool Caller) lets an AI Employee execute concrete actions -- such as creating a ServiceNow ticket, filing PTO in Workday, or updating a Salesforce opportunity -- directly inside the target system, without writing code. More than 200 pre-integrated connectors are available, giving you immediate coverage across HR, CRM, ITSM, finance, and collaboration. Common Scenarios ScenarioExample SystemsTypical OutcomeEmployee AssistantWorkday, JiraSubmit time-off requests; open or update IT ticketsFinance & AuditCoupa, SAP, NetSuiteGenerate purchase orders; reconcile ledgersSales IntelligenceSalesforce, HubSpotEnrich leads; advance opportunity stages Agent Anatomy ElementDescriptionInputsUser query and, if needed, conversation historyConfigurationAllowed apps and tools (for example, Create Ticket in ServiceNow) plus high-level instructions that help the AI Employee choose the correct actionOutputRaw JSON returned by the external system; downstream blocks transform this into end-user-friendly text The decision engine inside the block evaluates the request, selects the appropriate tool, fills required parameters, executes the call, and returns the result for post-processing. Using Pre-Built Tool Support 1. Connect the App Open the Integrations page and choose the target application (for example, ServiceNow). Select Connect against the "Intelligent Actions integration" field and complete OAuth or key-based authentication. When the connector card shows Connected, the application is available for use within the current tenant. Note: If you do not see "Intelligent Actions integration" for an app you want, reach out to your Ema sales representative so it can be prioritized for your account. Apps like Salesforce require the customer's account to be allow-listed first. See Salesforce Setup for detailed steps. 2. Enable Specific Tools Now that the connection to the desired application is enabled within your tenant, activate the tools you need. Within the same application panel, switch to the Tools tab and enable only the desired actions (for example, Create Ticket, Update Ticket Description). This gives you granular control over which actions are in scope per application within your tenant. 3. Add Intelligent Actions to Your Workflow Drag the Intelligent Actions agent onto your workflow canvas. Connect it to the appropriate input source -- typically the workflow trigger or a prior logic block that handles user queries. You can feed output from other agents using the Additional Context configuration in the agent. To display the output of the tool call, link a Respond with Tool Result or Respond agent immediately downstream. This response agent interprets both the original input query and the raw output from the Intelligent Actions agent, applying your configured instructions to return a user-friendly response. Configuring the Intelligent Actions Agent Once the Intelligent Actions agent is selected, a configuration panel appears on the right. Click + Add to open the tool selection menu. Choose your target application (such as ServiceNow) and select the specific tool actions you want to enable -- for example, Create Ticket, Update Due Date, or Add Ticket Comment. After selection, the tools are listed under Tools and are ready for parameter configuration. A single Intelligent Actions agent can support multiple applications and tools. It intelligently selects the appropriate tool within the correct system based on the context of the incoming user query and any additional conversation context provided. Parameter Configuration Each tool may require a different set of input parameters. For example, when creating a ticket in ServiceNow, fields such as Priority, Short Description, and Assignee Email need to be passed along with the tool call. Click Manage against any tool to open its parameter configuration screen. For each input, you can specify how the value is prefilled: Auto fill by Ema -- Dynamically extracts parameter values from the ongoing conversation context. This is the default behavior and helps automate data capture based on user input. Fixed value -- A specific constant that should always be used for a parameter. For example, you may want the User ID to always default to a predefined value. Enabling Human-in-the-Loop (HITL) Review Ema can intelligently pause execution and hand off control to a human reviewer before proceeding with a tool action. When HITL is enabled, the agent prompts the user with a confirmation step. You can configure the message text and button labels to suit the tone and context of your workflow. You may also choose to hide specific parameters from the confirmation view (such as internal fields like User ID) to maintain clarity and protect sensitive data. Finding Available Tools To view the full list of tools available for any app: Go to Integrations page. Select All Apps. Click an App. Select the Tools tab to see the list of available tools. For the complete catalog of supported integrations, see Integration List.

================================================================================
# Salesforce Integration Setup
URL: https://builder.ema.ai/integrations-data/salesforce-setup
================================================================================

Salesforce Integration Setup When connecting Salesforce from the Ema Integrations page, you will see three options for authentication. Authentication Options Option 1: Provide Your Own Salesforce App (Recommended) Most clients prefer this method. You configure and provide your own Client ID and Client Secret. The steps for creating and configuring your Salesforce Connected App, setting permissions, and completing setup are documented in detail below. Option 2: Salesforce Production Account This method uses Ema's Client ID and Client Secret. Clients still log in with their own Salesforce user credentials. On the Ema Integrations page, choose "Salesforce Production Account." A login page opens -- use your Salesforce credentials to log in. After login, the Salesforce Admin will see Ema's app listed under Connected Apps (Salesforce > Settings > Connected Apps). The Admin must click Install to finalize the connection. Once installed, Ema can use this connection. Option 3: Salesforce Sandbox Account Choose this option when testing in a Salesforce Sandbox (login URL starts with https://test.salesforce.com instead of production https://login.salesforce.com). On the Ema Integrations page, click on Salesforce Sandbox Account. Log in with your sandbox user credentials. If your org uses a custom domain, click Use Custom Domain, provide your domain, and continue login. Once logged in, the Salesforce Admin will see Ema's app listed under Connected Apps. It will show as uninstalled until the Admin explicitly installs it. Once installed, the sandbox integration works the same way as production. Detailed Instructions: Provide Your Own Salesforce App Step 1: Navigate to the Ema Integrations Page Go to the Integrations page in the Ema Portal. All Apps > Salesforce. Select Connect on Intelligent Actions integration. Select Provide your own Salesforce App. Note the Redirect URL and Permissions (three) displayed on the screen -- these are used in Step 2. Step 2: Create / Configure a Salesforce Connected App Sign in to Salesforce, click the gear icon > Setup. Go to Platform Tools > Apps > App Manager. Click New External Client App (or open an existing one). Give it a name and contact email. In API (Enable OAuth Settings): Check Enable OAuth Settings. In Callback URL, paste the redirect URL from Step 1 (for example, https://passport.paragon.ema.co/oauth). Select the OAuth scopes as shown on the Ema Integration login screen. In Flow Enablement, select Enable Authorization Code and Credentials Flow. In Security, disable "Require PKCE" if it is enabled. In Security, enable Require secret for Refresh Token Flow. Click Create. After saving, copy the Consumer Key and Consumer Secret from the app's OAuth Settings. Note: Salesforce may take a few minutes to propagate a new Connected App. If you receive a 403 Forbidden error when entering the Client ID and Client Secret on the Ema Integration page, wait 5-10 minutes and retry. Step 3: Set Up Permissions for the Connected App Create the permission set: In Salesforce Setup, go to Users > Permission Sets. Click New and fill in: Label: Ema Integration Access (or any name you prefer) API Name: auto-fills when you click the field User License: -- None -- (important so you can assign it to any user) Description: (optional) "Ema connected app" Click Save. Turn on the special permission: Once saved, under System, click System Permissions. Click Edit. Find Approve Uninstalled Connected Apps (use browser Find: Ctrl/Cmd+F). Check the box and Save. Assign it to a user: Click Manage Assignments > Add Assignments. Select at least one user who will perform the Salesforce authorization. The user should be an admin; select no expiry when assigning. Click Assign > Done. If the App status is not enabled in External Client App Manager: Have the assigned user go to the Ema Integrations Page > Salesforce integration settings and connect their Salesforce account. In Salesforce Setup, go to Connected Apps OAuth Usage (Quick Find: "Connected Apps OAuth Usage"). Find your app in the list and click Install. Step 4: Establish Connection from Ema and Enable Tools Go back to the Salesforce login from the Ema Integrations page (same as Step 1). Enter the Salesforce Client ID and Client Secret, then click Continue. You will be redirected to the Salesforce login page. Log in using the same credentials as the assignee from Step 3. When prompted, select Allow. After login, enable the tools on the next tab so they can be used in AI Employees. Step 5: Use Salesforce in an AI Employee Add the Intelligent Actions agent in the AI Employee workflow. In agent configuration, go to + Add. Select Salesforce. Add all tools you want to include in the agent. (Optional) Configure each tool separately as needed.

================================================================================
# Templates
URL: https://builder.ema.ai/templates
================================================================================

Templates This section provides guides for deploying and customizing pre-built AI Employees by Ema. Introduction AI Employee Templates are reusable, modular, and production-ready workflow blueprints designed to simplify the process of deploying AI-powered automation in the Ema ecosystem. Each template encapsulates all the required components -- structured prompts, configured tool actions, multi-agent workflows, and system logic -- to enable teams to go live quickly with minimal customization. With over 30 templates currently available (and more being developed), these workflows cover a wide array of common use cases across support, sales operations, document automation, analytics, and more. Ema collaborates with partners and customers to create new templates that incorporate domain expertise and technical knowledge to build reusable AI Employees. Templates created for one partner are only available to their builders and customers. To view the templates available to you, scroll down on your AI Employee dashboard or click the + New Employee button. What Is an AI Employee Template? At its core, a template is a reusable pattern that instantiates an AI Employee with a defined purpose, structured interactions, and optional tool integrations. Templates are not rigid; they are designed to be extended, customized, and adapted to various data sources and environments. For most use cases, you can directly use a pre-built template to launch an AI Employee quickly. Where required, you can also modify the template to customize the AI Employee to specific needs. An AI Employee template includes: A pre-configured multi-agent workflow with logic that orchestrates tasks such as file retrieval, ticket updates, structured query response, or system calls. Clear instructions and prompt formatting to ensure consistency in tone, terminology, and data presentation. Integration hooks for external systems like ServiceNow, CRMs, knowledge bases, or file systems. Placeholder values and editable components that allow users to configure and tailor the final deployed instance. Templates are not connected to live data or systems by default. They are designed as launch-ready frameworks that allow teams to plug in their data sources and go live. Why Use Templates? Templates are essential to scaling AI Employee deployment because they reduce redundancy, accelerate prototyping, and improve quality. They serve as a shared knowledge base that reflects best practices across the ecosystem. High-quality templates enable teams to: Deliver working workflows in minutes instead of hours or days. Reuse known-good patterns rather than reinventing logic for each deployment. Rapidly generate demos for customer discussions or internal pilots. Minimize builder onboarding and training through structured, documented flows. Provide a baseline for experimentation, versioning, and iterative improvements. Anatomy of a Template 1. Defined Workflow Architecture Templates can use either: GWE (Generative Workflow Engine) agents -- Execute multi-step tasks via specified workflows and tool calls. Non-GWE agents -- Expose UI widgets for custom configuration. Each agent is connected with decision logic, data pipelines, and task triggers to allow intelligent interaction based on user input and external signals. 2. Role-Specific Instruction Layer Templates include detailed instruction sets for how each agent should interpret queries, retrieve data, and generate responses. These include rules for formatting answers, terminology to include or avoid, and response strategies. 3. External Tool Integrations Templates include optional, pre-wired connectors for external platforms like CRMs, file storage systems, analytics tools, or ticketing platforms. These can be quickly configured by admins to match internal environments. 4. Template Description and Metadata Each template has a name, description, and metadata to make it easily discoverable. Naming conventions prioritize clarity and brevity (ideally four words or fewer). Discovery and Access Templates can be discovered and accessed through: the Ema platform Builder chatbot In-product search and filtering Templates may be scoped at the environment, tenant, or global level. Currently, only admins can create and edit templates, but broader access levels are expected in future platform updates. AI Employee Templates are the foundation for scalable, repeatable, and high-quality deployments on Ema. By using templates, teams can move faster, deploy smarter, and deliver more consistent results without starting from scratch every time. Using Templates Select one of the template cards under "Create an AI Employee." Each corresponds to a different AI Employee template and comes with unique functionalities. Templates are instantiated by copy, so updates to the template do not retroactively change existing AI Employees built from it. Ema is happy to collaborate with partners and customers to create new templates that incorporate your domain expertise and Ema's technical knowledge to create reusable AI Employees. Templates created for one partner are only available to their builders and customers. Available Templates TemplateDescriptionCustomer Support AI EmployeeAssist customers with questions and post-sales supportSales Concierge AI EmployeeEngage visitors and drive conversionsAgent Assist StarterHelp support teams answer helpdesk ticketsLeadership Recruiter AI EmployeeAI-powered executive talent discoveryEmployee AssistantInstant resolutions for employee queriesResume Analysis Assistant (Coming Soon)Resume parsing and candidate scoringDocument Proposal AI EmployeeAI-powered PPT proposal creationSales Engineer AI Employee (Coming Soon)Answer technical sales questionsPrior Authorization AI Employee (Coming Soon)Healthcare drug eligibility assessmentKnowledge Base Auditor AI Employee (Coming Soon)Validate KB articles against real conversationsSales Intelligence AnalystCompany research and intelligence reportsContract Evaluation AssistantExtract and assess contract termsInsurance FNOL AI Employee (Coming Soon)Automate first notice of loss intakeReimbursement AI EmployeeInvoice validation against policiesVoice of Customer AI EmployeeAnalyze customer feedback at scaleSales Development RepresentativeAutomated outbound sales developmentRecruiterAI-powered hiring and candidate engagement

================================================================================
# Agent Assist AI Employee
URL: https://builder.ema.ai/templates/agent-assist
================================================================================

Agent Assist AI Employee Provides assistance to support teams answering helpdesk tickets either by directly responding to the customer query, or providing recommendations to support teams via private notes. Overview Ema's Agent Assist AI Employee provides seamless, conversational assistance to your customers and agents over helpdesk tickets. Key capabilities: Receives and interprets incoming support tickets from your ticketing systems (Zendesk, Freshdesk, ServiceNow, etc.). Drafts personalized, context-aware responses by leveraging your knowledge base. Automatically categorizes tickets and responds based on instructions given to Ema, while smartly deferring to humans when escalation is needed. This workflow is instantiated by copy, so any changes to the template will not retroactively affect existing AI Employees built from it. Key Features Ticket classification and routing -- Automatically categorizes tickets (for example, billing, technical, returns) and suggests next-best actions or escalation paths. Context preservation -- Summarizes past interactions and ongoing tickets, helping agents maintain continuity across multi-touch conversations. Grounded, high-quality response generation -- Pulls in relevant articles, order histories, and product specs to craft accurate, on-brand replies. Compliance and tone adaptation -- Ensures every reply adheres to your company's style, legal, and privacy guidelines, and adjusts tone based on customer sentiment. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of this template page. 2. Connect Your Ticketing App and Knowledge Base Choose from supported integrations or configure a custom connection to your helpdesk and upload internal documentation. 3. Define Ticket Categories and Provide Instructions Describe categories that incoming tickets can be classified into. Provide instructions to follow the SOP, escalation criteria, and any custom ticket fields or tags you use. 4. Set Tone and Compliance Guidelines Provide style instructions, response templates, language preferences, and any regulatory requirements via respond agents. 5. Enable and Test Turn on your AI Employee. Try asking a supported query by creating a sample helpdesk ticket and make sure you receive the expected response.

================================================================================
# AI SDR
URL: https://builder.ema.ai/templates/ai-sdr
================================================================================

AI SDR Ema's AI SDR is an always-on, high-performing sales development assistant designed to supercharge pipeline generation. Built for sales and marketing teams, this AI Employee automates the entire outbound prospecting workflow -- from lead sourcing and enrichment to personalized email outreach and follow-ups. It enables businesses to book more meetings per AE at a fraction of the cost, all while continuously improving through built-in experimentation and smart deliverability management. Whether you are looking to expand into new markets or boost conversions from your current list, Ema's AI SDR ensures your team focuses on what matters most: closing deals. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Targeted lead generation -- Identifies high-intent prospects using real-time signals, public data, CRM imports, and Ema's in-house scoring models. Combines contact, intent, and first-party data for precision targeting. Hyper-personalized messaging -- Crafts email sequences tailored to each lead's role, company, pain points, and buyer journey stage. Messaging reflects your tone, best practices, and product strengths. Self-learning campaign optimization -- Tracks key metrics like open and reply rates to test variations, identify winning messages, and refine future outreach strategies automatically. Smart email deliverability -- Built-in tools for domain health monitoring, list hygiene, email warm-up, and regulation compliance ensure your emails hit inboxes -- not spam folders. Multilingual and adaptive communication -- Connect with global prospects. Ema writes fluent, native-level messages in multiple languages and mimics your team's email style using past communications. Inbox-ready sequences -- Generates full email sequences per lead, including thoughtful follow-ups, links to case studies, and relevant CTAs. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Define Your Target Audience Specify your ideal customer profile, including industry, company size, job titles, and geographic focus. 3. Configure Messaging Upload email templates, style guides, or past outreach examples so Ema can match your brand voice. 4. Enable and Test Turn on your AI Employee. Review generated lead lists, email sequences, and campaign metrics in the dashboard. Benefits Boost meeting volume -- Multiply qualified meetings per AE without adding SDR headcount. Reduce cost per opportunity -- Achieve significant ROI by replacing manual prospecting with intelligent automation. Stay on-brand and on-message -- Adapt messaging to reflect your company's voice and product positioning with ease. Scale globally with confidence -- Run multilingual campaigns across geographies, markets, and industries. Build a predictable pipeline -- Turn outreach into a repeatable, data-driven engine for top-of-funnel success. Supported File Formats CSV (lead imports) DOCX or TXT (email templates, style guides) Public web content (for enrichment and buyer research) CRM integration (for lead sync and status tracking)

================================================================================
# Contract Evaluation AI Employee
URL: https://builder.ema.ai/templates/contract-evaluation-assistant
================================================================================

Contract Evaluation AI Employee Ema's Contract Evaluation Assistant AI Employee streamlines legal and compliance workflows by extracting key terms from business contracts and assessing them against organizational rules. Designed for legal, sales, and compliance teams, this AI Employee helps detect risks and compliance discrepancies early -- before contracts are finalized. Capable of reading lengthy Statements of Work (SoWs), including those with complex tables and embedded visuals, it enables fast, explainable evaluation without requiring legal expertise. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Comprehensive contract parsing -- Supports extraction from long, complex documents across multiple formats -- including those with tables, annexures, and images. Natural language extraction -- Describe what you need ("contract value," "termination clause," or "maximum liability") and Ema finds and extracts it accurately. Reliable rule-based assessment -- Evaluate contracts against internal policies by providing rules in natural language. The assistant returns assessments with source-backed justifications. Proactive risk identification -- Detect and flag issues like missing terms, risky clauses, or non-compliant language so they can be corrected before legal review. Self-serve for sellers -- Sales and operations teams can pre-check contracts against standard criteria, reducing legal backlogs and enabling faster deal cycles. Source traceability with "Show Work" -- Every flagged issue or extracted term includes reasoning and document traceability for easy verification. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Add Contract Criteria Provide evaluation rules in plain English (for example, "maximum liability should not exceed contract value"). 3. Enable and Test Turn on your AI Employee. Upload contracts to the dashboard and see extractions and assessments in real time. Use "Show Work" to view source evidence and rationale. Example Queries Extract contract value, governing law, and payment terms. Does this contract comply with our liability policy? Highlight any risky indemnity clauses. Check if the termination period meets our standard. Benefits High-quality contract parsing -- Handles complex, unstructured contract formats with ease. Accurate, configurable extraction -- Tailor extraction targets with simple natural language prompts. Catch issues early -- Flag discrepancies and risks before contracts reach legal teams. Speed up deal closures -- Empower sales teams to self-validate contracts and reduce review cycles. Maintain compliance standards -- Ensure contracts are always aligned with internal policies and thresholds. Supported File Formats PDF DOCX Scanned documents with tables or annexures Contract templates and standard SoWs

================================================================================
# Customer Support AI Employee
URL: https://builder.ema.ai/templates/customer-support-assistant
================================================================================

Customer Support AI Employee Assist customers by recommending products, answering their questions, and providing post-sales support. Overview Ema's Customer Support AI Employee provides seamless, conversational assistance to your customers during and after purchase. It can be hosted on your website or app to troubleshoot issues, answer product questions, and automate post-sales support -- all while responding naturally to small talk and guiding users with empathy and efficiency. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Seamless, multi-turn conversations -- Understands customer intent and context to provide personalized, dynamic responses. Smart knowledge base search -- Simply provide your helpdesk URLs or knowledge base articles and the AI Employee can search over them. Feedback and escalations -- Asks for user feedback and allows you to configure escalation paths for negative feedback. Web widget (SDK) to host on your website -- Customize to your brand colors and guidelines and go live in a few easy steps. Trusted AI that keeps you in control -- Grounded in your data and policies, ensuring transparency, compliance, and adherence to your SOPs. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Configure Your AI Employee Add knowledge base: Provide relevant documentation like helpdesk articles, product information, and policies. You can either upload PDF files or provide the web URLs to your website and Ema can automatically crawl them. Customize instructions: Go to the workflow builder and review the current configuration. Add the relevant categories and category descriptions in the intent classifier. Review the instructions provided in the various respond agents and ensure they reflect your company name and context. Look for placeholders in the instructions and replace them with your company name. Remember to publish the workflow outputs if you are adding a new respond agent. Customize your SDK: Provide a welcome message, upload a logo, and decide a name for your chatbot. If you do not want Ema to show sources, enable the "hide sources" option. Decide if you want to ask for end-user feedback and how often. 3. Enable and Test Turn on your AI Employee. Try asking a supported query in the SDK and make sure you receive the expected response. To add to your website, whitelist your domains and copy the JavaScript snippet and add it to the <body> section of your website. Learn more about domain whitelisting in Embeddable Chat SDK. Example Queries I received a damaged product Good evening / Good morning What is your refund policy? I want to cancel an order

================================================================================
# Document Proposal AI Employee
URL: https://builder.ema.ai/templates/document-proposal-manager
================================================================================

Document Proposal AI Employee Pre-built workflow template for AI Employees that creates high-quality PPT proposals in minutes using enterprise golden data. Overview The Document Proposal Manager is part of Ema's Document Generation suite, offering a pre-built, end-to-end workflow that: Creates high-quality document proposals from enterprise content accurately and in minutes. Leverages AI to help generate and refine content with natural language instructions. Enables seamless collaboration with peers via comments and version control capabilities. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features AI-powered content creation -- Instantly creates accurate and visually enriched content (text, images, charts) from your content repository in minutes. Regeneration using natural language -- Edit content manually or provide instructions in plain English to refine content. Traceable and explainable -- Access a full work log with source references for the content generated. Collaboration and control -- Leave comments and revert versions to collaborate seamlessly within your team. Enterprise branding and consistency -- Every slide adheres to pre-configured brand themes ensuring polished, uniform presentation. Secure and compliant -- Built-in de-identification and data protection ensure privacy and regulatory adherence. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Configure Your Parameters Upload content repository -- Upload source data that Ema should use to recommend and generate content from. 3. Enable and Test Turn on your AI Employee. Create a project -- upload an RFP, a response template (with added instructions for each section), and a style guide. Supported File Formats DOCX, PDF

================================================================================
# Employee Service AI Employee
URL: https://builder.ema.ai/templates/employee-assistant
================================================================================

Employee Service AI Employee Harness Agentic AI powered by your enterprise data to deliver instant resolutions and seamless actions to employees, all from a single place. This intelligent system transforms traditional employee support from reactive ticket-based systems into proactive, conversational assistance that operates 24/7. Key Features Natural language employee support -- Ask questions in plain English about policies, benefits, IT issues, or any work-related topic. The AI understands context, interprets intent, and delivers precise, personalized answers instantly. Enterprise application integration -- Seamlessly connect with 200+ enterprise applications including ServiceNow, Jira, Workday, SharePoint, Confluence, and more. View tickets, submit requests, check leave balances, and complete workflows without switching between applications. Personalized context awareness -- Every response is tailored to the employee's role, location, department, and access permissions. Multi-platform accessibility -- Deploy across Microsoft Teams, Google Chat, web portals, mobile apps, and email. Intelligent workflow automation -- Execute complex multi-step processes through simple conversational requests. From expense report submissions to leave applications, software license requests to IT troubleshooting. Action-oriented capabilities -- Create Jira tickets, submit ServiceNow requests, apply for leave, update personal information, and trigger approval workflows directly through conversation. Continuous learning and improvement -- Admin dashboards provide interaction insights and feedback collection. How to Use 1. Deploy Your AI Employee Assistant Configure your Employee Assistant through Ema's platform. Upload organizational documents and policy materials. Integrate with communication platforms (Teams, Slack, Google Chat). 2. Train on Organizational Knowledge Ingest policy documents, handbooks, and knowledge base articles. Configure location-specific and role-specific policy variations. Configure personalization rules for different employee bands/levels. Set up real-time data synchronization with enterprise systems. 3. Set Up Tool Calling Connect your enterprise applications (ServiceNow, Jira, Workday, etc.). Define parameters to intake and actions to be performed (for example, apply for leave, access payroll). 4. Launch Employee Experience Deploy across chosen communication platforms. Monitor interactions and gather feedback through admin dashboards. Continuously refine configuration based on employee usage patterns. Example Use Cases ScenarioApproachExpected ResultsPolicy and Benefits InquiriesHandle complex, personalized policy questions considering employee location, band, and role95% accuracy without human interventionIT Support AutomationTroubleshoot common issues, password resets, software requests; create tickets for complex problemsInstant resolution of IT requestsHR Service ManagementProcess leave applications, expense submissions, personal information updatesSignificant reduction in HR support ticket volume Integration Capabilities HR and ITSM Platforms: ServiceNow, Jira, Workday, SAP SuccessFactors, and more. Communication and Collaboration: SDK, Microsoft Teams, Google Chat. Knowledge Management: SharePoint, Confluence, Google Drive, Box/Dropbox, and more. Productivity and Business Applications: Office 365, Google Workspace, Salesforce, custom enterprise applications via API.

================================================================================
# Insurance FNOL AI Employee
URL: https://builder.ema.ai/templates/insurance-fnol-assistant
================================================================================

Insurance FNOL AI Employee Ema's Insurance First Notice of Loss (FNOL) Assistant AI Employee automates the initial step of the claims process by extracting key information from customer-submitted documents and filling out the FNOL template required by insurance providers. Built for insurance operations and claims processing teams, this assistant handles a wide variety of document types, formats, and languages -- ensuring faster, more accurate claim intake. From handwritten police reports to multilingual emails and scanned bills, this AI Employee parses it all with built-in OCR and translation capabilities to generate structured FNOL records with minimal manual intervention. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Multi-format document parsing -- Supports PDFs, scanned images, emails, handwritten forms, and structured documents -- even when they contain tables or embedded visuals. Built-in OCR and translation -- Automatically reads scanned documents and translates content from different languages to ensure all claims are processed uniformly. Configurable field extraction -- Extracts itemized details such as product names, prices, quantities, vendors, and other claim-relevant fields as defined by your FNOL template. Template population -- Automatically fills out the FNOL claim form with structured data extracted from uploaded documents -- ready for downstream processing or review. Accelerated claims intake -- Cuts down on the manual effort and time required to process new claims, enabling faster response to customers and reduced backlog. Audit-friendly outputs -- Extracted data includes source traceability, making it easy to validate entries and meet compliance needs. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Configure Your FNOL Template Define the fields your FNOL form requires (e.g., claimant name, date of loss, loss description, policy number). The AI Employee uses these field definitions to structure its extraction. 3. Upload Customer Documents Add initial claim forms, police reports, invoices, emails, or any supporting documentation. The assistant will process each file automatically. 4. Enable and Test Turn on your AI Employee. Upload a sample claim package in the dashboard and review how the FNOL form is completed. Use "Show Work" to trace each field's origin. Example Queries Fill out an FNOL using these documents. Extract item details from this invoice. Is the police report missing any required data for the FNOL? Translate this email and pull out the key facts for the claim form. Benefits Speed up claim intake -- Automate form population to accelerate time-to-processing for new claims. Handle diverse document types -- Accepts and processes structured, unstructured, scanned, and multilingual inputs. Reduce manual errors -- Improve accuracy with automated extraction and template filling. Improve customer experience -- Respond to new claims faster with fewer back-and-forth requests for missing information. Ensure compliance and traceability -- Every data point can be traced back to its source for full auditability. Supported File Formats PDF DOCX Scanned images (JPEG, PNG) Emails (EML, MSG, or pasted text) FNOL form templates (uploadable or pre-configured in dashboard)

================================================================================
# Knowledge Base Auditor AI Employee
URL: https://builder.ema.ai/templates/knowledge-base-auditor
================================================================================

Knowledge Base Auditor AI Employee Ema's KB Auditor AI Employee automates the maintenance of support documentation by validating knowledge base (KB) articles against real-world customer support conversations. Designed for CX and documentation teams, this AI Employee continuously scans for outdated or incorrect content, identifies discrepancies, and suggests evidence-based updates -- all grounded in actual user interactions. By aligning help content with live product behavior and customer needs, it reduces support volume, enhances self-serve accuracy, and builds trust with end users. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Real-time validation of help content -- Compares existing KB articles against customer support transcripts to spot and highlight outdated or inconsistent information. Evidence-backed suggestions -- Proposes edits and updates based on actual customer language, product behavior, and UI flows captured in transcripts. Scalable content maintenance -- Replace periodic, manual audits with an always-on system that monitors documentation and flags issues as they arise. Reduced support load -- Ensure customers find correct answers through search or chatbot, deflecting tickets and decreasing agent workload. "Show Work" for transparency -- Every proposed change is linked to specific conversation examples, so you can review and approve with confidence. Aligned with product evolution -- Helps documentation stay in sync with product updates, bug fixes, and UI changes that may not be reflected in older KBs. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Provide KB Articles Upload the knowledge base articles you want Ema to audit. 3. Enable and Test Turn on your AI Employee. Use the chat to validate responses and explore recommended updates. Use "Show Work" to trace the source of each suggestion. Example Queries Is this KB article still accurate? Show me updates based on recent conversations. What parts of this article are outdated? Recommend changes to reflect the current product UI. Benefits Keep docs aligned with reality -- Ensure support content mirrors actual user issues and product behavior. Reduce repeat tickets -- Empower customers with accurate self-serve answers and free up agent time. Scale with confidence -- Maintain quality across hundreds of KBs without increasing team overhead. Build end-user trust -- Deliver consistent, up-to-date guidance that reinforces reliability and transparency. Supported File Formats PDF DOCX HTML or markdown-based KB exports Customer support transcripts (text or JSON)

================================================================================
# Leadership Recruiter AI Employee
URL: https://builder.ema.ai/templates/leadership-recruiter
================================================================================

Leadership Recruiter AI Employee Ema's Leadership Recruiter is an AI-powered leadership hiring platform that revolutionizes how you identify and hire executive talent. This intelligent system transforms weeks of manual screening into automated candidate discovery, assessment, and engagement processes that run 24/7, helping you find exceptional leaders in weeks, not quarters. The platform combines natural language search capabilities with deep social media insights, real-time news monitoring, and personalized engagement tools to discover hidden leadership gems and accelerate your hiring process while reducing bias through AI-powered evaluation. Key Features Natural language companies search -- Describe what you are looking for in plain English. The AI understands your preferences, identifies patterns, and uncovers hidden leaders from the best companies to grow your talent pool fast. Social media intelligence -- Analyze candidate profiles across public and private data sources to generate comprehensive leadership scorecards. Decode leadership styles, communication patterns, cultural fit indicators, values alignment, and growth potential. Real-time news monitoring -- Monitor career movements, company restructuring, acquisitions, and growth announcements. Predict when high-caliber executives might be ready for their next move. AI-generated personalized outreach -- Create compelling, personalized email drafts based on deep understanding of candidate profiles, job requirements, and search criteria. Scorecards -- Get faster and clearer signals for candidate shortlisting using scorecards against criteria defined in search details. Scores range from 1-5: Not a match (gray, 0-2), Potential fit (yellow, 3), Good match (green, 4-5). The aggregate score is a weighted average of all criteria. Edit search for relaunch -- Update search criteria including scorecards and target companies to get a refreshed candidate list. Candidates already moved to subsequent stages (Contacted, Potential Interest) are retained along with notes and emails. How to Use 1. Create Your AI Employee Click "Create AI Employee" to begin configuring your Leadership Recruiter. Connect your email ID for Ema to use for outreach to shortlisted leaders. 2. Define Job Details and Scorecard Criteria Define job details covering job title, company name, industry, job function, and company revenue details. Specify scorecard criteria covering required skills, experience levels, and cultural fit factors. Define primary and secondary criteria for sourcing leaders. 3. Define Target Companies Generate target companies matching your criteria using simple natural language. Review filters auto-populated from your natural language query (industry keywords, company size, company type, location, business types). Remove/delete companies that do not fit your criteria. Star high-fit companies for easy filtering. 4. Launch Search and Get Ranked Results Refine your ideal candidate requirements in conversational language. Let the AI agent search across multiple data sources. Add notes for each leader to review later. Shortlist leaders who meet the criteria. Review automatically generated candidate scorecards. 5. Engage Top Leaders Review AI-generated personalized outreach messages. Customize engagement strategies based on social media and news insights. Track email activity across candidates and update the stage of each leader. Example Use Cases ScenarioApproachExpected ResultsC-Suite Executive SearchTarget leaders at companies in growth phases; personalize based on strategic initiatives and recent funding newsQualified executive leaders in C-level and SVP rolesVP-Level Technical RolesFocus on candidates with proven scaling experience; leverage social insights for cultural fit assessmentHigh volume of candidates in specified locationsDiversity Leadership HiringIdentify high-potential diverse candidates from top schools with growth trajectoriesSignificant improvement in diverse candidate pipeline Requirements Job details Email IDs for candidate outreach (Gmail or Outlook) ATS or TRM integration (coming soon)

================================================================================
# Prior Authorization AI Employee
URL: https://builder.ema.ai/templates/prior-authorization-assistant
================================================================================

Prior Authorization AI Employee Ema's Prior Authorization AI Employee assists healthcare providers in rapidly determining if a patient qualifies for a specific drug based on their medical history and the drug's authorization criteria. Built for clinical and operations teams, this AI Employee analyzes unstructured medical documents and aligns them with drug policy requirements to deliver fast, reliable, and explainable decisions. With source-backed answers and automatic document handling, it enables healthcare systems to reduce turnaround time from days to minutes, while maintaining a high standard of accuracy and compliance. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Policy-based eligibility assessment -- Matches patient records to predefined drug criteria to determine whether authorization can be granted, improving speed and consistency. 90% accuracy from day one -- Trained on clinical documentation patterns and optimized for policy matching, enabling high accuracy without manual fine-tuning. Rapid review turnaround -- Cuts down case assessment time from hours or days to just minutes, empowering clinicians to make faster decisions. Trusted, explainable responses -- Every AI-generated decision is backed with citations and reasoning, allowing providers to audit and trust the results. Automatic document processing -- Handles scanned and handwritten patient records via built-in OCR and applies PII scrubbing for data privacy. Seamless clinical deployment -- Upload, evaluate, and test authorizations directly in the Ema dashboard without needing technical configuration. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Add Drug Policies Input the specific criteria required for each drug's authorization -- such as diagnosis, lab values, or prior treatment history. Each criterion should be described in natural language so the AI Employee can match patient records against it. 3. Upload Patient Records Add patient documentation to the dashboard. Ema performs OCR and automatic de-identification for each file. 4. Enable and Test Turn on your AI Employee. Run evaluations from the dashboard and review source-backed decisions in real time. Use "Show Work" to trace how each criterion was evaluated against the patient record. Example Queries Is this patient eligible for Drug A based on history? Does this patient meet the criteria for prior authorization of Drug B? Highlight which document supports this decision. Why was the request for Drug C denied? Benefits Reduce time to decision -- Replace multi-day reviews with instant results directly within your workflow. Enhance clinical confidence -- Ground decisions in evidence with full reasoning and citations to policy. Scale review operations -- Evaluate high volumes of authorizations without increasing clinical workload. Protect patient data -- Built-in PII scrubbing and secure handling of sensitive health records. Accelerate AI adoption -- Out-of-the-box high accuracy makes it easy to deploy and start using immediately. Supported File Formats PDF (scanned or digital) DOCX Clinical record systems (exported files) Drug policy documents (structured or unstructured)

================================================================================
# Recruiter AI Employee
URL: https://builder.ema.ai/templates/recruiter
================================================================================

Recruiter AI Employee Ema's Recruiter is an AI-powered hiring platform that revolutionizes how you identify and hire talent. This intelligent system transforms weeks of manual screening into automated candidate discovery, assessment, and engagement processes that run 24/7, helping you find exceptional talent in weeks, not quarters. The platform combines natural language search capabilities with deep social media insights, real-time news monitoring, and personalized engagement tools to discover hidden talent and accelerate your hiring process while reducing bias through AI-powered evaluation. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Anatomy A Recruiter AI Employee has these tabs: TabWhat it's forSearchList of all searches. Create new searches here.ConfigurationConnect email and LinkedIn senders for outreach, and connect an ATS.PermissionsWho can use this AI Employee.DetailsName, description, and other AI Employee metadata. Each search holds its own job description, filters, scorecard, candidates, and outreach sequence. Core concepts ConceptWhat it isSearchA single hiring effort tied to one role.FiltersConstraints on the candidate pool (location, company, role, etc.) using Must / Preferred / Exclude logic.ScorecardWeighted criteria (Required / Preferred) that every candidate is scored against.Public profilesCandidates from Ema's external index.Internal talentCandidates from your connected ATS.Outreach stageWhere a candidate sits in the outreach lifecycle (e.g. Email sent, Interested). How a search flows Create the search (name + description). Enter a natural-language query or upload a JD. Review the filters Ema extracted. Review and edit the scorecard. Configure the outreach sequence and preferences, then click Begin Search. Review and shortlist candidates. Then in the Shortlisted candidates tab, select candidates and click Start Outreach to enroll them in the sequence. Beta -- When an ATS is connected, candidates from your pipeline appear in the Internal Talent tab alongside public profiles. See Connecting an ATS. Setting up the Recruiter AI Employee Before searches can send outreach, the AI Employee needs at least one connected sender. Senders live on the AI Employee, not the search -- once connected, all searches in this AI Employee can use them. Connect an email sender Open the Configuration tab on the Recruiter AI Employee. Click Connect email and choose Gmail or Outlook. Complete the OAuth flow with the mailbox you want to send from. Messages send from your real mailbox and appear in your Sent folder. Connect LinkedIn Open the Configuration tab. Click Connect LinkedIn. Authorize the connection in the LinkedIn flow. Connect an ATS (Beta) ATS connection also lives in the Configuration tab. See Connecting an ATS for what's currently supported. Picking which sender a search uses When you create a search, the outreach setup step lets you pick which connected email and LinkedIn account it should use. You can connect multiple senders at the AI Employee level and assign different ones to different searches. Common questions Q: My OAuth keeps failing. The most common cause is partial scope grants. Approve all permissions Ema requests during OAuth -- denying any will block sending. If you have multiple Google or Microsoft accounts, do the connection in an incognito window. Q: My LinkedIn account shows as expired. LinkedIn sessions can drop, especially if you log out of LinkedIn elsewhere. Reconnect from the Configuration tab -- sequences resume automatically once the connection is healthy. Creating a search A search is a wizard. You'll go through five steps, then click Begin Search to launch. Step 1 -- Name the search On the Search tab, click + New Search. Enter a Search name (e.g. "Software engineer") and a short Description. Click Save. Step 2 -- Describe who you're looking for You must describe the role in one of two ways: Natural language -- type a description of the ideal candidate in the "Find your next great hire" box (e.g. "Software Engineers in the United States with experience in React"). Search using a job description -- upload a JD as a file (PDF, DOC, DOCX, TXT). Maximum JD length is 20,000 characters; longer JDs are truncated before parsing. Ema parses your input and extracts filters. You can't skip this step -- every search starts from a natural-language query or a JD. Step 3 -- Review filters The filters panel groups constraints by category. Each filter has three options: Must -- hard filter; every candidate must match this. Stacking too many Must constraints sharply narrows results. Exclude -- hard filter; every candidate must not match this. Preferred -- soft signal; doesn't filter the pool, but boosts the candidate's score when matched. Use this for things that are nice-to-have but shouldn't disqualify candidates. Filter categories CategoryFiltersWhat it controlsJobsJob Title, Job Function, SeniorityThe role the candidate currently holds.LocationCountry, State / Region, City, ContinentWhere the candidate is based.CompanyCurrent Company, Past Company, Company Type, Employee CountThe companies the candidate has worked at.IndustryIndustry, Industry KeywordsThe industry of the candidate's current or past employers.ExperiencesYears of Experience, Years in Current CompanyHow long the candidate has been working in total or in their current role.Revenue and FundingRevenue Range, Funds RaisedThe size and stage of companies the candidate has worked at.EducationSchool, School Location, Degree, Field of Study, Graduation YearThe candidate's educational background.LanguagesLanguageLanguages the candidate speaks.Skills and KeywordsSkillSkills and keywords mentioned in the candidate's profile. Edit filters as needed, then continue. Step 4 -- Review the scorecard Ema generates a scorecard from your filters and JD/NL input. Each criterion is Required or Preferred: Required -- heavily weighted; candidates missing this score low. Preferred -- boosts the score when present, doesn't penalize when absent. Edit names, descriptions, and weights. Add or delete criteria. The scorecard populates even without a JD -- it's built from whatever input you provided in Step 2. Each candidate is scored 1-5 against every criterion: Not a match (gray, 0-2), Potential fit (yellow, 3), Good match (green, 4-5). The aggregate score shown in the candidate list is a weighted average of all criteria, with Required criteria contributing more than Preferred. Step 5 -- Configure outreach Set up the outreach sequence and preferences: Sequence steps (email and LinkedIn). Sender to use (chosen from the senders connected in Configuration). Daily Candidate Limit -- caps how many shortlisted candidates start outreach per day. Click Begin Search. Ema fetches and scores candidates in the background. Common questions Q: My search returned very few candidates. The most common cause is over-restrictive Must filters. Every Must filter narrows the pool, and stacking several (specific city + specific company + narrow seniority) can shrink results to almost nothing. Move non-essential constraints to Preferred -- they'll still influence ranking without filtering candidates out. Q: I uploaded a JD but the parsed filters look wrong. Try pasting the JD as text in the natural-language box instead of uploading a file. Scanned PDFs or files with heavy formatting can produce noisy parses. Also confirm the JD is under 20,000 characters -- longer JDs get truncated before parsing. Reviewing candidates Once a search is launched, candidates appear under the Search candidates tab while scoring runs in the background ("Generating..." appears in the Score column until ready). Tabs and sub-tabs Search candidates -- candidates surfaced by the search, with two sub-tabs: Public Profiles -- from Ema's external index. Internal Talent -- from your connected ATS (when ATS is connected). Shortlisted candidates -- candidates you've shortlisted (see Shortlisting and outreach). The candidate table shows Candidate, Company, Role, Score, plus per-criterion columns from your scorecard. Candidate drawer Click a candidate to open the drawer. Tabs: TabWhat you seeOverviewHeadline summary and aggregate score.ScorecardPer-criterion score with the citation the LLM used.NewsRecent news mentions of the candidate or their company.SocialPublic profile signals from sources like LinkedIn, GitHub, Twitter/X, personal websites, blogs, and academic pages.ActivityStage history and outreach activity for this candidate.NotesFree-text notes shared with the team.ContactVerified contact details where available. Shortlisting Click the bookmark icon on any candidate to move them to the Shortlisted candidates tab. Shortlisted candidates persist across search re-runs even if you edit filters or the scorecard. Managing outreach for a candidate The Activity tab in the candidate drawer shows the outreach timeline for that candidate -- every step that's been queued, sent, paused, cancelled, or failed, in order. From here you can: Send Now -- dispatch the next queued step immediately, ignoring the schedule and Daily Candidate Limit. Pause -- pause outreach for this candidate. Resume from the same control later. Cancel Outreach -- stop the sequence for this candidate permanently. This cannot be undone. If the candidate has replied, the reply appears in this section as well. Common questions Q: Scores are stuck on "Generating..." Scoring runs in the background and can take a few minutes for large candidate pools. The page polls automatically; leave the tab open or come back. If it's been over an hour, reach out to support. Q: A candidate's News or Social tab is empty. Enrichment is best-effort and depends on the candidate's public footprint. Sparse profiles produce empty tabs. The aggregate score does not depend on these tabs. Shortlisting and outreach Shortlisting a candidate does not start outreach on its own. To enroll candidates in the sequence configured for the search, open the Shortlisted candidates tab, select the candidates you want to contact, and click Start Outreach. Outreach stages The Shortlisted candidates tab shows an Outreach stage column. Stage values you'll see: StageMeaningEmail sentEmail step has been sent.LinkedIn connectionLinkedIn connection request sent.LinkedIn message sentLinkedIn DM sent (after connection accepted).Interested / Neutral / Not interestedManually-set status reflecting the candidate's reply. Replies pause the sequence for that candidate automatically. You can read the reply and set the candidate's status (Interested / Neutral / Not interested) from the Activity tab in the candidate drawer. Daily Candidate Limit The Daily Candidate Limit (set in the search's outreach preferences) caps how many shortlisted candidates start outreach in a 24-hour window. The default is 10. Once the cap is hit, the rest queue and start the next day. Common questions Q: I shortlisted candidates but no outreach has gone out. Check four things: Did you click Start Outreach? Shortlisting alone doesn't enroll candidates -- you have to select them in the Shortlisted candidates tab and start outreach explicitly. Sender connected and not expired? Configuration tab on the AI Employee. Daily Candidate Limit hit? New candidates queue until the next day. Sequence configured for the channel you expect? A LinkedIn-only sequence won't send email, and vice versa. Q: A candidate replied but the stage didn't move to Interested. Reply detection pauses the sequence, but the Interested / Neutral / Not interested status is set manually. Open the candidate's Activity tab to read the reply and set the status. Editing a search after launch Searches aren't locked once launched -- you can revise them at any time. Click Edit setup in the search header to step back through the wizard. What re-runs When you save changes: Edit JD or NL query -- filters re-extract, then candidates re-fetch and re-score. Edit filters (Must / Preferred / Exclude) -- candidates re-fetch and re-score. Edit scorecard criteria or weights -- existing candidates re-score; no re-fetch. Edit outreach sequence or preferences -- applies to candidates shortlisted from this point forward; in-flight outreach is unaffected. What's preserved Shortlisted candidates stay shortlisted across all re-runs. Notes on candidates persist. Outreach activity and stages for candidates already in outreach are preserved. Common questions Q: I changed criteria and rankings didn't update. Re-scoring runs in the background and the page polls. Wait a minute and refresh the candidate list. If the Score column still shows old values, click Edit setup and confirm the changes saved. Q: I broadened the filters and don't see the new candidates. The Public Profiles list updates as new candidates are fetched and scored. Sort by Score or scroll to load more -- newly fetched candidates may rank below the originals if their scorecard fit is weaker. Connecting an ATS (Beta) Beta -- ATS connection is in beta. Scope is currently limited to reading candidates from the ATS into Recruiter. Pushing candidates back to the ATS is not supported. When an ATS is connected, candidates from your pipeline appear in the Internal Talent sub-tab of Search candidates, scored against the same scorecard as public profiles and deduplicated against the external index. Connecting Open the Recruiter AI Employee and go to the Configuration tab. Find the ATS section and click Connect ATS. Choose your provider and complete the OAuth flow. What gets pulled in Candidates from selected jobs in the ATS. Basic profile fields (name, contact, resume text, current ATS stage). Historical candidates, where the provider supports it. What is not supported in beta Pushing shortlisted candidates back to the ATS. Two-way stage sync (changes in Recruiter don't reflect in the ATS, and vice versa). All ATS providers -- the supported list is shown during connection. Common questions Q: I connected an ATS but the Internal Talent tab is empty. Initial sync runs in the background and can take several minutes for large pipelines. If it's been over an hour, contact support -- the sync log will show whether the pull ran. Q: An ATS candidate has very little detail. Field availability depends on the provider. Some ATSes expose only minimal fields over their API.

================================================================================
# Reimbursement AI Employee
URL: https://builder.ema.ai/templates/reimbursement-assistant
================================================================================

Reimbursement AI Employee Ema's Reimbursement Assistant AI Employee automates the evaluation of invoices and bills against your organization's reimbursement policies. Built for finance, compliance, and operations teams, it parses uploaded documents -- including scanned and multilingual files -- to extract key fields and validate claims with high accuracy. This assistant delivers instant, explainable results and actionable feedback for both approved and rejected claims, helping reduce processing time, detect anomalies, and simplify policy updates. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Flexible document parsing -- Supports all invoice and bill formats -- including scanned images, PDFs, and multilingual content -- with built-in OCR and translation. Configurable field extraction -- Extracts item lists, quantities, prices, vendors, tax amounts, and more, based on fields you define in the extraction configuration. Policy validation in plain English -- Add and update reimbursement rules using natural language -- no need for technical configuration. Explainable, actionable results -- Each approval or rejection includes clear reasoning, source citations, and recommended next steps to resolve discrepancies. Real-time SLA improvements -- Automate end-to-end evaluation to reduce turnaround time and meet or exceed reimbursement SLAs. Fraud and error detection -- Identify duplicate entries, inflated charges, and missing details automatically through rule-based validation. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Set Up Extraction Fields In the Extraction agent, define the fields Ema should pull from uploaded documents (for example, item name, price, vendor). 3. Set Up Reimbursement Rules In the Validation agent, provide the policies and rules your organization uses to evaluate reimbursements in natural language. 4. Enable and Test Turn on your AI Employee. Upload test invoices to the dashboard and review output, including validation results and source-backed justifications. Use "Show Work" to trace each result. Example Queries Check this invoice for compliance with our reimbursement policy. Why was this claim rejected? Extract all line items and flag any policy violations. Suggest next steps to fix this claim. Benefits Improve reimbursement SLAs -- Achieve faster turnaround times with automated evaluations and recommendations. High accuracy from day one -- Reliable extractions and validations with clear justifications for every decision. Business-user friendly -- Easily update policies without needing engineering or technical input. Reduce fraud and manual errors -- Automatically catch suspicious claims and inconsistencies early. Scale operations efficiently -- Handle large volumes of claims without increasing review overhead. Supported File Formats PDF DOCX Scanned images (JPEG, PNG) Multilingual invoice files Excel or CSV (if exported from billing systems)

================================================================================
# Sales Concierge AI Employee
URL: https://builder.ema.ai/templates/sales-concierge
================================================================================

Sales Concierge AI Employee Help website visitors explore products, answer their questions, and drive conversions by guiding them to a purchase. Overview Ema's Sales Concierge AI Employee engages visitors by answering questions, recommending the right products, and booking meetings with your sales team. You can host this AI Employee on your website or app to search over your knowledge base, handle small talk, and perform escalation in a seamless, conversational manner. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Seamless, multi-turn conversations -- Understands customer intent and context to provide personalized, dynamic responses. Smart knowledge base search -- Simply provide your helpdesk URLs or knowledge base articles and the AI Employee can search over them. Feedback and escalations -- Asks for user feedback and allows you to configure escalation paths for negative feedback. Web widget (SDK) to host on your website -- Customize to your brand colors and guidelines and go live in a few easy steps. Trusted AI that keeps you in control -- Grounded in your data and policies, ensuring transparency, compliance, and adherence to your SOPs. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Configure Your AI Employee Add knowledge base: Provide relevant documentation like helpdesk articles, product information, and policies. You can either upload PDF files or provide the web URLs to your website and Ema can automatically crawl them. Customize instructions: Go to the workflow builder and review the current configuration. Add the relevant categories and category descriptions in the intent classifier. Review the instructions in the various respond agents and ensure they reflect your company name and context. Replace placeholders with your company name. Remember to publish the workflow outputs if you are adding a new respond agent. Customize your SDK: Provide a welcome message, upload a logo, and decide a name for your chatbot. If you do not want Ema to show sources, enable the "hide sources" option. Decide if you want to ask for end-user feedback and how often. 3. Enable and Test Turn on your AI Employee. Try asking a supported query in the SDK and make sure you receive the expected response. To add to your website, copy the JavaScript snippet and add it to the <body> section of your website. Whitelist your URL for Ema's chatbot following the Embeddable Chat SDK guide. Example Queries What products do you offer? Good evening What are your pricing details? Do you offer something for XYZ use case?

================================================================================
# Sales Engineer AI Employee
URL: https://builder.ema.ai/templates/sales-engineer
================================================================================

Sales Engineer AI Employee Ema's Sales Engineer AI Employee empowers sales teams to answer complex technical questions with speed and accuracy, directly from technical documentation. Whether it is handling inquiries about architecture, compliance, product specs, or integrations, this AI assistant streamlines the sales cycle by delivering high-quality, source-backed answers instantly -- even from documents with dense content, images, and tables. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Technical query resolution -- Understands and responds to deeply technical questions using your uploaded documents, including architecture diagrams, spec sheets, and policy guides. Improves sales velocity -- Removes technical blockers in sales cycles by giving reps immediate access to the answers they need. Reliable and trustworthy -- Provides responses with source citations so sales reps and prospects can verify every claim. Scalable knowledge integration -- Expand the assistant's knowledge base beyond documents by indexing your website, developer portal, or product support center via URLs or web crawls. Explainable with "Show Work" -- Review how each response was derived to debug, audit, and improve AI behavior. Secure by design -- Enterprise-grade security, de-identification, and access control features ensure privacy and compliance. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Upload Documentation Add technical resources such as manuals, specs, guides, and diagrams. PDF and DOCX formats are supported. 3. Enable and Test Turn on your AI Employee and interact with it in chat. Use the "Show Work" feature to inspect source traces and response logic. Example Queries What is your high availability architecture? How does your API authentication work? Do you support multi-region deployments? Where is data encryption implemented in your platform? What are the system requirements for installation? Supported File Formats PDF DOCX Public web pages or internal portals (via URL) Technical diagrams embedded in documents

================================================================================
# Sales Intelligence AI Employee
URL: https://builder.ema.ai/templates/sales-intelligence-assistant
================================================================================

Sales Intelligence AI Employee Ema's Sales Intelligence Assistant AI Employee helps sales and marketing teams create comprehensive, up-to-date intelligence reports on public companies. By combining web search capabilities with structured financial data aggregation, it delivers well-designed, source-backed documents that can be customized to match your brand's style guide. Designed to empower customer-facing teams with fresh insights, this assistant delivers reports in a fixed format with financial charts, contextual commentary, and clear citations -- accelerating prep for sales calls, account planning, and executive briefings. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Real-time market research -- Gathers the latest publicly available data on companies from financial sources and live web search, ensuring your team has current insights. Structured reports with charts -- Automatically generates clean, consistent documents with embedded financial charts, business summaries, and qualitative observations. Customizable document format -- Follows a predefined structure that can be adjusted to reflect your organization's preferred briefing or memo style. Style guide adherence -- Extracts fonts, colors, and formatting rules from your uploaded style guide to ensure every report looks on-brand. Explainable and trustworthy -- All data points and commentary are traceable via source links, giving sales teams confidence in what they are presenting. Multi-region coverage -- Supports public companies across geographies, expanding your sales team's reach with localized, relevant insights. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Provide Document Template Add a customizable response format in the query creator agent to define how the report should be structured. 3. Provide Style Guide Upload your brand's style guide so Ema can automatically apply formatting, fonts, and layout rules to each report. 4. Enable and Test Turn on your AI Employee. Use the chat to request company reports and check the output. Use "Show Work" to trace sources and formatting logic. Example Queries Create a report on Salesforce Inc. Give me the latest financials and stock trends for Alibaba. Generate a company brief on Siemens with charts. What are the recent market moves of Spotify? Benefits Empower sales with data -- Equip sales teams with real-time, accurate, and visually engaging intelligence on prospects and customers. Create high-quality outputs -- Deliver polished, professional reports that match your organization's branding. Accelerate sales prep -- Save hours of research by automating company profiling and briefing creation. Build trust with clients -- Cite every insight with sources so sellers can present confidently and credibly. Supported File Formats DOCX (style guide and template) PDF Public web content (via search or URL crawl) Financial databases and news feeds (automatically queried)

================================================================================
# Talent Matching AI Employee
URL: https://builder.ema.ai/templates/talent-matching-assistant
================================================================================

Talent Matching AI Employee Overview The Talent Matching Assistant is part of Ema's AI recruiter suite, offering a pre-built, end-to-end workflow that: Extracts key qualifications and skills from candidate resumes and job descriptions. Evaluates candidates against custom job requirements and screening criteria. Provides explainable scoring to generate shortlists with interview tips. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Intelligent resume parsing -- Extract and normalize candidate information including skills, education, experience, certifications, and achievements from various resume formats. Custom scoring criteria -- Define evaluation parameters based on specific job requirements, must-have skills, and preferred qualifications. Bias mitigation tools -- Configure settings to reduce unconscious bias by focusing on qualifications rather than demographic factors. Candidates shortlisting -- Automatically generate shortlists with detailed scoring breakdowns and aggregated scores. Explainable results -- Access a full assessment log with justifications for scoring decisions and qualification matches. How to Use Configure Your Parameters Resume extraction fields -- Specify information to extract, such as: Total Years of Experience, Relevant Experience, Education Level, Previous Job Titles, Past Companies, Certifications, Languages Spoken, Location/Relocation Status, Salary Expectations, Technical Skills, Domain-Specific Skills, Soft Skills, Awards, and Publications. Job description extraction fields -- Specify information to extract, such as: Total Years of Experience, Relevant Experience, Education, Certifications, Language Requirements, Job Location, Technical Skills, Domain-Specific Skills, and Soft Skills. Scoring criteria -- Write criteria in 1-2 sentences each. Examples: Domain expertise -- Score higher if candidate's domain expertise matches directly with job description expectation. Years of relevant experience -- Score higher if candidate's experience directly matches job requirements in years. Skill alignment -- Prioritize candidates proficient in core technical, domain-specific, and soft skills mentioned in the JD. Education and certifications -- Prefer candidates who meet or exceed degree and certification expectations. Analysis instructions -- Provide detailed prompts, such as: "Summarize each candidate's key qualifications and experience relative to job requirements in three concise bullet points." "Identify skill gaps between job requirements and candidate profiles, suggesting potential training needs." "Flag exceptional candidates who exceed minimum requirements in critical areas." Enable and Test Turn on your AI Employee. Upload job description and candidate resumes (PDF, DOCX, RTF, TXT). Alternatively, sync both job applications and candidate resumes from your ATS. Review candidates, match scores, and detailed descriptions in the dashboard.

================================================================================
# Voice of Customer AI Employee
URL: https://builder.ema.ai/templates/voice-of-customer-analyst
================================================================================

Voice of Customer AI Employee Ema's Voice of Customer Analyst AI Employee helps CX and insights teams extract meaningful feedback from customer conversations at scale. By analyzing historical transcripts, survey responses, and NPS feedback, this assistant uncovers sentiment trends, highlights key pain points, and recommends actionable next steps -- all without manual effort. This assistant enables organizations to listen to customers more effectively, identify patterns across channels, and align internal teams around data-driven improvements to the customer experience. This workflow is instantiated by copy, so any updates to the template will not retroactively change existing AI Employees built from it. Key Features Automated insight extraction -- Processes large volumes of transcripts and feedback to surface important themes and issues without manual tagging or review. Deep sentiment analysis -- Evaluates how customers feel across products, experiences, and touchpoints -- identifying frustration, satisfaction, and confusion at a granular level. Prioritized issue identification -- Detects high-impact issues, clusters them by frequency or urgency, and recommends practical, targeted fixes. Action-oriented reporting -- Generates concise, structured reports summarizing findings with suggested improvements that can be shared with stakeholders and tracked over time. Multichannel input support -- Works across call logs, surveys, support tickets, NPS forms, and other sources of qualitative feedback. Transparency with "Show Work" -- Every insight and recommendation is backed by evidence from the transcripts, making the results easy to verify and trust. How to Use 1. Create Your AI Employee Click Create AI Employee at the top of the template page. 2. Upload Transcripts Add historical call transcripts, survey responses, or NPS feedback to the chat interface for analysis. Supported formats include PDF, DOCX, TXT, and CSV exports from your survey or ticketing platform. 3. Enable and Test Turn on your AI Employee. Ask it to summarize feedback trends, surface complaints, or propose CX improvements. Use "Show Work" to view the source behind each insight. Example Queries Summarize the top 3 issues raised in these calls. What is the sentiment trend across these NPS responses? What are customers complaining about the most? Recommend actions based on these survey results. Benefits Accelerate feedback analysis -- Replace manual reviews with automated insight generation across thousands of records. Improve customer satisfaction -- Act quickly on prioritized issues with clear fixes suggested by the assistant. Understand sentiment at scale -- Gain visibility into how customers feel -- across regions, products, and support channels. Enable data-driven CX strategy -- Align internal teams with structured, shareable reports that drive continuous improvement. Scale Voice of Customer programs -- Analyze more interactions without increasing team size or overhead. Supported File Formats PDF or DOCX (for transcripts and reports) TXT or CSV (for survey or NPS data) Call transcript exports from support platforms or voice analytics tools JSON or API feeds from feedback systems

================================================================================
# Testing & Operations
URL: https://builder.ema.ai/testing-operations
================================================================================

Testing & Operations This section covers the full lifecycle of an AI Employee from pre-launch testing through post-launch monitoring, auditing, and continuous improvement. In This Section Testing & Evaluation Testing AI Employees -- How to build test datasets, run progressive tests, and validate AI Employees before launch. Evaluating AI Employees -- Running evaluation suites with scoring criteria and interpreting results. Launch Launch Checklist -- Pre-launch verification steps organized by phase. Launching & Monitoring -- Post-launch rollout, user onboarding, and adoption tracking. Debugging Debug Logs -- Reading and using debug logs to inspect workflow execution. Metrics & Auditing Chat Metrics -- Tracking usage, feedback, and tool call metrics for chat AI Employees. Auditing Chat AI Employees -- Reviewing conversations, providing feedback, and tracking resolution. Metrics & Insights -- Overview of per-AI-Employee metrics by trigger type. Operations Seamless Upgrade -- Safely testing and deploying changes to live AI Employees. Configuration Chatbot Logo Configuration -- Upload and manage a brand logo for embedded chatbots. Customize In-Progress Messages -- Configure live progress updates shown to users while the AI Employee processes a request.

================================================================================
# Auditing Chat AI Employees
URL: https://builder.ema.ai/testing-operations/auditing
================================================================================

Auditing Chat AI Employees The Audit tab in chat AI Employees provides comprehensive capabilities to track, evaluate, and continuously improve your AI Employee's performance with access to real user conversations. This enables reviewers and builders to monitor conversations, add notes, and measure performance objectively to update the GWE workflow and AI Employee configuration. User Roles The Audit tab is available to users with the AI Employee Admin, AI Employee Manager, or AI Employee Metrics Viewer role on the AI Employee. All three roles can: View all conversations for the AI Employee, filtered by date range. Filter conversations by: user dissatisfaction, user feedback added, or reviewer comments added. Search conversations by email, conversation ID, or message snippet. Open a conversation to view the full message history, user context, and conversation sources. Set or update a conversation's resolution status (New, Opened, Needs Improvement, Needs Clarification, Resolved). Benefits Complete Conversation Visibility -- Access and review all user interactions with detailed conversation history, user context, and source attribution. Structured Feedback -- Capture both end-user feedback and expert notes through filters. Performance Optimization -- Identify patterns in successful and dissatisfying interactions to guide improvements. Key Features Conversation Table The Audit dashboard provides a conversation table with: Conversation ID (with quick copy) User email Date Resolution status User feedback rating Conversation Status Filtering View and filter conversations by key criteria: User dissatisfaction -- Includes workflow failures, external action failures, and user negative feedback. User feedback added -- All conversations with any user feedback. Reviewer comment added -- All conversations with any reviewer comments. Additional Filtering and Search Filter conversations by date range. Search by user email, conversation ID, or content snippets. Detailed Conversation Review Access complete conversation history with user context, sources used, and all feedback along with timestamps. Adding Comments Reviewers can provide optional comments for each AI Employee response. Status Tracking Mark conversations as: New Opened Needs Clarification Needs Improvement Resolved Feedback Categories Conversations are automatically categorized based on the percentage of queries: CategoryCriteriaGood>80% positive or no-feedback queriesNeutral50--80% positive or no-feedback queriesBad<50% positive or no-feedback queries Advanced Debugging Access Show Work functionality to view intermediate agent processing and decision-making. For details, see Debug Logs. How to Use Getting Started Automatically enabled for all deployed chat-based AI Employees. No additional configuration required -- conversation logging begins immediately upon the first query. Access through the dedicated Audit tab in your chat-based AI Employee. Pre-Launch Testing Reviewers can simulate various user scenarios and provide structured feedback to builders during the UAT phase. Post-Launch Operations Daily Monitoring -- Reviewers check recent conversations for issues requiring attention. Regular Evaluations -- Conduct unbiased performance assessments using randomized conversation samples. Continuous Improvement -- Builders monitor comments, implement fixes, and track resolution progress.

================================================================================
# Chat Metrics
URL: https://builder.ema.ai/testing-operations/chat-metrics
================================================================================

Chat Metrics Metrics for chat AI Employees transform raw conversation data into actionable insights. They provide real-time monitoring, user behavior analysis, and performance optimization tools to help you continuously improve the effectiveness of your AI Employees. Benefits Real-Time Performance Monitoring -- Measure usage and adoption of end-to-end workflows, including external tool calls. Monitor Feedback -- Track positive and negative feedback rates to assess user satisfaction. Pattern Discovery -- Identify the most relevant user actions and workflows to guide future integrations. Optimization Insights -- Track workflow reliability and success rates. Spot high error or drop-off points to prioritize UX and reliability improvements. Supported Channels Chat metrics cover conversations across all chat channels an AI Employee is deployed to: Web -- Embedded chatbot and in-app chat. Microsoft Teams Google Chat Key Features The Metrics Dashboard provides two categories of insights: 1. Primary Metrics MetricDescriptionTotal Active UsersUsers who sent at least one message during the selected time period.Total User MessagesNumber of messages sent by users.Total SessionsSession counts based on platform rules. Microsoft Teams / Google Chat: new session after 24 hours of inactivity. Web: new session after 30 minutes of inactivity.Positive Feedback RateShare of interactions that were not rated negative. Computed as 1 − (negative / (positive + negative + unrated)), so both explicit thumbs-up and interactions left unrated count as non-negative.Total Tool CallsTotal number of tool calls made. 2. Trend Analysis Over Time Active Users Over Time -- Track unique user engagement trends. User Messages Over Time -- Monitor message volume trends. Sessions Over Time -- Understand session creation patterns based on inactivity rules. Positive Feedback Rate Over Time -- Measure changes in satisfaction levels. Tool Calls by Status Over Time -- Analyze completed, failed, and abandoned tool calls. Tool Calls by Tool -- Breakdown of tool usage by integration. Filtering and Timeframes All metrics are displayed in Coordinated Universal Time (UTC). The date range picker supports custom start and end dates as well as the following presets: Today Last 7 full days Last week Last 14 full days Last 30 full days Last month Last 365 full days Note: "Last X full days" presets include completed days only and exclude today, so intra-day data does not skew comparisons. How to Use The Metrics tab is automatically enabled for all chat-based AI Employees. No additional configuration is required to start tracking metrics.

================================================================================
# Chatbot Logo Configuration
URL: https://builder.ema.ai/testing-operations/chatbot-logo-configuration
================================================================================

Chatbot Logo Configuration The Chatbot Logo Configuration feature lets you upload a custom brand logo that appears in the header of your embedded chatbot widget. A recognizable logo builds user trust and reinforces brand identity within the chat experience. Where the Logo Appears The uploaded logo is displayed in the header area of the Embeddable Chat SDK widget. It replaces the default Ema icon with your company's branding. The same logo is used across all deployment domains whitelisted for the AI Employee. How to Configure Step 1: Navigate to Chatbot Configuration Open the AI Employee you want to brand. Go to the Configurations tab. Locate the Chatbot Configuration widget. Step 2: Upload Your Logo In the Brand Logo section, click the upload area or drag and drop your image file. The platform validates the image before accepting it. Step 3: Save and Preview Click Save to persist the logo. Open the chatbot preview or navigate to a whitelisted domain to verify the logo renders correctly in the chat header. Image Requirements RequirementDetailSupported formatsPNG, JPG, JPEGMaximum file size1 MBRecommended dimensionsSquare aspect ratio (for example, 256 x 256 pixels)TransparencySupported for PNG format Images that exceed the maximum file size or use an unsupported format are rejected with an inline error message. Non-square images are accepted but may be cropped or padded to fit the header area. Best Practices Use a square logo. The chat header renders the logo in a compact square area. Rectangular logos may lose important detail when scaled. Prefer PNG with transparency. Transparent backgrounds blend seamlessly with the chatbot header regardless of the primary color theme. Keep the design simple. The logo is displayed at a small size; intricate details may not be visible. Test on multiple devices. Verify the logo looks correct on both desktop and mobile viewports. Related Embeddable Chat SDK -- Full chatbot embedding guide including branding, domain whitelisting, and snippet generation.

================================================================================
# Debug Logs
URL: https://builder.ema.ai/testing-operations/debug-logs
================================================================================

Debug Logs The Debug Logs feature provides comprehensive visibility into AI Employee workflow execution. It addresses the critical need for debuggability and explainability by offering deep, structured insights into every workflow run -- including agent configurations, input/output values with their sources, detailed work logs with LLM prompts and responses, and clear error/warning indicators. Debug Logs are accessible directly from the workflow canvas. This feature allows builders to independently debug failures, test improvements iteratively, and inspect any user's workflow execution without contaminating production metrics or requiring reproduction steps. Accessing Debug Logs Chat AI Employees Save the persona and start using the AI Employee. In the conversations window, each message has a Show Work button. Click Show Work to open a modal with an action execution summary for each action in the workflow (in the order it was run). Under every action, you can see the summary of each step during that action's lifecycle. Dashboard AI Employees In the Dashboard view, a separate column displays the Show Work button for every row, regardless of workflow run status. Click the button to view the detailed graph view, same as in chat. Deep Logs Viewer Admins see an additional button to view detailed logs (deep logs). This opens the canvas showing a graph view of the workflow in read-only mode. Non-admins do not see this button. Node Status Colors The outline color of each node indicates the run state for that action: ColorStatusGreenSuccessfulYellowWarningGreyNot runRedErroredBluePaused Node Status Icons The icon on the right side of each node (next to the expand button) follows this mapping: IconMeaningRed warning circleAction has errorsGreen check circleNo errors or warningsYellow warning circleAction has warnings Inspecting Action Details Clicking on any node in the canvas opens a drawer on the right side with four tabs: Configuration, Inputs, Work Log, and Outputs. Inputs Displays all inputs the agent received at runtime. For each input, you can see: Input name -- The identifier. Input type -- The data type. Input value -- The actual value. JSON data is automatically formatted with expand/collapse and copy options. Input source -- Where the input came from. Each input dropdown includes an expand option to view the full JSON payload in a modal. Configurations The configuration section mirrors the right-hand-side drawer in builder mode. It shows the exact configurations the agent was wired up with, in read-only mode. All widgets used in the configuration are displayed. Configurations are snapshotted at runtime when the workflow engine receives the workflow definition and the persona config. Note: Uploaded files are not snapshotted at runtime. If a file has been modified since the run, the current version is shown. Work Logs Work logs contain messages generated by the action implementation at runtime. Key details: Step-wise logging: All messages are logged under a specific step, even if a step has only a single message. Regular messages: Logged directly by the action implementation. JSON data is automatically formatted. LLM calls: Populated at the LLM caller level each time the action makes an LLM call. Each LLM call has three parts: System prompt -- Viewable by Ema internal users only. User prompt -- Viewable by all admins. For some LLM calls, these are the instructions provided in the agent configuration tab. Response -- Viewable by all admins. Step Status Indicators Each step tile in the work logs section shows a status icon: Green check circle -- Step succeeded. Red cross circle -- Step failed. Yellow warning circle -- Step had a warning. Errors and warnings are also displayed at the top as clickable tiles that scroll to the relevant step when clicked. Outputs Displays all data produced by the agent during execution. For each output: Output name -- The identifier. Output type -- The data type (e.g., Text, Text with Sources, List). Output value -- The actual data produced, formatted based on type. Published status -- Whether this output was published as the final chat response. Published outputs display a green "Published as primary category" badge. Complex Output Values For outputs containing complex data structures or JSON, the built-in JSON viewer automatically formats the data. Each output dropdown includes a "View Full Data" option that opens an expanded modal. Array Outputs Named array items -- If the array contains objects with name properties, each item is expanded into its own output entry. Regular arrays -- Displayed as "Array with X items" in the summary, with individual items accessible via the expandable view. Complex object arrays -- Each item can be expanded to view the full JSON structure. Empty State If an agent did not produce any outputs (e.g., it failed early or was configured without outputs), the Outputs tab displays: "No output data available for this execution." Per-Agent Latency Metrics The debug view surfaces per-agent latency data to help builders identify performance bottlenecks. Each action node in the Show Work and Deep Logs views displays the total LLM latency accumulated during that action's execution. Where Latency Appears Latency is displayed in two locations within the debug interface: Action summary cards -- Each action card in the Show Work modal includes a latency badge showing the total time spent on LLM calls, formatted in seconds (for example, "1.24 seconds"). Work Logs detail view -- Within the Work Logs tab for a specific action, each individual LLM call entry includes its own latency measurement alongside cost and success/failure indicators. How Latency Is Calculated The latency value represents the total wall-clock time spent waiting for LLM responses within a single action. The per-call latency is read directly from LLM response metrics (already in seconds). The llm_latency_ms field is displayed separately in milliseconds in the Work Log tab Using Latency Data Identify slow actions -- Compare latency across actions in a workflow run to find which agents contribute the most to overall response time. Evaluate model choices -- If EmaFusion™ is enabled, compare latency between runs to assess the performance impact of different model selections. Optimize workflows -- Actions with consistently high latency may benefit from prompt simplification, reduced context sizes, or model downgrades where quality permits. Set baselines -- Track latency across workflow versions to detect regressions after configuration changes.

================================================================================
# Evaluating AI Employees
URL: https://builder.ema.ai/testing-operations/evaluating
================================================================================

Evaluating AI Employees Evaluations allow you to measure how an AI Employee performs against a large dataset using defined scoring criteria. This helps validate response quality, consistency, and alignment with expected behavior before or after launch. Supported AI Employees Evaluations are currently supported only on chat-triggered AI Employees. Key Concepts ConceptDescriptionEvaluationA single execution that runs against a dataset and scores each response using defined criteria.DatasetA CSV file containing test queries. Each row represents a single workflow run.User Query ColumnThe dataset column whose values are used to trigger AI Employee workflow runs.Evaluation CriteriaDefines how responses are assessed. Criteria include evaluation context and one or more scoring guidelines.Scoring GuidelineA rule that defines how a response is scored on a numeric scale. Each guideline produces a separate score.LLM EvaluatorThe large language model used to evaluate and score AI Employee responses.Evaluation ResultsRow-level outputs containing scores. Results can be viewed in the UI or downloaded as CSV. Permissions Only users with the AI Employee Manager or AI Employee Admin role can view and run evaluations in the Evaluations tab. Creating an Evaluation Evaluations are created from the Evaluations tab of a chat-triggered AI Employee by clicking New evaluation. Evaluation Setup Dataset Selection You can either: Select an existing dataset (previously uploaded), or Upload a new dataset. Input Mapping Each evaluation requires mapping one dataset column as the user query. Values from this column are used to trigger the AI Employee for evaluation. Evaluation Criteria You can either: Use an existing default evaluation criteria or previously saved criteria, or Create a new evaluation criteria. Evaluation Context The evaluation context defines the instructions and variables used to guide scoring. Pills: Pills can be selected from the left panel and inserted into the evaluation context. Each pill represents a variable and is replaced with its corresponding value before being sent to the LLM evaluator. Scoring Guidelines At least one scoring guideline is required per evaluation criteria. Each scoring guideline includes: Name (required) Description (optional) Scale -- An integer range for the scoring scale (e.g., 1 to 3, 1 to 5, or custom ranges). Each numeric value within the selected scale must have a clearly defined criterion to ensure consistent and reliable scoring. LLM Evaluator Selection Each evaluation requires selecting an LLM evaluator. The selected model is used as a judge to score all dataset rows. The dropdown displays all available models, including any custom models added on the AI Employee's configuration page. Running Evaluations Configure the dataset and evaluation criteria. Click Run Evaluation to start. Monitoring Progress Each dataset row displays an execution status. Rows marked Success indicate completed scoring. Results and Metrics Evaluation Results After completion: Full results are available in the evaluation view. Results can be downloaded as a CSV file. Metrics For each scoring guideline, the following metrics are generated: Highest score Lowest score Average score Score distribution Notes Notes can be added to evaluations for documentation and future reference. Past Evaluations The Evaluations tab lists all historical evaluations for the AI Employee, making it easy to compare performance over time.

================================================================================
# Intelligent Human Collaboration (HITL)
URL: https://builder.ema.ai/testing-operations/human-collaboration
================================================================================

Intelligent Human Collaboration (HITL) Ema agents support Human-In-The-Loop (HITL) capabilities that allow you to involve a human decision-maker at key points in a workflow. HITL is useful in three scenarios: Ema is unsure of the path forward and needs more information from the user (e.g., select option A or B). Ema needs additional information before taking an action (e.g., ticket priority when creating a ticket). An admin wants Ema to always stop for approval before proceeding. HITL in the Intelligent Actions Agent You can enable HITL for each external tool (e.g., Create Ticket) within the Intelligent Actions agent. This allows you to review parameters before the agent executes the tool. Configuration Options Message, confirmation button, cancel button -- Customize the text displayed to the user. Hidden parameters -- Select parameters that should be hidden from the end user (e.g., User ID). Mandatory vs. optional HITL: Mandatory -- Ema always pauses for approval. Optional -- Ema only invokes HITL when it needs more information to proceed. HITL in Intelligent Actions is available in both Conversational and Document Intelligence type AI Employees. HITL in the Extract Entities Agent HITL can be enabled with the Extract Entities agent to ensure humans can approve extractions. Set it up using the Human Feedback setting in the Extract Entities agent. When HITL is enabled and invoked during a run, the user is asked to approve the extraction before the workflow continues. HITL in the Categorize Conversations and Route Agent HITL can be enabled in the Categorize Conversations and Route agent. It is invoked when Ema is unsure which option to select and needs help from a human. The Human Collaboration Agent A standalone HITL agent is available for chat-based workflows. Admins can configure: Success criteria -- Conditions under which the workflow should proceed. Failure criteria -- Conditions under which the workflow should stop or escalate. Ema uses these criteria to determine when to involve a human in the workflow.

================================================================================
# Launch Checklist
URL: https://builder.ema.ai/testing-operations/launch-checklist
================================================================================

Launch Checklist Use this checklist to verify readiness before launching an AI Employee to production. These phases apply to both first-time and improvement launches. Phase 1: Testing Preparation Gather all known use cases into one place (template or GWE-based). For Chat AI Employees: Create a diverse query testbed (languages, synonyms, company lexicon). Include follow-up queries (relevant and irrelevant). Cover different user types (for personalization). Flag deprioritized or out-of-scope cases. Write golden responses with required facts, tone, and disclaimers. For Dashboard AI Employees: Build varied test input combinations. Include representative document types (scanned, blurry, image-heavy). Exclude irrelevant document formats. Identify and flag HITL-required test cases. Prepare a sandbox environment if production data is unavailable. Phase 2: Progressive Testing Build and test the workflow incrementally. Optimize for full use-case coverage before polish. Publish intermediate outputs or responses for debugging. Use Show Work in GWE to debug responses. Phase 3: User Acceptance Testing (UAT) Run all test cases end-to-end, impersonating different users. Simulate production-scale usage. Remove all intermediate outputs and debug artifacts. Nominate actual users as testers and collect feedback. Phase 4: Testing Existing AI Employees Create a copy of the AI Employee for safe testing (see Seamless Upgrade). Test new branches or flows in isolation before merging. Save copies of all workflows for regression tracking. Annotate changes with corresponding test results. Conduct blind evaluations against humans for benchmarking. Use HITL or disclaimers for lower-confidence cases. Phase 5: Launch Planning Plan a limited first launch: Small user group. High-impact test cases. Define rollout phases with audience, timelines, and exit criteria. Phase 6: Workflow Enablement Switch app connections from sandbox to production. Confirm the AI Employee name and description are user-appropriate. Resolve all pending issues before enabling the workflow. Phase 7: User Access Setup Add AI Employee-level admins. Add regular users as guests (if needed). For embedded chatbots, skip guest addition. For project-based tools, nominate project-level admins. Phase 8: Launch Communication Send a launch announcement with usage examples. Run an onboarding webinar with a deck and live demo. Share training material and webinar recording. Schedule post-launch office hours (2--4 weeks). Share a feedback and bug tracking form or sheet.

================================================================================
# Launching and Monitoring Your AI Employee
URL: https://builder.ema.ai/testing-operations/launching-monitoring
================================================================================

Launching and Monitoring Your AI Employee These steps apply to both first-time and improvement launches. Determine Launch Phases Start with a limited first launch. Target a smaller group of users to effectively manage feedback and scale. Focus on a smaller set of high-impact test cases so customers can start realizing gains quickly. Create a clear set of phases with the audience, timelines, and exit criteria for each. Enable Your Workflow Remove testing artifacts. Switch app connections to actual production instances if you were using sandbox environments. Confirm the AI Employee's name and description are appropriate for your current users. Enable your workflow. If you have any pending issues, Ema will prevent you from enabling the workflow until they are resolved. Add Relevant Users Invite additional admins as AI Employee-level admins. Add regular users as guests. For chat AI Employees being embedded elsewhere, skip this step. Simply embed the chat as required. For project-based AI Employees (such as Document Writer), nominate some users as "Project-level admins." These users can create new projects and invite new users without having admin-level editing privileges. Create and Share Launch Material Launch Announcements Publish launch announcements to each tranche of users via their preferred communication channel. Onboarding Webinar Prepare a deck and an end-to-end demo. Set up a launch webinar and walk users through the product. We recommend a hands-on format where users follow along and try the product during the session. Share the training deck and webinar recordings with users for future reference. Office Hours Schedule office hours in the 2-4 weeks following launch so users can drop in and seek help. Feedback and Bug Tracking Share a feedback form or spreadsheet that users can use to report bugs and feature requests. Ensure the form: Clearly differentiates between bugs and feature requests. Captures screenshots and additional details. Indicates urgency or priority. Set up a process to review and address submissions periodically. Monitoring Adoption and Impact All AI Employees include out-of-the-box metrics to track usage. Chat AI Employees Track: Number of chat sessions Number of queries Number of active users Feedback trends (positive and negative) For detailed chat metrics, see Chat Metrics. Dashboard AI Employees Track: Total triggers of the dashboard Success rates Additional dashboard metrics are expected to be available soon. Upcoming Metrics for GWE Workflows For all GWE-based workflows, the following metrics are being added: Total agentic triggers -- Count across agents. External tool calling metrics -- Track which tools and apps are triggered most often. Workflow success and failure counts.

================================================================================
# Metrics & Insights
URL: https://builder.ema.ai/testing-operations/metrics-insights
================================================================================

Metrics & Insights Metrics Metrics are available on a per-AI-Employee basis, determined by the trigger type of the AI Employee. This means that chatbot AI Employees display different metrics out of the box compared to document-based or ticketing AI Employees. Chat AI Employees Chatbot AI Employees show usage metrics including sessions, messages, users, and feedback trends. For a detailed breakdown, see Chat Metrics. Ticketing AI Employees Ticketing AI Employees display metrics relevant to ticket processing volume and resolution rates. Dashboard AI Employees Dashboard AI Employees show total triggers and success rates. See Launching & Monitoring for details. Customizable Metrics Customizable metrics are coming soon, along with more detailed metrics and graphs per use case.

================================================================================
# Seamless Upgrade for AI Employees
URL: https://builder.ema.ai/testing-operations/seamless-upgrade
================================================================================

Seamless Upgrade for AI Employees Overview Seamless Upgrade helps builders safely test and deploy changes to a live AI Employee without causing downtime. It is designed for situations where an AI Employee is already in production and you need a safer way to update behavior, data, or configuration. Key Features Clone AI Employee with Data -- Creates a full, editable copy of a live AI Employee, including uploaded files, configurations, and workflows. The cloned AI Employee is disabled by default, keeping tests isolated from live traffic. Import Changes from a Test AI Employee -- After validating changes in the clone, import those changes back into the production AI Employee of the same type. This applies workflows, data, and configurations while preserving production properties like metrics, API keys, and permissions. End-to-end upgrade workflow -- Supports a complete clone, test, validate, and deploy flow within the platform, reducing manual effort and avoiding downtime risk. The Problem Once an AI Employee is live, making changes can be risky and slow: No safe testing environment -- Previous cloning did not carry over data, requiring manual re-uploads. Manual effort and errors -- Files had to be ingested repeatedly, consuming time and increasing the chance of mistakes. Difficult evaluations -- Testing updated behavior consistently took significant time. Downtime risk -- Migrating changes back to the original AI Employee could disrupt service. How to Use Seamless Upgrade The workflow has three phases: Clone > Make changes and test > Import changes back to production. Step 1: Clone the Production AI Employee Navigate to the production AI Employee you want to test. Click the three-dot menu in the top-right corner. Select Clone AI Employee. In the modal: Enter a name for the new test AI Employee. Choose Clone AI Employee with Data as the clone type. Click Clone AI Employee. The system clones the AI Employee along with all ingested data. A banner displays during the cloning process. Time to complete depends on the volume of files. Important notes: During cloning, neither AI Employee can be edited, but the original AI Employee continues to function without disruption. Files currently in progress in the original AI Employee are also cloned once they are successfully ingested. Failed files are not cloned. You can simultaneously clone the same AI Employee multiple times. The system supports cloning a maximum of 6,000 files per hour across the tenant. Step 2: Make Your Changes Once cloning is complete: Modify data -- add or remove files. Change configuration or workflow. Test in the platform. Step 3: Import Changes Back to Production Once you are satisfied with your changes: Navigate to the production AI Employee where you want to import the changes. Click the three-dot menu in the top-right corner. Click Import changes from AI Employee. Select the clone AI Employee from the dropdown. Click Import. During import, a banner is displayed and both AI Employees are locked for editing. Both AI Employees continue to function during the import. What Gets Imported vs. Preserved ImportedPreserved on the originalWorkflowsAPI keysDataMetricsConfigurationsPermissions If the import does not complete successfully, no changes are applied -- there is no partial import, and the original AI Employee remains unaffected. Once import is complete, a completion banner is displayed and the production AI Employee uses the imported data and configuration to respond.

================================================================================
# Testing AI Employees
URL: https://builder.ema.ai/testing-operations/testing
================================================================================

Testing AI Employees Testing and evaluation is an ongoing process for all AI Employees. This guide covers how to create refined test datasets, perform test-driven AI Employee development, and continue evaluating AI Employees that have already been deployed. Testing New AI Employees The testing approach varies by AI Employee type. The examples below illustrate the process for two common types: Chat-based AI Employee -- A policy assistant that responds to employee queries and personalizes answers based on location and level. Dashboard-based AI Employee -- A financial audit assistant that categorizes incoming documents as invoices or purchase orders, extracts values, and validates them against company rules. Step 1: Testbed Creation and Test Prep Whether you are creating a new AI Employee from a template or via a custom GWE workflow, begin by collecting all existing use cases in a single place. Chat AI Employees Create a diverse query testbed. Build an extensive set of queries that end users might ask. Include variations across all supported languages, synonyms, and company-specific terminology. Account for follow-up queries. Create a separate testbed that outlines follow-up queries and expected responses. Cover both: Follow-ups relevant to the previous query (to verify context retention). Follow-ups irrelevant to the previous query (to rule out context contamination). Account for different user types. If user parameters matter for personalization (e.g., location, role), ensure your testbed includes queries from each user type. Include out-of-scope cases. Flag deprioritized, inappropriate, or irrelevant queries and set up the AI Employee to respond with a boilerplate disclaimer explaining they are out of scope. Create golden response outputs. Capture all the key elements of a good response: required facts, tone, and disclaimers. Since agentic responses are non-deterministic, the AI Employee response will not always match the golden response exactly. You can either: Have a human evaluate whether the response covers key points. Use an LLM evaluator with a golden prompt to check coverage. Dashboard AI Employees Create a varied testbed of inputs. For example, for a document processing AI Employee, include a variety of invoices and purchase orders. Represent all document formats and complexities. Include image-heavy documents, large documents, and handwritten, blurry, or scanned documents where applicable. Exclude formats that are not relevant to your use case. Both Types Account for HITL use cases. Mark test cases where Human-In-The-Loop is required and note potential inputs from the user at each step. Prepare sandbox environments. If you cannot use production app integrations for testing, have a sandbox version with similar data ready. Step 2: Progressive Testing During Development Build and test the workflow incrementally rather than all at once. Tackle a few test cases at a time. Progressively build an AI Employee that can address your entire testbed. Different team members can build different parts of the workflow in isolation and consolidate later. For example, with a policy assistant, start by adding support for payroll-related queries only. Hand over this v1 to payroll SMEs for testing while you build out support for other categories. Once payroll queries are answered satisfactorily, add an intent categorizer and test whether it accurately differentiates between payroll, vacation, and medical queries. Publish intermediate outputs for debugging. Use intermediate responses to inspect each step of the workflow individually. You can: Add "Logging" steps using the Fixed Response agent combined with workflow branching via Trigger When to detect which arm of the workflow was triggered. Publish the output of helper agents (e.g., a Query Augmenter) to verify they work correctly before building the next steps. Unpublish intermediate outputs once you are satisfied and move on. Use Show Work to debug responses. Show Work logs display the agents invoked, steps taken, and error messages for each response. See the section below. Using Show Work Show Work logs help demonstrate the steps taken to respond to each query. They provide a log of agents invoked, steps taken by each agent, and error messages if any agent failed. For chat AI Employees: View Show Work logs in the Ema webapp chat. If building an embeddable chatbot, go to the GWE Canvas and click "Use AI Employee" to start a webapp-based chat (the test chatbot does not display Show Work logs since it emulates the end-user experience). How to use Show Work: Inspect which category was chosen to verify the correct workflow branch was selected. Check which agent might be causing quality issues (e.g., zero search results, or an oversized model causing slowness). In cases of complete failure, view the last agent that ran and any error messages it produced. Step 3: User Acceptance Testing (UAT) Before launching to production, run a full round of end-to-end testing. Go through the entire testbed. Impersonate all kinds of users with the same AI Employee. Mock production scale. Ensure the AI Employee will not buckle under production volumes. Remove all debug artifacts. Remove intermediate outputs to ensure the experience matches what an actual end user will see. Recruit actual testers. Nominate a few real users as testers with minimal instructions to mimic actual end-user behavior. Their feedback is often more useful for improving onboarding and training material than for improving the product itself. Testing Existing AI Employees Testing existing AI Employees is more challenging because live users may be impacted by regressions. All the steps above apply, along with these additional strategies: Create a copy of the AI Employee. Use the clone feature (see Seamless Upgrade) to maintain a separate test version that is always slightly ahead of the production version. Test isolated workflows. If you plan to add a new branch, test it in isolation in a new AI Employee, then merge it into the main AI Employee once you are satisfied. Quick Tips Save workflow copies. Store copies of past workflows so you can easily inspect or roll back if you see regressions. Download the persona config from the browser inspector (copy the response of the "Get personas" API call) or copy the config from the code view in the GWE visual editor. Track changes and impact. Keep an annotated log of changes and corresponding test results so you can correlate changes with outcomes. Keep evaluations objective. Use blind evaluations between the AI Employee and a human performing the same role. Users frequently overestimate human accuracy; benchmarking against humans establishes relative accuracy. Launch progressively. It is acceptable to launch test cases where the AI Employee performs well while letting it take a back seat on complex cases. For those cases, configure HITL for human approval or provide a disclaimer so users know the AI Employee may be less reliable.

================================================================================
# API Reference
URL: https://builder.ema.ai/api-reference
================================================================================

API Reference This section provides comprehensive documentation for Ema's Builder Platform APIs. Use these references to integrate with Ema programmatically, manage AI Employees, orchestrate workflows, handle chat interactions, operate dashboards, and generate documents. Getting Started Getting Started -- REST API quickstart covering authentication, tenant setup, AI Employee creation, chat, and dashboard interaction. Authentication -- How to generate API keys and access tokens. Tenant Management -- Create and manage tenants in Ema's hierarchy. AI Employees AI Employee Overview -- Core concepts: AI Employees, templates, categories, behavior types, widgets, and trigger types. AI Employee Data Model -- PersonaConfig, Widget, WidgetType enum, DisplaySettings, and ProjectSettings structures. AI Employee API -- Create, update, retrieve, and manage AI Employees. Template API -- Create, update, and manage AI Employee templates with access control. Workflows Workflow Overview -- Core concepts: workflows, actions, input bindings, execution flow, and outputs. Workflow Data Model -- WorkflowDef, ActionInstance, InputBinding, Tool, Condition, TypeReference, and EnumType structures. Action Data Model -- ActionType, ActionCategory, InputDef, OutputDef, WellKnownType, and Value system. Workflow API -- List actions, query workflow structure, and retrieve edge candidates. Chat Chat Overview -- Conversations, messages, snippets, source attribution, and platform integrations. Chat Data Model -- ChatbotMessage, MessageType, TextMessage, ButtonsMessage, FormMessage, FeedbackMessage, and Snippet types. Chat API -- Create conversations, send messages, retrieve history, and collect feedback. Dashboard Dashboard Overview -- Structure, rows, columns, states, HITL support, and use cases. Dashboard Data Model -- DashboardRow, DashboardRowState, ColumnValue, ColumnDetails, ColumnType, and DashboardSchema. Dashboard HTTP API -- REST endpoints for row upload, triggering, results, and HITL continuation. Dashboard RPC Calls -- gRPC-Web endpoints for dashboard row and workflow operations. Document Generation Document Generation Overview -- Async document lifecycle, statuses, and use cases. Document Generation API -- Create, retrieve, regenerate, and update documents. Miscellaneous Miscellaneous APIs -- File upload and pre-signed URL endpoints. Handling gRPC-Web Requests -- Step-by-step guide for making gRPC-Web calls with curl. Access Token for Root Tenant API Key -- How to obtain an initial access token for first-time API setup. Debug Worklogs API -- Retrieve workflow-level debug logs and show-work data. Triggers Triggering AI Employees -- Set up recurring and event-based triggers to invoke AI Employees from external platforms.

================================================================================
# AI Employee API
URL: https://builder.ema.ai/api-reference/ai-employees/ai-employee-api
================================================================================

AI Employee API This page documents the REST API endpoints for creating, updating, and managing AI Employees (personas). CreateAIEmployee Create a new AI Employee within a tenant. PropertyValueURL/api/personas/create_personaHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionnamestringYesDisplay name of the AI EmployeedescriptionstringNoDescription of the AI Employee's purposetemplate_idstringConditionalTemplate ID to base the AI Employee on. Provide exactly one of template_id or source_persona_id.source_persona_idstringConditionalSource AI Employee to clone from. Provide exactly one of template_id or source_persona_id.proto_configobjectNoFull protobuf configuration (widgets, display settings, etc.)trigger_typestringNoOptional trigger type such as CHAT or DASHBOARDclone_databooleanNoWhen cloning from source_persona_id, also replicate uploaded files and scraped URLs Example curl -X POST https://your-instance.ema.co/api/personas/create_persona \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "IT Support Agent", "description": "Handles IT helpdesk tickets and troubleshooting", "template_id": "<template-uuid>", "trigger_type": "CHAT", "proto_config": { "widgets": [], "display_settings": { "display_type": "SINGLE_PAGE" } } }' Response FieldTypeDescriptionpersona_idstringUUID of the created AI EmployeestatestringInitial state of the created AI Employeeworkflow_idstringAssociated workflow ID, if one was created UpdateAIEmployee Update an existing AI Employee's configuration. PropertyValueURL/api/personas/update_personaHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionpersona_idstringYesUUID of the AI Employee (sent in the request body, not as a path parameter)namestringNoUpdated display namedescriptionstringNoUpdated descriptionproto_configobjectYesUpdated protobuf configurationworkflowobjectNoUpdated workflow definition when changing the associated workflow Example curl -X POST https://your-instance.ema.co/api/personas/update_persona \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "persona_id": "<persona-uuid>", "name": "Updated IT Support Agent", "description": "Enhanced IT helpdesk support with broader knowledge base", "proto_config": { "widgets": [] } }' Response Returns the updated PersonaDTO. GetAccessLevel Retrieve the current user's access level for a specific AI Employee. PropertyValueURL/api/personas/{persona_id}/access_levelHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Path Parameters ParameterTypeDescriptionpersona_idstringUUID of the AI Employee Example curl -X GET https://your-instance.ema.co/api/personas/<persona_id>/access_level \ -H "Authorization: Bearer <access_token>" Response FieldTypeDescriptionidstringUUID of the AI Employeeaccess_levelstringThe user's access level for this AI Employee GetPersonasForTenant Retrieve all AI Employees for the authenticated tenant. PropertyValueURL/api/personas/get_personas_for_tenantHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Example curl -X GET https://your-instance.ema.co/api/personas/get_personas_for_tenant \ -H "Authorization: Bearer <access_token>" Response Returns a list of AI Employee objects for the tenant. FieldTypeDescriptionpersonasarrayList of PersonaDTO objects Each PersonaDTO includes fields such as id, template_id, name, description, status, proto_config, access_level, and other metadata. DeleteAIEmployee Delete an AI Employee. PropertyValueURL/api/personas/{persona_id}HTTP MethodDELETEProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Path Parameters ParameterTypeDescriptionpersona_idstringUUID of the AI Employee Example curl -X DELETE https://your-instance.ema.co/api/personas/<persona_id> \ -H "Authorization: Bearer <access_token>" Related AI Employee Overview -- Core concepts AI Employee Data Model -- Data structures Template API -- Template management

================================================================================
# AI Employee Data Model
URL: https://builder.ema.ai/api-reference/ai-employees/data-model
================================================================================

AI Employee Data Model This page defines the protobuf data structures used to configure AI Employees (personas) in the Ema platform. PersonaConfig The top-level configuration object for an AI Employee. FieldTypeDescriptionidstringUnique identifier (UUID)namestringDisplay name of the AI EmployeedescriptionstringBrief description of the AI Employee's purposeiconstringIcon identifierstatusTemplateStatusDeprecated template status fieldeditableboolWhether the configuration is editableversionint32Configuration version numberrich_detail_descriptionstringRich text description (supports formatting)widgetsrepeated WidgetList of widget configurationsdisplay_settingsDisplaySettingsUI display configurationproject_settingsProjectSettingsProject-level settings and defaultstriggerPersonaTriggerOperational trigger configurationpersona_statusPersonaStateEnumPersona stateaccess_levelPersonaAccessLevelComputed access levelpersona_trigger_typePersonaTriggerTypeUser-facing trigger type such as chat or dashboardworkflow_dashboard_idstringAssociated workflow dashboard IDtemplate_idstringTemplate ID this persona was instantiated frompersona_group_idstringOptional persona group identifier Widget A Widget connects the AI Employee to an external data source or integration. FieldTypeDescriptionnamestringUnique name of the widget instancetypeWidgetTypeThe type of widget<widget field>objectType-specific configuration stored under the matching widget field (for example file_upload or chatbot_sdk_config) WidgetType Enum ValueIntegerDescriptionSCRAPE_URLS0URL scraping configurationEXAMPLE_TRIGGERS1Example triggers (deprecated)WEBSEARCH_ENABLED2Web search enablementFILE_UPLOAD3Direct file uploadDATA_INTEGRATION4Data source integrationANSWER_FORMAT5Answer format configurationFUSION_MODEL6Fusion LLM model selectionEXAMPLE_QUESTIONS7Example questions for the AI EmployeeDATA_PROTECTION8Data protection settingsCOPYRIGHT_CHECK9Copyright checkingSTEPS10Workflow steps configurationTICKET_CATEGORY_CONFIG11Ticket category configurationCUSTOM_INSTRUCTIONS12Custom instructionsGLOSSARY13Glossary termsHEIRARCHICAL_TAGS14Hierarchical tagsPROPOSAL_TEMPLATE_TYPE15Proposal template typeDOC_SECTION_CONFIG16Document section configurationCOMPANY_DETAILS17Company detailsEMAIL_INTEGRATION18Email integrationTARGET_AUDIENCE19Target audience (deprecated)EMAIL_CONFIGURATION20Email configuration (deprecated)CAMPAIGN_GOAL_SETUP21Campaign goal setupBASE_CATEGORY_WIDGET22Base category widgetTITLE_WITH_TEXT_AREA23Title with text areaLINKEDIN_INTEGRATION24LinkedIn integrationCANDIDATE_SEARCH_DETAILS25Candidate search detailsCANDIDATE_SEARCH_SCORECARD26Candidate search scorecardTARGET_COMPANY_SEARCH27Target company searchCHATBOT_SDK_CONFIG28Chatbot SDK configurationFILE_TAGGING29File taggingMULTI_SOURCE_TARGET_AUDIENCE30Multi-source target audienceFILE_LINKING31File linkingTEMPLATE_INPUT32Template inputFEEDBACK_MESSAGE33Feedback messageBLOCK_USERS34Block usersENGAGEMENT_CONFIGURATION35Engagement configurationSFO_ID_CONFIG36SFO ID configurationVOICEBOT_VOICE_SETTINGS38Voicebot voice settingsVOICEBOT_CONVERSATION_SETTINGS39Voicebot conversation settingsVOICEBOT_FEEDBACK_COLLECTION40Voicebot feedback collectionVOICEBOT_CALL_SETTINGS41Voicebot call settingsVOICEBOT_DATA_STORAGE_SETTINGS42Voicebot data storage settingsVOICEBOT_VAD_SETTINGS43Voicebot VAD settingsVOICEBOT_PHONE_NUMBER44Voicebot phone numberDOCUMENT_INSTRUCTIONS_CONFIG45Document instructions configurationDOCUMENT_OUTLINE_SOURCE46Document outline sourceSTYLE_GUIDE_SOURCE47Style guide sourceWORKFLOW_DYNAMIC_INPUTS48Workflow dynamic inputsEMAIL_INTEGRATION_V249Email integration v2 (API-powered)AGENT_QA_RULE_GENERATION50Agent QA rule generationEMAIL_EMPLOYEE_INBOX_PREFERENCES51Email employee inbox preferencesDOCUMENT_APPROVAL52Document approvalTOOL_WIDGET53Custom tools widget (deprecated)AGENT_QA_INSIGHT_GENERATION54Agent QA insight generationTOOL_PERSONA_CONFIG55Tool persona configurationRFP_EXTRACTED_FIELDS56RFP extracted fields Complete list of WidgetType values from the proto definition. Note that value 37 is not assigned. DisplaySettings Controls how the AI Employee appears in the UI. FieldTypeDescriptiondisplay_typeDisplayTypeDisplay mode for the persona UIpagesrepeated DisplayPagePages shown for multi-page or tabbed displays Complete list of DisplaySettings fields. ProjectSettings Project-level configuration for the AI Employee. FieldTypeDescriptionenabledboolWhether projects are enabled for this personadisplay_namestringDisplay name used for projects in the UIproject_typeProjectTypeProject type associated with the personaallowed_sub_projectsrepeated SubProjectAllowed sub-project categoriesselected_sub_project_typeSubProjectTypeCurrently selected sub-project typeworkflowsrepeated ProjectWorkflowProject workflows associated with the persona Complete list of ProjectSettings fields. PersonaTrigger Defines how the AI Employee is triggered. FieldTypeDescriptiontypePersonaTrigger.TriggerTypeOperational trigger sourceintegration_idstringIntegration ID used for data-ingestion triggerstriggerer_emailstringEmail address associated with the trigger when applicable PersonaTriggerType Enum ValueIntegerDescriptionCHAT1Triggered by a chat conversationDASHBOARD2Triggered by a dashboard row operationTHREAD3Triggered by a thread interactionCHATBOT4Triggered by an external chatbotDOCUMENT_GENERATION5Triggered by a document generation requestCONVERSATIONAL_EMAIL6Triggered by a conversational email interactionAGENT_QA7Triggered by Agent QA evaluation TemplateStatus Enum ValueIntegerDescriptionACTIVE0Template is activeINACTIVE1Template is inactive Related AI Employee Overview -- Concepts and architecture AI Employee API -- CRUD endpoints Workflow Data Model -- Workflow structures used by AI Employees

================================================================================
# AI Employee Overview
URL: https://builder.ema.ai/api-reference/ai-employees/overview
================================================================================

AI Employee Overview An AI Employee is Ema's core abstraction for an autonomous agent. Each AI Employee has a defined personality, knowledge sources, workflows, and interaction channels. The platform refers to these as "personas" in the API layer. Core Concepts AI Employee (Persona) An AI Employee is a configured agent that: Has a name, description, and icon Belongs to a specific tenant Contains one or more workflows that define its behavior Connects to knowledge sources through widgets Supports multiple interaction channels (chat, dashboard, document generation) Templates Templates are reusable starting points for creating AI Employees. A template defines: Default workflows and widget configurations A category such as General, Employee Experience, or Sales Experience Access control for which tenants can use the template Templates can be granted to specific tenants or made globally available. Categories Templates are organized into categories that describe their functional area: GENERAL EMPLOYEE_EXPERIENCE SALES_EXPERIENCE CUSTOMER_EXPERIENCE HEALTHCARE BFSI The full list of supported categories. Behavior Types The API exposes this as trigger_type / PersonaTriggerType, which determines how an AI Employee interacts with users: CHAT -- Real-time conversational interaction DASHBOARD -- Batch processing of tabular data DOCUMENT_GENERATION -- Producing documents asynchronously Whether additional behavior types exist. Widgets Widgets are configuration blocks that connect an AI Employee to external systems and knowledge sources. Each widget has a type and type-specific configuration. The platform supports 30+ widget types, including: Knowledge sources (Confluence, Google Drive, SharePoint, Notion, etc.) Communication channels (Slack, Teams, Email) CRM integrations (Salesforce, HubSpot) Ticketing systems (Jira, ServiceNow, Zendesk) See AI Employee Data Model for the complete WidgetType enum. Trigger Types The PersonaTriggerType enum defines how an AI Employee is activated: ValueIntegerDescriptionCHAT1Triggered by a chat conversationDASHBOARD2Triggered by a dashboard row operationTHREAD3Triggered by a thread interactionCHATBOT4Triggered by an external chatbotDOCUMENT_GENERATION5Triggered by a document generation requestCONVERSATIONAL_EMAIL6Triggered by a conversational email interactionAGENT_QA7Triggered by Agent QA evaluation Architecture AI Employee (Persona) ├── PersonaConfig │ ├── Widgets[] -- Knowledge sources and integrations │ ├── DisplaySettings -- UI configuration │ └── ProjectSettings -- Project-level defaults ├── Workflow(s) │ ├── Actions[] -- Steps in the workflow │ └── InputBindings[] -- Data flow between actions └── Trigger └── PersonaTriggerType -- How the AI Employee is activated Related AI Employee Data Model -- Full data structures AI Employee API -- CRUD endpoints Template API -- Template management Workflow Overview -- How workflows power AI Employee behavior

================================================================================
# Template API
URL: https://builder.ema.ai/api-reference/ai-employees/template-api
================================================================================

Template API Templates are reusable configurations for creating AI Employees. This page documents the API endpoints for creating, updating, and managing access to templates. CreateTemplate Create a new AI Employee template. PropertyValueURL/api/personas/create_persona_templateHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionnamestringYesDisplay name of the templatedescriptionstringNoDescription of the template's purposecategorystringNoTemplate category such as GENERAL or EMPLOYEE_EXPERIENCEproto_configobjectNoDefault protobuf configurationworkflow_defobjectNoDefault workflow definitiontrigger_typestringNoTrigger type for personas created from this template Example curl -X POST https://your-instance.ema.co/api/personas/create_persona_template \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "Basic Q&A Template", "description": "Template for knowledge-base Q&A AI Employees", "category": "GENERAL", "proto_config": { "widgets": [], "display_settings": { "display_type": "SINGLE_PAGE" } } }' Response FieldTypeDescriptiontemplate_idstringUUID of the created template UpdateTemplate Update an existing template's configuration. PropertyValueURL/api/personas/update_persona_templateHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptiontemplate_idstringYesUUID of the template to updatenamestringNoUpdated display namedescriptionstringNoUpdated descriptioncategorystringNoUpdated categoryproto_configobjectNoUpdated protobuf configurationworkflow_defobjectNoUpdated workflow definition Example curl -X POST https://your-instance.ema.co/api/personas/update_persona_template \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "template_id": "<template-uuid>", "name": "Enhanced Q&A Template", "description": "Updated template with improved search and response" }' GrantAccess Grant a tenant access to use a specific template. PropertyValueURL/api/personas/grant_persona_template_accessHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptiontemplate_idstringYesUUID of the templategrantee_tenant_idstringYesUUID of the tenant to grant access to Example curl -X POST https://your-instance.ema.co/api/personas/grant_persona_template_access \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "template_id": "<template-uuid>", "grantee_tenant_id": "<tenant-uuid>" }' RevokeAccess Revoke a tenant's access to a specific template. PropertyValueURL/api/personas/revoke_persona_template_accessHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptiontemplate_idstringYesUUID of the templatetarget_tenant_idstringYesUUID of the tenant to revoke access from Example curl -X POST https://your-instance.ema.co/api/personas/revoke_persona_template_access \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "template_id": "<template-uuid>", "target_tenant_id": "<tenant-uuid>" }' GetPersonaTemplates Retrieve available templates. PropertyValueURL/api/personas/get_persona_templatesHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Example curl -X GET https://your-instance.ema.co/api/personas/get_persona_templates \ -H "Authorization: Bearer <access_token>" Response FieldTypeDescriptiontemplatesarrayList of PersonaTemplateDTO objects Each template includes id, name, description, category, icon, and configuration details. GetPersonaTemplate Retrieve a specific template by ID. PropertyValueURL/api/personas/persona_template/{template_id}HTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Path Parameters ParameterTypeDescriptiontemplate_idstringUUID of the template Example curl -X GET https://your-instance.ema.co/api/personas/persona_template/<template_id> \ -H "Authorization: Bearer <access_token>" Related AI Employee Overview -- Core concepts AI Employee API -- AI Employee CRUD operations

================================================================================
# Authentication
URL: https://builder.ema.ai/api-reference/authentication
================================================================================

Authentication Ema's API uses a two-step authentication flow: first generate an API key, then exchange it for a short-lived access token (JWT). All subsequent API calls use the access token in the Authorization header. Authentication Flow 1. GenerateApiKey (gRPC-Web) --> API Key (long-lived) 2. GenerateAccessToken (REST) --> Access Token (JWT, short-lived) 3. Use Access Token in Authorization header for all API calls Step 1: Generate an API Key Create an API key for a user within a specific tenant. This is a gRPC-Web endpoint. PropertyValueURL/auth.v1.AuthService/GenerateApiKeyHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token with user authenticationContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionemailstringYesEmail address of the user to generate the key forscopeApiKeyScopeNoThe scope for the API key. Default: API_KEY_SCOPE_GLOBAL. Response FieldTypeDescriptionapi_keystringThe generated API keyapi_key_idstringThe generated API key ID Example # Encode the request cat <<EOF | protoc -I=. --encode=auth.v1.GenerateApiKeyRequest \ service/auth/v1/auth.proto > request.bin email: "user@example.com" EOF # Frame the request python3 -c 'import sys,struct; data=sys.stdin.buffer.read(); \ sys.stdout.buffer.write(b"\x00"+struct.pack(">I",len(data))+data)' \ < request.bin > framed_request.bin # Send the request curl -X POST https://your-instance.ema.co/auth.v1.AuthService/GenerateApiKey \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/grpc-web+proto" \ -H "x-grpc-web: 1" \ --data-binary @framed_request.bin \ --output response.bin First-time setup: If you do not yet have an access token, see Access Token for Root Tenant API Key for instructions on obtaining one from your browser session. For the full gRPC-Web encoding/decoding process, see Handling gRPC-Web Requests. Step 2: Generate an Access Token Exchange an API key for a JWT access token using the REST endpoint. PropertyValueURL/api/auth/generate_access_tokenHTTP MethodPOSTProtocolREST (HTTP) Headers HeaderTypeRequiredDescriptionx-ema-api-keystringYesYour API key Request Body This endpoint does not require a request body. Pass the API key in the x-ema-api-key header. Response Body FieldTypeDescriptionaccess_tokenstringJWT access token for API authorization Example curl -X POST https://your-instance.ema.co/api/auth/generate_access_token \ -H "x-ema-api-key: your-api-key-here" Response: { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } Token Expiration API Key TypeToken LifetimeGlobal API key24 hoursChatbot API key30 minutes When a token expires, generate a new one by calling GenerateAccessToken again with the same API key. Using the Access Token Include the access token in the Authorization header of every API request: Authorization: Bearer <access_token> This applies to both REST and gRPC-Web endpoints. API Key Types Ema supports two types of API keys: Global API key: Full access to all Builder Platform APIs. Tokens last 24 hours. Chatbot API key: Restricted to chatbot-related endpoints. Tokens last 30 minutes. Related Getting Started -- End-to-end quickstart Handling gRPC-Web Requests -- Detailed gRPC-Web encoding guide Access Token for Root Tenant API Key -- First-time token setup

================================================================================
# Chat API
URL: https://builder.ema.ai/api-reference/chat/chat-api
================================================================================

Chat API This page documents the API endpoints for managing chat conversations and messages with AI Employees. CreateConversation Create a new conversation with an AI Employee. PropertyValueURL/api/chat/HTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionpersona_idstringYesUUID of the AI Employee to chat with Example curl -X POST https://your-instance.ema.co/api/chat/ \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "persona_id": "abc12345-6789-0abc-def0-123456789abc" }' Response Returns the initial AI Employee greeting and conversation metadata. FieldTypeDescriptionconversation_idstringUUID of the created conversationmessagesarrayInitial messages (e.g., welcome message) RespondToMessage (Synchronous) Send a user message and receive an AI response synchronously. PropertyValueURL/api/chat/{conversation_id}HTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Path Parameters ParameterTypeDescriptionconversation_idstringUUID of the conversation Request Body FieldTypeRequiredDescriptionmessagestringYesThe user's message text Example curl -X POST https://your-instance.ema.co/api/chat/<conversation_id> \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "message": "How do I reset my password?" }' Response Returns the AI Employee's reply, including message content, snippets, and sources. FieldTypeDescriptionmessagesarrayAI response messages with snippets and sources RespondToMessage (Asynchronous) Send a user message without waiting for the AI response. PropertyValueURL/api/chat/{conversation_id}/asyncHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Path Parameters ParameterTypeDescriptionconversation_idstringUUID of the conversation Request Body FieldTypeRequiredDescriptionmessagestringYesThe user's message text Example curl -X POST https://your-instance.ema.co/api/chat/<conversation_id>/async \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "message": "Generate a summary report for Q4 sales" }' The response acknowledges receipt. Poll GetMessages to retrieve the AI response when ready. GetMessages Retrieve all messages in a conversation. PropertyValueURL/api/chat/{conversation_id}HTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Path Parameters ParameterTypeDescriptionconversation_idstringUUID of the conversation Example curl -X GET https://your-instance.ema.co/api/chat/<conversation_id> \ -H "Authorization: Bearer <access_token>" Response Returns the full message history for the conversation, including all messages and conversation metadata. GetChatbotConfig Retrieve the chatbot configuration for a specific AI Employee. PropertyValueURL/api/chat/config/{persona_id}HTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Path Parameters ParameterTypeDescriptionpersona_idstringUUID of the AI Employee Example curl -X GET https://your-instance.ema.co/api/chat/config/<persona_id> \ -H "Authorization: Bearer <access_token>" Response Returns the chatbot configuration including welcome message, suggested questions, branding, and display settings. GetConversationFeedback Retrieve aggregated feedback for conversations. PropertyValueURL/api/conversations/get_conversation_feedbackHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Query Parameters ParameterTypeRequiredDescriptionpersona_idstringYesUUID of the AI Employee Example curl -X GET "https://your-instance.ema.co/api/conversations/get_conversation_feedback?persona_id=<persona_id>" \ -H "Authorization: Bearer <access_token>" GetConversationFeedbackDetail Retrieve detailed feedback for a specific conversation. PropertyValueURL/api/conversations/get_conversation_feedback_detailHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Query Parameters ParameterTypeRequiredDescriptionconversation_idstringYesUUID of the conversation Example curl -X GET "https://your-instance.ema.co/api/conversations/get_conversation_feedback_detail?conversation_id=<conversation_id>" \ -H "Authorization: Bearer <access_token>" LogCustomEvent Log a custom event for analytics tracking in a chatbot session. PropertyValueURL/api/chat/eventsHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionevent_namestringYesName of the custom eventevent_dataobjectNoAdditional event data Related Chat Overview -- Concepts and architecture Chat Data Model -- Message structures AI Employee API -- AI Employee management

================================================================================
# Chat Data Model
URL: https://builder.ema.ai/api-reference/chat/data-model
================================================================================

Chat Data Model This page defines the data structures used in the Chat API for messages, conversations, and response types. ChatbotMessage The top-level message object in a conversation. FieldTypeDescriptionmessage_idstringUnique identifier for the messageconversation_idstringID of the conversation this message belongs tomessage_typeMessageTypeType of message contentcontentobjectMessage content (varies by message type)senderstringSender identifier (user or ai)timestampstringISO 8601 timestampsnippetslist of SnippetStructured content blockssourceslist of SourceSource attributions MessageType ValueDescriptionTEXTPlain text or markdown messageBUTTONSMessage with clickable buttonsFORMMessage with form fieldsFEEDBACKFeedback request (rating/thumbs)URLURL/link message Complete list of MessageType values. TextMessage A plain text or markdown-formatted message. FieldTypeDescriptiontextstringThe message content (supports markdown) ButtonsMessage A message presenting clickable options to the user. FieldTypeDescriptiontextstringPrompt text above the buttonsbuttonslist of ButtonList of button options Button FieldTypeDescriptionlabelstringDisplay text for the buttonvaluestringValue sent when the button is clicked FormMessage A message presenting form fields for structured input. FieldTypeDescriptiontextstringPrompt text above the formfieldslist of FormFieldList of form fields FormField FieldTypeDescriptionnamestringField identifierlabelstringDisplay labeltypeFormFieldTypeField type (text, number, select, etc.)requiredbooleanWhether the field is requiredoptionslist of stringsOptions for select/dropdown fieldsdefault_valuestringDefault value FormFieldType ValueDescriptionTEXTSingle-line text inputTEXTAREAMulti-line text inputNUMBERNumeric inputSELECTDropdown selectionCHECKBOXBoolean checkboxDATEDate picker Complete list of FormFieldType values. FeedbackMessage A message requesting user feedback on the AI response. FieldTypeDescriptiontextstringPrompt text for the feedback requestfeedback_typestringType of feedback (thumbs, rating, text) Snippet Types Snippets are structured data blocks within messages. The platform supports the following snippet types: Snippet TypeDescriptionTextSnippetFormatted text blockCodeSnippetCode with syntax highlightingTableSnippetTabular dataImageSnippetInline imageFileSnippetDownloadable file attachmentLinkSnippetHyperlink with previewListSnippetOrdered or unordered listChartSnippetData visualizationSourceSnippetKnowledge source citationActionResultSnippetOutput from a workflow actionErrorSnippetError message with detailsProgressSnippetProgress indicatorSuggestionSnippetSuggested follow-up questionsJSONSnippetFormatted JSON dataMarkdownSnippetRich markdown content Complete list of snippet types. Source A source attribution linking a response to its knowledge origin. FieldTypeDescriptiontitlestringTitle of the source documenturlstringURL to the source documentsnippetstringRelevant excerpt from the sourcesource_typestringType of source (e.g., confluence, gdrive) ConversationChatMessageHistory The full message history for a conversation. FieldTypeDescriptionmessageslist of ChatbotMessageAll messages in the conversationmetadataConversationMetadataConversation metadata ConversationMetadata FieldTypeDescriptionconversation_idstringUnique conversation identifierpersona_idstringAI Employee IDcreated_atstringISO 8601 creation timestampupdated_atstringISO 8601 last update timestamp Related Chat Overview -- Concepts and architecture Chat API -- API endpoints

================================================================================
# Chat Overview
URL: https://builder.ema.ai/api-reference/chat/overview
================================================================================

Chat Overview The Chat API enables real-time conversational interactions with AI Employees. Users create conversations, send messages, and receive AI-generated responses that can include text, buttons, forms, feedback requests, and source attributions. Core Concepts Conversations A conversation is a session between a user and an AI Employee. Each conversation: Is tied to a specific AI Employee Contains an ordered sequence of messages Maintains context across multiple exchanges Supports both synchronous and asynchronous response modes Messages Messages flow in both directions: User messages -- Text input from the user AI responses -- Structured responses from the AI Employee, which can contain multiple message types Message Types AI Employee responses can include several message types: TypeDescriptionTextPlain text or markdown-formatted responseButtonsClickable options for the user to selectFormStructured form fields for collecting user inputFeedbackRequest for thumbs-up/thumbs-down or rating feedbackURLLink to an external resource Snippets Snippets are structured data blocks embedded in responses. They provide rich content such as: Source citations -- References to knowledge base articles Code blocks -- Formatted code with syntax highlighting Tables -- Structured tabular data Images -- Inline images File attachments -- Downloadable files Action results -- Outputs from workflow actions The platform supports 15+ snippet types for different content formats. Source Attribution When an AI Employee's response draws from knowledge sources, the response includes source attributions that link back to the original documents. This enables users to verify the information and access the full source material. Platform Integrations The Chat API supports multiple interaction channels: Web chatbot -- Embeddable chat widget for websites Slack -- Direct integration with Slack workspaces Microsoft Teams -- Integration with Teams channels API -- Direct API access for custom integrations Each channel uses the same underlying conversation and message model, with platform-specific adaptations for message formatting and delivery. Synchronous vs. Asynchronous Responses The Chat API offers two response modes: Synchronous -- The response is returned in the same request. Suitable for short interactions. See RespondToMessage (Synchronous) in the Chat API. Asynchronous -- The request returns immediately, and the response is delivered later. Suitable for long-running workflows. See RespondToMessage (Asynchronous) in the Chat API. Chatbot Configuration Each AI Employee can be configured with chatbot-specific settings: Welcome messages Suggested questions Brand colors and logos Source display preferences Custom CSS Retrieve chatbot configuration using the GetChatbotConfig endpoint in the Chat API. Related Chat Data Model -- Message and snippet structures Chat API -- API endpoints AI Employee Overview -- AI Employee architecture

================================================================================
# Dashboard Data Model
URL: https://builder.ema.ai/api-reference/dashboard/data-model
================================================================================

Dashboard Data Model This page defines the data structures for dashboards, rows, columns, and schema in the Ema platform. DashboardRow A single row in a dashboard. FieldTypeDescriptionrow_idstringUnique identifier (UUID) for the rowdashboard_idstringUUID of the parent dashboardstateDashboardRowStateCurrent processing statecolumn_valuesmap<string, ColumnValue>Map of column name to valueworkflow_run_idstringUUID of the associated workflow runcreated_atstringISO 8601 creation timestampupdated_atstringISO 8601 last update timestampcreated_bystringUser ID who created the rowerror_messagestringError details if state is FAILED DashboardRowState Enum ValueIntegerDescriptionUNSPECIFIED0Default/unspecifiedINITIAL1Row is in initial stateQUEUED2Row is queued for processingRUNNING3Workflow is currently executingSUCCESS4Workflow finished successfullyFAILED5Workflow encountered an errorREVIEWING6Row is under review (e.g., HITL) Complete list of DashboardRowState values and integer mappings. ColumnValue The value of a single cell in a dashboard row. FieldTypeDescriptionstring_valuestringString representation of the valuevalueValueTyped value (uses the workflow Value type)column_typeColumnTypeThe column's data type ColumnDetails Metadata for a single column in the dashboard schema. FieldTypeDescriptionnamestringInternal column identifierdisplay_namestringUser-friendly column namecolumn_typeColumnTypeData type of the columnis_inputboolWhether this is an input columnis_outputboolWhether this is an output columndescriptionstringDescription of the columntype_referenceTypeReferenceFull type referenceaction_namestringAction that produces this output columnoutput_namestringOutput parameter name for output columns ColumnType Enum ValueIntegerDescriptionUNSPECIFIED0Default/unspecifiedSTRING1Text stringNUMBER2Numeric value (double)BOOLEAN3True/falseDATE4Date valueTIME5Time valueDOCUMENT6Document referenceVALIDATION_REPORT7Validation reportARRAY8Array of valuesOBJECT9Object/mapINTEGER10Integer value (int64)ENUM11GWE enum type defined in workflow_defDOCUMENT_VERSION_ID12Document version identifier Complete list of ColumnType values from the proto definition. DashboardSchema The schema defining the structure of a dashboard. FieldTypeDescriptioncolumnsrepeated ColumnDetailsList of column definitions The schema is derived from the workflow's input/output definitions. Input columns correspond to workflow inputs, and output columns correspond to workflow outputs (or named results). DashboardRowResult Result data for a processed row, used by the HTTP API. FieldTypeDescriptionrow_idstringUUID of the rowstateDashboardRowStateProcessing statecolumn_valuesmap<string, ColumnValue>Output valueserror_messagestringError message if failed SubDashboard A filtered view of the main dashboard. FieldTypeDescriptionsub_dashboard_idstringUUID of the sub-dashboarddashboard_idstringUUID of the parent dashboardnamestringDisplay namefilterobjectFilter criteria Related Dashboard Overview -- Concepts and architecture Dashboard HTTP API -- REST endpoints Dashboard RPC Calls -- gRPC-Web endpoints

================================================================================
# Dashboard HTTP API
URL: https://builder.ema.ai/api-reference/dashboard/http-api
================================================================================

Dashboard HTTP API This page documents the REST HTTP endpoints for dashboard operations. All endpoints are prefixed with /api/personas/{persona_id}/dashboard/. All endpoints support an optional callback_url parameter. When provided, Ema sends the result to the callback URL upon completion instead of requiring polling. Upload and Run Rows Upload a file and automatically create and trigger rows. PropertyValueURL/api/personas/{persona_id}/dashboard/upload-and-run-rowsHTTP MethodPOSTProtocolREST (multipart/form-data) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesmultipart/form-data Path Parameters ParameterTypeDescriptionpersona_idstringUUID of the AI Employee Form Data FieldTypeRequiredDescriptionfilefileYesCSV or XLSX file with row datacallback_urlstringNoURL to receive results upon completion Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/upload-and-run-rows \ -H "Authorization: Bearer <access_token>" \ -F "file=@data.xlsx" \ -F "callback_url=https://your-server.com/webhook" Response FieldTypeDescriptionrow_idsarrayUUIDs of the created rows Get Row Result Retrieve the result of a single processed row. PropertyValueURL/api/personas/{persona_id}/dashboard/get-row-resultHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Query Parameters ParameterTypeRequiredDescriptionrow_idstringYesUUID of the row Example curl -X GET "https://your-instance.ema.co/api/personas/<persona_id>/dashboard/get-row-result?row_id=<row_id>" \ -H "Authorization: Bearer <access_token>" Response Returns a DashboardRowResult with the row's state and output values. Get All Row Results Retrieve results for all rows in the dashboard. PropertyValueURL/api/personas/{persona_id}/dashboard/get-all-row-resultsHTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Example curl -X GET https://your-instance.ema.co/api/personas/<persona_id>/dashboard/get-all-row-results \ -H "Authorization: Bearer <access_token>" Response Returns an array of DashboardRowResult objects. Add Row Add a single row to the dashboard. PropertyValueURL/api/personas/{persona_id}/dashboard/add-rowHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptioncolumn_valuesobjectYesMap of column name to valuecallback_urlstringNoURL to receive results Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/add-row \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "column_values": { "company_name": "Acme Corp", "website": "https://acme.com" } }' Update Row Update values in an existing row. PropertyValueURL/api/personas/{persona_id}/dashboard/update-rowHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionrow_idstringYesUUID of the row to updatecolumn_valuesobjectYesMap of column name to new value Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/update-row \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "row_id": "<row-uuid>", "column_values": { "company_name": "Acme Corporation" } }' Delete Rows Delete one or more rows from the dashboard. PropertyValueURL/api/personas/{persona_id}/dashboard/delete-rowsHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionrow_idsarrayYesList of row UUIDs to delete Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/delete-rows \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "row_ids": ["<row-uuid-1>", "<row-uuid-2>"] }' Trigger Row Trigger workflow processing for a specific row. PropertyValueURL/api/personas/{persona_id}/dashboard/trigger-rowHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionrow_idstringYesUUID of the row to triggercallback_urlstringNoURL to receive results Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/trigger-row \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "row_id": "<row-uuid>", "callback_url": "https://your-server.com/webhook" }' Get Continuation Message Retrieve the HITL continuation message for a paused row. PropertyValueURL/api/personas/{persona_id}/dashboard/get-continuation-messageHTTP MethodGETProtocolREST (HTTP/JSON) Query Parameters ParameterTypeRequiredDescriptionrow_idstringYesUUID of the paused row Example curl -X GET "https://your-instance.ema.co/api/personas/<persona_id>/dashboard/get-continuation-message?row_id=<row_id>" \ -H "Authorization: Bearer <access_token>" Response Returns the HITL message (form, buttons, or text prompt) that the workflow is waiting for. Continue Row Submit a HITL response to resume a paused workflow. PropertyValueURL/api/personas/{persona_id}/dashboard/continue-rowHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionrow_idstringYesUUID of the paused rowresponseobjectYesThe user's response to the HITL promptcallback_urlstringNoURL to receive results Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/continue-row \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "row_id": "<row-uuid>", "response": { "approved": true, "comment": "Looks good, proceed." } }' Related Dashboard Overview -- Concepts and architecture Dashboard Data Model -- Row, column, and schema structures Dashboard RPC Calls -- gRPC-Web endpoints for dashboard operations

================================================================================
# Dashboard Overview
URL: https://builder.ema.ai/api-reference/dashboard/overview
================================================================================

Dashboard Overview Dashboards provide a batch-processing interface for AI Employees. Instead of real-time chat, dashboards process tabular data row by row through workflows. Each row can trigger a workflow execution, and results are written back to the dashboard as new columns. Core Concepts Dashboard Structure A dashboard is a structured table associated with an AI Employee: Dashboard ├── Schema (column definitions) ├── Rows[] │ ├── Input Columns (user-provided data) │ ├── Output Columns (workflow-generated results) │ └── Row State (processing status) └── Sub-Dashboards (filtered views) Rows Each row represents a single unit of work. A row has: Input columns -- Data provided by the user (uploaded or manually entered) Output columns -- Results generated by the workflow State -- The processing status of the row Metadata -- Timestamps, user info, workflow run references Columns Columns are defined by the workflow's input/output schema. Each column has: A name and display name A data type (string, number, boolean, date, URL, file, etc.) A category (input vs. output) Optional display configuration Row States StateDescriptionNOT_STARTEDRow has not been processedIN_PROGRESSWorkflow is currently executingCOMPLETEDWorkflow finished successfullyFAILEDWorkflow encountered an errorPAUSEDWorkflow paused for human-in-the-loop input Complete list of DashboardRowState values. Human-in-the-Loop (HITL) Support When a workflow action requires human input, the dashboard row enters a PAUSED state. The user can: Retrieve the continuation message with GetContinuationMessageForRow View the HITL prompt (form, buttons, or text input) Submit a response with ContinueWorkflowForRow The workflow resumes processing from where it paused Sub-Dashboards Sub-dashboards are filtered views of the main dashboard. They allow users to organize rows by criteria such as status, date range, or custom filters without duplicating data. Use Cases Data enrichment -- Upload a list of companies, enrich each with research data Document review -- Upload documents, extract key information from each Lead qualification -- Upload leads, score and qualify each one Compliance checking -- Upload records, check each against compliance rules Bulk processing -- Any repetitive task that processes items individually Interaction Patterns Upload and Process Upload a file (CSV, XLSX) with upload-and-run-rows Each row is automatically created and triggered Poll get-row-result or get-all-row-results for completion Manual Row Management Add rows individually with add-row or AddDashboardRow Trigger processing with trigger-row or TriggerWorkflowForRow Update row values with update-row or UpdateDashboardRow Delete rows with delete-rows or DeleteDashboardRows Callback-Based Processing The HTTP API supports callback URLs. When provided, Ema sends the processing result to your callback URL upon completion instead of requiring polling. curl -X POST .../upload-and-run-rows \ -H "Authorization: Bearer <token>" \ -F "file=@data.xlsx" \ -F "callback_url=https://your-server.com/webhook/dashboard-result" Related Dashboard Data Model -- Row, column, and schema structures Dashboard HTTP API -- REST endpoints Dashboard RPC Calls -- gRPC-Web endpoints Workflow Overview -- How workflows process dashboard rows

================================================================================
# Dashboard RPC Calls
URL: https://builder.ema.ai/api-reference/dashboard/rpc-calls
================================================================================

Dashboard RPC Calls This page documents the gRPC-Web endpoints for dashboard operations. These endpoints provide the same functionality as the HTTP API but use the gRPC-Web protocol. For instructions on encoding and decoding gRPC-Web requests, see Handling gRPC-Web Requests. AddDashboardRow Add a single row to a dashboard. PropertyValueURL/workflows.v1.DashboardsService/AddDashboardRowHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardcolumn_valuesmap<string, ColumnValue>YesInput column values Response FieldTypeDescriptionrow_idstringUUID of the created row UpdateDashboardRow Update column values in an existing row. PropertyValueURL/workflows.v1.DashboardsService/UpdateDashboardRowHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptionrow_idstringYesUUID of the rowdashboard_idstringYesUUID of the dashboardcolumn_valuesmap<string, ColumnValue>YesUpdated column values DeleteDashboardRows Delete one or more rows from a dashboard. PropertyValueURL/workflows.v1.DashboardsService/DeleteDashboardRowsHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardrow_idsrepeated stringYesList of row UUIDs to delete GetDashboardRows Retrieve rows from a dashboard with optional filtering and pagination. PropertyValueURL/workflows.v1.DashboardsService/GetDashboardRowsHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardpage_sizeint32NoNumber of rows per pagepage_tokenstringNoPagination tokenfilterstringNoFilter expressionminimal_row_valuesboolNoReturn minimal column values Response FieldTypeDescriptionrowsrepeated DashboardRowDashboard rowsnext_page_tokenstringToken for the next pagetotal_countint32Total number of matching rows TriggerWorkflowForRow Trigger workflow execution for a specific row. PropertyValueURL/workflows.v1.DashboardsService/TriggerWorkflowForRowHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardrow_idstringYesUUID of the row to trigger Response FieldTypeDescriptionworkflow_run_idstringUUID of the workflow execution TriggerWorkflowForRemaining Trigger workflow execution for all rows that have not yet been processed. PropertyValueURL/workflows.v1.DashboardsService/TriggerWorkflowForRemainingHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboard Response FieldTypeDescriptiontriggered_row_idsarrayUUIDs of the rows that were triggered ContinueWorkflowForRow Submit a HITL response to resume a paused workflow for a row. PropertyValueURL/workflows.v1.DashboardsService/ContinueWorkflowForRowHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardrow_idstringYesUUID of the paused rowresponseobjectYesUser's response to the HITL prompt GetContinuationMessageForRow Retrieve the HITL continuation message for a paused row. PropertyValueURL/workflows.v1.DashboardsService/GetContinuationMessageForRowHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardrow_idstringYesUUID of the paused row Response Returns the HITL message that the workflow is waiting on, including message type (form, buttons, or text) and the message content. GetDashboardSchema Retrieve the schema (column definitions) for a dashboard. PropertyValueURL/workflows.v1.DashboardsService/GetDashboardSchemaHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboard Response FieldTypeDescriptioncolumnsrepeated ColumnDetailsColumn definitions for the dashboard DownloadDashboardRows Download dashboard rows as a file (XLSX or CSV). PropertyValueURL/workflows.v1.DashboardsService/DownloadDashboardRowsHTTP MethodPOSTProtocolgRPC-Web over HTTP Request FieldTypeRequiredDescriptiondashboard_idstringYesUUID of the dashboardformatstringNoFile format (xlsx or csv) Response Returns the dashboard data as a downloadable file. Related Dashboard Overview -- Concepts and architecture Dashboard Data Model -- Data structures Dashboard HTTP API -- REST endpoints Handling gRPC-Web Requests -- gRPC-Web encoding guide

================================================================================
# Document Generation API
URL: https://builder.ema.ai/api-reference/document-generation/api
================================================================================

Document Generation API This page documents the REST API endpoints for creating, retrieving, regenerating, and updating documents produced by AI Employees. All endpoints are prefixed with /api/document-generation/{ai_employee_id}/. Create Document Submit a document generation request. PropertyValueURL/api/document-generation/{ai_employee_id}/documentsHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionpersona_idstringYesUUID of the AI EmployeeinputobjectYesInput data for document generationoptionsobjectNoGeneration options (format, template, etc.) Example curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "persona_id": "<persona-uuid>", "input": { "topic": "Q4 2025 Sales Summary", "data_source": "salesforce", "date_range": "2025-10-01 to 2025-12-31" } }' Response FieldTypeDescriptiondocument_idstringUUID of the created documentstatusstringInitial status (TRIGGERED) Retrieve Document Retrieve the current status and content of a document. Use this endpoint to poll for completion. PropertyValueURL/api/document-generation/{ai_employee_id}/documents/retrieveHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptiondocument_idstringYesUUID of the document Example curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/retrieve \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "document_id": "<document-uuid>" }' Response FieldTypeDescriptiondocument_idstringUUID of the documentstatusstringCurrent status (TRIGGERED, PROCESSING, COMPLETED, FAILED)contentstringGenerated document content (when COMPLETED)show_workarrayList of ShowWorkEntry objects with processing detailserrorstringError message (when FAILED) Polling Pattern # Poll every 5 seconds until status is COMPLETED or FAILED while true; do RESPONSE=$(curl -s -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/retrieve \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{"document_id": "<document-uuid>"}') STATUS=$(echo $RESPONSE | jq -r '.status') if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then echo $RESPONSE | jq . break fi echo "Status: $STATUS. Waiting..." sleep 5 done Regenerate Document (Preview) Regenerate a document without replacing the original. This creates a preview that can be reviewed before finalizing. PropertyValueURL/api/document-generation/{ai_employee_id}/documents/regenerateHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptiondocument_idstringYesUUID of the original documentinputobjectNoUpdated input data (overrides original)optionsobjectNoUpdated generation options Example curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/regenerate \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "document_id": "<document-uuid>", "input": { "topic": "Q4 2025 Sales Summary - Revised", "include_forecast": true } }' Response FieldTypeDescriptionpreview_document_idstringUUID of the preview documentstatusstringStatus of the regeneration Update Document Finalize changes to a document (e.g., after reviewing a preview). PropertyValueURL/api/document-generation/{ai_employee_id}/documents/updateHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptiondocument_idstringYesUUID of the document to updatecontentstringNoUpdated contentmetadataobjectNoUpdated metadata Example curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/update \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "document_id": "<document-uuid>", "content": "Updated document content here..." }' Document Status Values StatusDescriptionTRIGGEREDRequest accepted, queued for processingPROCESSINGAI Employee is generating the documentCOMPLETEDDocument generated successfullyFAILEDGeneration failed (check error field for details) Related Document Generation Overview -- Concepts and lifecycle AI Employee API -- AI Employee management Miscellaneous APIs -- File upload and pre-signed URL endpoints

================================================================================
# Document Generation Overview
URL: https://builder.ema.ai/api-reference/document-generation/overview
================================================================================

Document Generation Overview Document Generation enables AI Employees to produce documents asynchronously. Unlike chat (real-time) or dashboard (batch processing), document generation follows an async lifecycle where a request is submitted, processed in the background, and the result is retrieved when ready. Async Lifecycle Document generation follows a state machine with four statuses: TRIGGERED → PROCESSING → COMPLETED → FAILED StatusDescriptionTRIGGEREDDocument generation request has been acceptedPROCESSINGThe AI Employee is actively generating the documentCOMPLETEDThe document has been generated successfullyFAILEDDocument generation encountered an error Workflow Create: Submit a document generation request with input data Poll: Retrieve the document status periodically until COMPLETED or FAILED Use: Access the generated document content from the response Iterate: Optionally regenerate or update the document Use Cases Report generation -- Generate summary reports from data Email drafting -- Create personalized email content Contract generation -- Produce documents from templates and data Content creation -- Generate marketing copy, documentation, etc. Data extraction -- Extract structured information into document form Trigger Type Document generation AI Employees use PersonaTriggerType.DOCUMENT_GENERATION (value 5). This trigger type determines the AI Employee's interaction pattern and the available API endpoints. Preview and Iteration The API supports a regeneration flow for iterating on documents: Call Regenerate (preview) to generate a new version without replacing the original Review the preview Call Update to finalize changes This allows safe iteration without losing the previous version. Related Document Generation API -- API endpoints AI Employee Overview -- AI Employee architecture Workflow Overview -- How workflows process document requests

================================================================================
# API Getting Started
URL: https://builder.ema.ai/api-reference/getting-started
================================================================================

API Getting Started This guide walks you through the essential steps to begin using Ema's Builder Platform APIs: authenticating, creating a tenant, setting up an AI Employee, interacting via chat, and running dashboard workflows. Ema provides two API paths: a REST (HTTP/JSON) quickstart for the most common operations, and a gRPC-Web path for advanced or lower-level endpoints. This guide covers the REST path first, with links to gRPC-Web alternatives where applicable. Prerequisites Access to an Ema instance (e.g., https://your-instance.ema.co) A valid API key (generated from the Ema UI or via the GenerateApiKey gRPC-Web endpoint) curl or an HTTP client for making API requests Step 1: Generate an API Key Create an API key by calling the GenerateApiKey gRPC-Web endpoint. This key is tied to a specific user and tenant. Note: If this is your first time setting up the API and you do not yet have an access token, see Access Token for Root Tenant API Key for how to obtain one from your browser session. PropertyValueURL/auth.v1.AuthService/GenerateApiKeyHTTP MethodPOSTProtocolgRPC-Web over HTTP Request Fields: FieldTypeRequiredDescriptionemailstringYesEmail address of the user to create the key for For detailed instructions on encoding and sending gRPC-Web requests, see Handling gRPC-Web Requests. Response Fields: FieldTypeDescriptionapi_keystringThe generated API key Step 2: Generate an Access Token Exchange your API key for a short-lived access token (JWT). Pass your API key in the x-ema-api-key header. PropertyValueURL/api/auth/generate_access_tokenHTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionx-ema-api-keystringYesYour Ema API keyContent-TypestringYesapplication/json curl -X POST https://your-instance.ema.co/api/auth/generate_access_token \ -H "x-ema-api-key: your-api-key" \ -H "Content-Type: application/json" Response: { "access_token": "eyJhbGciOiJSUzI1NiIs...", "token_type": "bearer" } Global API key tokens expire after 24 hours. Chatbot API key tokens expire after 30 minutes. Use the access token in the Authorization header for all subsequent requests: Authorization: Bearer <access_token> Legacy endpoint: The older /api/generate_access_token endpoint (which accepts the API key in the JSON body) is still supported but deprecated. Use /api/auth/generate_access_token with the x-ema-api-key header for all new integrations. See Authentication for complete details on token types and lifecycle. Step 3: Create a Tenant Create a child tenant under your organization. Tenants form a hierarchy where child tenants inherit configurations from their parent. REST Endpoint PropertyValueURL/api/tenantHTTP MethodPOSTProtocolREST (HTTP/JSON) curl -X POST https://your-instance.ema.co/api/tenant \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "tenant_name": "Acme Corp", "parent_id": "<parent-tenant-uuid>", "admin_email": "admin@acme.com" }' Request Fields: FieldTypeRequiredDescriptiontenant_namestringYesDisplay name for the tenantparent_idstringYesUUID of the parent tenantadmin_emailstringYesEmail of the tenant admin gRPC-Web Alternative The tenant creation endpoint is also available via gRPC-Web at /tenant.v1.TenantService/CreateTenant. See Tenant Management for full gRPC-Web details and additional tenant operations. Step 4: Create an AI Employee Create an AI Employee using the REST API. PropertyValueURL/api/ai_employee/create_ai_employeeHTTP MethodPOSTProtocolREST (HTTP/JSON) curl -X POST https://your-instance.ema.co/api/ai_employee/create_ai_employee \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Support Agent", "description": "Handles customer support queries", "category": "CUSTOMER_SUPPORT", "behavior_type": "CHAT", "icon": "support-icon", "proto_config": { "widgets": [], "display_settings": {}, "project_settings": {} } }' Legacy endpoint: The older /api/personas/create_persona endpoint is still supported. The new /api/ai_employee/create_ai_employee endpoint is preferred for all new integrations. See AI Employee API for full endpoint details including update, delete, and list operations. Step 5: Start a Chat Conversation Create a conversation and send messages to your AI Employee. Create a Conversation PropertyValueURL/api/{tenantId}/chat/HTTP MethodPOSTProtocolREST (HTTP/JSON) curl -X POST https://your-instance.ema.co/api/<tenant_id>/chat/ \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "persona_id": "<persona-uuid>" }' Note: The chat endpoint now includes the tenant ID in the path (/api/{tenantId}/chat/). The older /api/chat/ endpoint without the tenant prefix is still supported for backward compatibility. Send a Message curl -X POST https://your-instance.ema.co/api/<tenant_id>/chat/<conversation_id> \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "message": "How do I reset my password?" }' See Chat API for the full conversation lifecycle, including asynchronous messaging and feedback collection. Step 6: Interact with a Dashboard Upload data rows and trigger workflow processing through the dashboard HTTP API. Upload and Run Rows curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/upload-and-run-rows \ -H "Authorization: Bearer <access_token>" \ -F "file=@data.xlsx" Get Row Results curl -X GET "https://your-instance.ema.co/api/personas/<persona_id>/dashboard/get-row-result?row_id=<row_id>" \ -H "Authorization: Bearer <access_token>" See Dashboard HTTP API and Dashboard RPC Calls for all dashboard operations. Quickstart Summary The table below summarizes the REST endpoints used in this guide: StepEndpointMethodGenerate Access Token/api/auth/generate_access_tokenPOSTCreate Tenant/api/tenantPOSTCreate AI Employee/api/ai_employee/create_ai_employeePOSTCreate Chat Conversation/api/{tenantId}/chat/POSTSend Chat Message/api/{tenantId}/chat/{conversationId}POSTUpload Dashboard Rows/api/personas/{persona_id}/dashboard/upload-and-run-rowsPOSTGet Dashboard Row Result/api/personas/{persona_id}/dashboard/get-row-resultGET Next Steps Authentication -- Detailed token lifecycle and key types AI Employee Overview -- Understand AI Employee architecture Workflow Overview -- Learn how workflows power AI Employee behavior Handling gRPC-Web Requests -- Guide for making gRPC-Web calls

================================================================================
# Debug Worklogs API
URL: https://builder.ema.ai/api-reference/misc/debug-worklogs
================================================================================

Debug Worklogs API The Debug Worklogs API provides detailed debug log data for workflow runs, including AI Employee configuration snapshots, workflow definitions, and per-action show-work logs. Access is filtered based on the requesting user's permission level. GetWorkflowLevelDebugLog Retrieve comprehensive debug data for an entire workflow run. PropertyValueURL/persona.v1.DebugLogService/GetWorkflowLevelDebugLogHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionworkflow_run_idstringYesUUID of the workflow run to debug Response FieldTypeDescriptionpersona_configPersonaConfigForShowWorkAI Employee configuration snapshot (Debug users only)action_typesmap<string, ActionType>Map of action names to their type snapshotsworkflow_definitionWorkflowDefWorkflow definition snapshot at time of execution (Debug users only)show_work_logsmap<string, ShowWorkLog>Map of action instance names to their show-work logsis_ema_userboolWhether the requester is an Ema user Example Response { "persona_config": { "id": "persona-uuid", "name": "Support Agent", "description": "Customer support persona", "status": "ACTIVE", "version": 1, "widgets": [], "display_settings": {}, "project_settings": {} }, "action_types": { "search@v2": { "type_name": {}, "display_name": "Knowledge Search", "description": "Searches the knowledge base" } }, "workflow_definition": { "workflow_name": {}, "actions": [], "display_name": "Support Workflow" }, "show_work_logs": { "search_step": { "action_title": "Knowledge Search", "llm_call_count": 2, "llm_cost_usd": 0.05, "action_run_status": "ACTION_RUN_STATUS_SUCCESS" } }, "is_ema_user": false } Permission Levels The API filters response data based on the requesting user's access level: User TypeSeesDebug access userEverythingStandard userAction names and step names only Data Structures ShowWorkLog Per-action debug information for a workflow run. FieldTypeDescriptionmessagesrepeated StructuredLogMessageLog messages with substitutable variablesllm_call_countint32Number of LLM calls madeaction_titlestringDisplay title of the actionllm_callsrepeated LlmCallEntryDetailed LLM call entriesllm_cost_usdfloatTotal LLM cost in USDllm_latency_msfloatTotal LLM latency in millisecondsinputsShowWorkInputsDetailed input informationoutputsShowWorkOutputsDetailed output informationhitl_roundsrepeated HitlRoundHuman-in-the-loop interaction roundswork_logsrepeated StepSteps executed in the actionworkflow_run_idstringUUID of the workflow runaction_run_statusActionRunStatusStatus of the action runembedded_persona_run_infoEmbeddedPersonaRunInfoInfo about embedded AI Employee runs ActionRunStatus Enum ValueIntegerDescriptionACTION_RUN_STATUS_UNSPECIFIED0Status not specifiedACTION_RUN_STATUS_SUCCESS1Action ran successfullyACTION_RUN_STATUS_ERRORED2Action encountered an errorACTION_RUN_STATUS_WARNING3Action completed with warningsACTION_RUN_STATUS_NOT_RUN4Action was not executedACTION_RUN_STATUS_PAUSED5Action execution was paused StructuredLogMessage FieldTypeDescriptionmessage_templatestringTemplate with {placeholder} variablessubstituted_fieldsmap<string, string>Placeholder-to-value mappingsheadingstringOptional headinglog_levelLogLevelMessage severity levelerror_infoErrorInfoError details (if applicable) LlmCallEntry FieldTypeDescriptionmetricsResponseMetricsLLM response metricsfusion_usedboolWhether Fusion selected a modelsuccessboolWhether the LLM call succeedederror_messagestringError message if failedtimestamp_msint64Timestamp in millisecondsllm_cost_final_choicefloatCost of the final model choice in USDpromptPromptDataPrompt data (super-admin only)headingstringDisplay heading for the call PromptData FieldTypeDescriptionsystem_promptstringSystem prompt textuser_promptstringUser prompt textresponsestringLLM response text HitlRound FieldTypeDescriptionmessage_typeMessageTypeType of HITL message (Form, Button, TextField, Feedback)hitl_requestoneofMessage shown to the humanhitl_responseoneofResponse from the humanoutcomestringOutcome status of the round ShowWorkInputs / ShowWorkOutputs FieldTypeDescriptionentriesrepeated InputEntry/OutputEntryList of input/output entries InputEntry FieldTypeDescriptionnamestringParameter namevalueValueThe actual valuetypeResolvedTypeData typesource_agent_namestringName of the source action OutputEntry FieldTypeDescriptionnamestringParameter namevalueValueThe actual valuetypeResolvedTypeData typepublished_as_chat_responseboolWhether published to the end user ErrorInfo FieldTypeDescriptionnamestringError nameinternal_messagestringInternal error message (not shown to end users)external_messagestringError message shown to end users Step FieldTypeDescriptionnamestringStep namemessagesrepeated StructuredLogMessageLog messages for the stepllm_callsrepeated LlmCallEntryLLM calls in the step Error Responses HTTP StatusgRPC CodeDescription400INVALID_ARGUMENTworkflow_run_id is required or invalid UUID403PERMISSION_DENIEDUser lacks permission for this AI Employee404NOT_FOUNDWorkflow run not found or tenant mismatch500INTERNALInternal server error Related Workflow Overview -- Workflow concepts Action Data Model -- ActionType structure Handling gRPC-Web Requests -- gRPC-Web encoding guide

================================================================================
# Handling gRPC-Web Requests
URL: https://builder.ema.ai/api-reference/misc/grpc-web
================================================================================

Handling gRPC-Web Requests Some Ema APIs are not accessible via standard REST and must be called using gRPC-Web over HTTP. This guide provides step-by-step instructions for making gRPC-Web requests using curl and command-line tools. Prerequisites protoc (Protocol Buffer compiler) python3 curl Access to the .proto files defining the service (e.g., service/auth/v1/auth.proto) Step 1: Encode the Request Message Use protoc to encode your request message into protobuf binary format. # Option A: Encode from inline text cat <<EOF | protoc -I=. --encode=auth.v1.GenerateApiKeyRequest \ service/auth/v1/auth.proto > request.bin email: "user@example.com" EOF # Option B: Encode from an input file protoc -I=. --encode=auth.v1.GenerateApiKeyRequest \ service/auth/v1/auth.proto < input.txt > request.bin Replace auth.v1.GenerateApiKeyRequest and the proto file path with the appropriate message type and file for your target endpoint. Step 2: Frame the Request gRPC-Web requires a 5-byte frame header before the protobuf payload: +---------------+-----------------------------------+ | 1 byte flag | 4 byte payload length (big endian)| +---------------+-----------------------------------+ | <protobuf-encoded message bytes> | +---------------------------------------------------+ Flag byte: 0x00 for uncompressed messages Length bytes: 4-byte big-endian integer representing the payload size Use this Python one-liner to add the frame header: python3 -c 'import sys,struct; data=sys.stdin.buffer.read(); \ sys.stdout.buffer.write(b"\x00"+struct.pack(">I",len(data))+data)' \ < request.bin > framed_request.bin Example: If the protobuf payload is 18 bytes, the frame header is 00 00 00 00 12 (where 0x12 = 18 in decimal). Step 3: Send the Request Make the HTTP request with the required gRPC-Web headers: curl -X POST https://your-instance.ema.co/<service-path> \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/grpc-web+proto" \ -H "x-grpc-web: 1" \ -H "x-user-agent: grpc-web-javascript/0.1" \ --data-binary @framed_request.bin -v \ --output response.bin Required Headers HeaderValueDescriptionAuthorizationBearer <token>Authentication tokenContent-Typeapplication/grpc-web+protogRPC-Web content typex-grpc-web1gRPC-Web protocol indicator Optional Headers HeaderValueDescriptionx-user-agentgrpc-web-javascript/0.1Client user agent identifier Step 4: Strip the Response Frame The response contains both message frames and trailer frames. Use this Python script to extract the protobuf message: #!/usr/bin/env python3 import struct import sys """ Usage: python strip_grpc_web.py response.bin > clean_payload.bin - response.bin: full gRPC-Web response captured from curl (--output file) - clean_payload.bin: the extracted raw protobuf message body """ def extract_messages(filename: str): with open(filename, "rb") as f: data = f.read() idx = 0 messages = [] while idx < len(data): if idx + 5 > len(data): raise ValueError("Truncated frame header") # Read gRPC-Web frame header flag = data[idx] length = struct.unpack(">I", data[idx + 1 : idx + 5])[0] idx += 5 if idx + length > len(data): raise ValueError("Truncated frame payload") payload = data[idx : idx + length] idx += length # Flag 0x80 = trailers frame (not protobuf) if flag == 0x80: try: print(payload.decode("utf-8"), file=sys.stderr) except Exception: print(f"[Trailers: {payload!r}]", file=sys.stderr) continue elif flag == 0x00: messages.append(payload) else: print(f"Unknown frame flag {flag:#x} (skipping)", file=sys.stderr) return messages def main(): if len(sys.argv) != 2: print("Usage: python strip_grpc_web.py response.bin > clean_payload.bin") sys.exit(1) messages = extract_messages(sys.argv[1]) if not messages: print("No proto messages found!", file=sys.stderr) sys.exit(2) # Output the first proto message to stdout sys.stdout.buffer.write(messages[0]) if __name__ == "__main__": main() Save this script as strip_grpc_web.py and run: python3 strip_grpc_web.py response.bin > clean_payload.bin The trailer frames (printed to stderr) contain gRPC status information such as grpc-status and grpc-message. Step 5: Decode the Response Decode the clean protobuf payload: protoc -I=. --decode=auth.v1.GenerateApiKeyResponse \ service/auth/v1/auth.proto < clean_payload.bin Replace the message type and proto file path with the appropriate response type for your endpoint. Frame Format Reference Flag ValueMeaning0x00Uncompressed message frame0x01Compressed message frame0x80Trailers frame (gRPC status) Complete Example Generating an API key end-to-end: # 1. Encode cat <<EOF | protoc -I=. --encode=auth.v1.GenerateApiKeyRequest \ service/auth/v1/auth.proto > request.bin email: "admin@company.com" EOF # 2. Frame python3 -c 'import sys,struct; data=sys.stdin.buffer.read(); \ sys.stdout.buffer.write(b"\x00"+struct.pack(">I",len(data))+data)' \ < request.bin > framed_request.bin # 3. Send curl -X POST https://your-instance.ema.co/auth.v1.AuthService/GenerateApiKey \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/grpc-web+proto" \ -H "x-grpc-web: 1" \ --data-binary @framed_request.bin \ --output response.bin # 4. Strip python3 strip_grpc_web.py response.bin > clean_payload.bin # 5. Decode protoc -I=. --decode=auth.v1.GenerateApiKeyResponse \ service/auth/v1/auth.proto < clean_payload.bin gRPC-Web Endpoints in Ema The following services use gRPC-Web: ServicePath PrefixAuthentication/auth.v1.AuthService/Tenant Management/tenant.v1.TenantService/Action Manager/workflows.v1.ActionManager/Workflow Manager/workflows.v1.WorkflowManager/Dashboard Service/workflows.v1.DashboardsService/Debug Log Service/persona.v1.DebugLogService/ Related Authentication -- API key and token generation Access Token for Root Tenant API Key -- First-time setup Workflow API -- Workflow gRPC-Web endpoints Dashboard RPC Calls -- Dashboard gRPC-Web endpoints

================================================================================
# Miscellaneous APIs
URL: https://builder.ema.ai/api-reference/misc/misc-apis
================================================================================

Miscellaneous APIs This page documents utility API endpoints for file operations. Upload File Upload a file to the Ema platform. The file is processed asynchronously. PropertyValueURL/api/personas/{persona_id}/upload HTTP MethodPOSTProtocolREST (multipart/form-data) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesmultipart/form-data Path Parameters ParameterTypeDescriptionpersona_idstringUUID of the AI Employee Form Data FieldTypeRequiredDescriptionfilefileYesThe file to upload Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/upload \ -H "Authorization: Bearer <access_token>" \ -F "file=@document.pdf" Response FieldTypeDescriptionfile_idstringUUID of the uploaded filestatusstringUpload status Processing Uploaded files are processed asynchronously. The processing pipeline may include: File format detection and validation Text extraction (for PDFs, documents, etc.) Indexing for search and retrieval Thumbnail generation (for images) Get Pre-Signed URL Generate a pre-signed URL for direct file download from cloud storage. PropertyValueURL/api/personas/{persona_id}/get_presigned_url HTTP MethodPOSTProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/json Request Body FieldTypeRequiredDescriptionfile_idstringYesUUID of the file Example curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/get_presigned_url \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "file_id": "<file-uuid>" }' Response FieldTypeDescriptionpresigned_urlstringTime-limited URL for file downloadexpires_atstringISO 8601 expiration timestamp The pre-signed URL grants temporary access to the file without requiring authentication. URLs typically expire after a short period (e.g., 15 minutes). Related Dashboard HTTP API -- Dashboard file upload (upload-and-run-rows) Document Generation API -- Document creation Authentication -- Token management

================================================================================
# Access Token for Root Tenant API Key
URL: https://builder.ema.ai/api-reference/misc/root-tenant-token
================================================================================

Access Token for Root Tenant API Key To create an API key for the root tenant, you must provide an access token in the Authorization header of the GenerateApiKey gRPC-Web request. However, if this is your first time setting up the API, you will not have an access token yet. Solution: Reuse the Browser Session Token For this initial request only, you can reuse the access token that is automatically set in your browser when you log in to your Ema instance. Method 1: Network Tab Log in to your Ema instance in a web browser Open the browser's Developer Tools (F12 or Cmd+Option+I) Go to the Network tab Perform any action in the Ema UI that triggers an API request Click on the request in the Network tab Find the Authorization header in the request headers Copy the token value (everything after Bearer ) Method 2: Application Tab Log in to your Ema instance in a web browser Open the browser's Developer Tools (F12 or Cmd+Option+I) Go to the Application tab Look for the access token in the stored cookies or local storage Use this token in the Authorization header when calling GenerateApiKey: curl -X POST https://your-instance.ema.co/auth.v1.AuthService/GenerateApiKey \ -H "Authorization: Bearer <browser-session-token>" \ -H "Content-Type: application/grpc-web+proto" \ -H "x-grpc-web: 1" \ --data-binary @framed_request.bin \ --output response.bin Once you have generated your API key, use it to call GenerateAccessToken for all subsequent operations. You will no longer need the browser session token. Related Authentication -- Full authentication flow Handling gRPC-Web Requests -- gRPC-Web encoding guide Getting Started -- Quickstart guide

================================================================================
# Tenant Management
URL: https://builder.ema.ai/api-reference/tenant-management
================================================================================

Tenant Management Tenants in Ema form a hierarchy. A root tenant sits at the top, and child tenants inherit configurations from their parent. This page covers the APIs for creating, querying, and managing tenants. Tenant Hierarchy Root Tenant ├── Child Tenant A │ ├── Grandchild Tenant A1 │ └── Grandchild Tenant A2 └── Child Tenant B Each tenant has its own set of AI Employees, workflows, dashboards, and users. Child tenants can inherit templates and configurations from their parent. CreateTenant Create a new child tenant under an existing parent tenant. PropertyValueURL/tenant.v1.TenantService/CreateTenantHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptiontenant_namestringYesDisplay name for the new tenantparent_idstringYesUUID of the parent tenantadmin_emailstringYesEmail address of the tenant admin Response FieldTypeDescriptiontenant_idstringUUID of the newly created tenant CreateTenantWithApiKey Create a new child tenant and simultaneously generate an API key for it. PropertyValueURL/tenant.v1.TenantService/CreateTenantWithApiKeyHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptiontenant_namestringYesDisplay name for the new tenantparent_idstringYesUUID of the parent tenantadmin_emailstringYesEmail address of the tenant admin Response FieldTypeDescriptiontenant_idstringUUID of the newly created tenantapi_keystringAPI key for the new tenant GetTenant Retrieve details about a specific tenant. PropertyValueURL/tenant.v1.TenantService/GetTenantHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptiontenant_idstringYesUUID of the tenant Response FieldTypeDescriptiontenant_idstringUUID of the tenanttenant_namestringDisplay name of the tenantparent_idstringUUID of the parent tenantadmin_emailstringEmail of the tenant admin GetUsers Retrieve the list of users associated with a tenant. PropertyValueURL/api/get_users HTTP MethodGETProtocolREST (HTTP/JSON) Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer token Response Returns a list of user objects associated with the authenticated tenant. FieldTypeDescriptionusersarrayList of user objectsusers[].idstringUUID of the userusers[].emailstringEmail address of the userusers[].rolestringRole of the user in the tenant Related Getting Started -- Quickstart guide Authentication -- API key and token management

================================================================================
# Triggering AI Employees
URL: https://builder.ema.ai/api-reference/triggers
================================================================================

Triggering AI Employees Ema's APIs allow you to invoke AI Employees programmatically, making it straightforward to set up recurring (scheduled) triggers and event-based triggers from external platforms. This guide covers common patterns for both approaches. Overview Any system that can make HTTP requests can trigger an Ema AI Employee. The two most common patterns are: Recurring triggers -- Run an AI Employee on a schedule (e.g., every hour, daily, weekly). Event-based triggers -- Run an AI Employee in response to an external event (e.g., a new lead is created in Salesforce, a support ticket is opened in Zendesk). Both patterns use the same Ema APIs under the hood. The difference is in what initiates the API call. API Endpoints for Triggering Depending on your AI Employee type, use the appropriate endpoint: AI Employee TypeEndpointMethodChat/api/{tenantId}/chat/ (create conversation) then /api/{tenantId}/chat/{conversationId} (send message)POSTDashboard/api/personas/{persona_id}/dashboard/upload-and-run-rowsPOST All requests require a valid access token. See Authentication for how to generate and refresh tokens. Recurring Triggers Use a scheduler in your platform of choice to call Ema's API at a fixed interval. Option 1: Cron-Based Schedulers If you have access to a server or cloud environment, use a cron job or cloud scheduler to make API calls on a schedule. Linux/macOS cron -- Add a crontab entry that runs a curl command to trigger the AI Employee at the desired interval. Google Cloud Scheduler -- Create a job that sends an HTTP POST to Ema's API endpoint on a cron schedule. Configure the Authorization header with your Ema access token. AWS EventBridge Scheduler -- Create a schedule rule that invokes a Lambda function (or directly targets an HTTP endpoint via API Destination) to call Ema's API. Azure Logic Apps -- Use the Recurrence trigger to run a workflow on a schedule, then add an HTTP action to call Ema's API. Option 2: Workflow Automation Platforms No-code platforms can schedule API calls without any infrastructure: Zapier -- Use the "Schedule by Zapier" trigger (every hour, day, or week), then add a Webhooks action to POST to Ema's API. Make (Integromat) -- Use the "Schedule" module as the trigger, followed by an HTTP module to call Ema's API. n8n -- Use the Cron node to trigger a workflow on a schedule, then use the HTTP Request node to call Ema's API. Power Automate -- Use the "Recurrence" trigger to run a flow on a schedule, then add an HTTP action to invoke Ema. Example: Recurring Chat Trigger This example creates a new conversation and sends a message to an AI Employee on a schedule: # Step 1: Generate an access token ACCESS_TOKEN=$(curl -s -X POST https://your-instance.ema.co/api/auth/generate_access_token \ -H "x-ema-api-key: your-api-key" \ -H "Content-Type: application/json" | jq -r '.access_token') # Step 2: Create a conversation CONVERSATION_ID=$(curl -s -X POST https://your-instance.ema.co/api/<tenant_id>/chat/ \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"persona_id": "<persona-uuid>"}' | jq -r '.conversation_id') # Step 3: Send a message to trigger the AI Employee curl -X POST https://your-instance.ema.co/api/<tenant_id>/chat/$CONVERSATION_ID \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"message": "Generate the daily sales summary report."}' Event-Based Triggers Event-based triggers invoke an AI Employee when something happens in an external system -- a new record is created, a status changes, or a threshold is crossed. Pattern: Webhook to Ema Most platforms support outbound webhooks or event notifications. The general pattern is: Configure the external platform to fire a webhook (or event notification) when the trigger condition is met. Point the webhook at a lightweight middleware (e.g., a serverless function, Zapier, or Make) that transforms the event payload into an Ema API call. The middleware authenticates with Ema and sends the relevant data to the AI Employee. Example Scenarios External EventPlatformHow to ConnectNew lead createdSalesforceUse Salesforce Flow or Outbound Messages to call a webhook that triggers an Ema AI Employee to enrich and qualify the lead.Support ticket openedZendesk / FreshdeskConfigure a webhook trigger on ticket creation that sends ticket details to Ema for auto-triage or draft response.New hire added to HRISWorkday / BambooHRUse the platform's event notification or a polling integration to trigger Ema's onboarding AI Employee.Deal stage changedHubSpotUse HubSpot Workflows to trigger a webhook when a deal moves to a specific stage, invoking Ema to generate next-step recommendations.Form submissionTypeform / Google FormsUse native webhook integrations or Zapier to forward submission data to Ema for processing.Document uploadedGoogle Drive / SharePointUse Google Drive push notifications or SharePoint webhooks to trigger Ema's document analysis AI Employee.Scheduled report readySnowflake / BigQueryUse a cloud function triggered by query completion to send results to Ema for summarization. Example: Salesforce Lead to Ema Using Zapier as middleware: Trigger: "New Record" in Salesforce (object: Lead). Action 1: Webhooks by Zapier -- POST to /api/auth/generate_access_token to get a token. Action 2: Webhooks by Zapier -- POST to /api/{tenantId}/chat/ to create a conversation. Action 3: Webhooks by Zapier -- POST to /api/{tenantId}/chat/{conversationId} with the lead details as the message body. The same pattern works with Make, n8n, Power Automate, or a custom serverless function (AWS Lambda, Google Cloud Functions, Azure Functions). Best Practices Token management: Access tokens expire (24 hours for global API keys, 30 minutes for chatbot keys). Build in token refresh logic, especially for recurring triggers. Idempotency: For event-based triggers, consider deduplication. Some platforms may retry webhook delivery, which could invoke the AI Employee multiple times for the same event. Error handling: Log API responses from Ema. If a trigger fails, implement retry logic with exponential backoff. Payload mapping: When passing external event data to Ema, format the message clearly so the AI Employee can parse and act on it. Include relevant record IDs, names, and context. Security: Store API keys securely (use secrets managers, not plain text). Restrict webhook endpoints with IP allowlisting or signature verification where possible. Related Authentication -- Token generation and lifecycle Chat API -- Full chat endpoint reference Dashboard HTTP API -- Dashboard trigger endpoints Getting Started -- API quickstart guide

================================================================================
# Action Data Model
URL: https://builder.ema.ai/api-reference/workflows/action-data-model
================================================================================

Action Data Model This page defines the protobuf data structures for action types, their inputs, outputs, and the Value system used across the workflow engine. ActionType The definition of a registered action type. FieldTypeDescriptiontype_nameRegisteredActionNameUnique identifier for the action typelifecycleActionLifecycleStatusLifecycle status of the actionis_asynchronousboolWhether the action may not immediately returnuses_toolboolWhether the action uses an external toolhuman_interaction_configHumanInteractionConfigHITL settings for external actionsinputsInputDefMapMap of input parameter definitionsoutputsOutputDefMapMap of output parameter definitionsdisplay_namestringUser-friendly display namedescriptionstringDescription of the action's behaviorcategoryActionCategoryCategory classificationtype_parametersTypeParamsType parameters for generic actionsdependenciesrepeated RegisteredActionNamePrerequisite actionsexternal_action_infoExternalActionInfoExternal action metadatasupported_enumsrepeated ResolvedTypeEnum types supported by the actionis_prerequisite_actionboolWhether this is a prerequisite actiondocumentationDocumentationDocumentation for the action ActionCategory Enum ValueIntegerDescriptionUNSPECIFIED0Default/unspecifiedTRIGGER1Entry point into a workflowGENERATION2LLM-based data generationPUBLISH_RESPONSE3Final step / workflow terminationRESOURCES4Data resource management (read/write)EXTERNAL_ACTION5External API integrationsANALYTICS6Data analysis and reasoningEVALUATION7Response evaluation and formattingFINANCE8Finance actionsHEALTHCARE9Healthcare actionsTECHNOLOGY10Technology actionsLEGAL11Legal actionsSALES12Sales actionsFREQUENTLY_USED13Commonly used actions (highlighted)AGENT_ASSIST14Agent assist actionsPERSONA_BACKED15Actions backed by a personaCUSTOMER_SUPPORT16Customer support actionsSECURITY17Security actionsFINANCE_AND_ACCOUNTING18Finance and accounting actionsPRODUCT_DEVELOPMENT19Product development actionsHUMAN_RESOURCES20Human resources actionsUTILITIES21General-purpose utility actionsAPP_NAVIGATION22Browser automation and web navigationINTERNAL_TOOL23Internal tool-calling agent actions Complete list of ActionCategory values from the proto definition. ActionLifecycleStatus Enum ValueIntegerDescriptionACTIVE0Action is activeDEPRECATED1Action is deprecatedEXPERIMENTAL2Action is experimental Complete list of ActionLifecycleStatus values. InputDef Definition of an action input parameter. FieldTypeDescriptionarg_typeArgumentTypeThe type of the input argumentdisplay_namestringUser-friendly namedescriptionstringDescription of the inputrequiredboolWhether the input is requireddefault_valueValueDefault value if not provided ArgumentType FieldTypeDescriptionstaticTypeReferenceA fixed type referencetype_parameter_refstringReference to a type parameter OutputDef Definition of an action output parameter. FieldTypeDescriptiontypeTypeReferenceThe data type of the outputdisplay_namestringUser-friendly namedescriptionstringDescription of the output InputDefMap / OutputDefMap FieldTypeDescriptioninputsmap<string, InputDef>Map of parameter name to InputDefoutputsmap<string, OutputDef>Map of parameter name to OutputDef WellKnownType Enum Primitive types supported by the workflow engine's type system. ValueIntegerDescriptionUNSPECIFIED0Default/unspecifiedSTRING1Text stringINT2Integer numberFLOAT3Floating-point numberBOOL4True/falseDOCUMENT5Document referenceDATASTORE_CONNECTION7Datastore connection configurationFUSION_LLM_CONFIG8Fusion LLM configurationSEARCH_RESULT9Search resultBOOST_TERM10Boost term for rerankingTEXT_WITH_SOURCES11Text with associated sourcesCHAT_MESSAGE12Chat message (deprecated, use CHAT_CONVERSATION)CHAT_CONVERSATION13Chat conversation or conversational contextSTRUCT14Untyped key-value dictionaryGLOSSARY_ITEM15Glossary item (term and definition)EXTRACTION_COLUMN16Extraction column in a tableRULESET17Rule setTAG_EXTRACTION_CONFIG18Tag extraction configurationDATA_PROTECTION_CONFIG19Data protection configurationCHART20Chart visualizationDATE21Date valueDATETIME22Date and time valueDOCUMENT_TEMPLATE23Document templateANY24Any type (untyped)THREAD25Ticketing threadJSON_MAPPER_CONFIG26JSON mapper configurationDOCUMENT_VERSION_ID27Document version identifierEMAIL_ACCOUNT_CONFIG28Email account configurationHUMAN_COLLABORATION_CONFIG29Human collaboration (HITL) configurationTOOL_CONFIG30Tool configuration for tool workflows Complete list of WellKnownType values from the proto definition. Note that value 6 is not assigned. Value The universal value type used throughout the workflow engine. A Value can hold any supported data type. FieldTypeDescriptionstring_valuestringString valueint_valueint64Integer valuefloat_valuedoubleFloating-point valuebool_valueboolBoolean valuejson_valuestringJSON string valuelist_valueListValueList of Valuesnull_valueNullValueNull Only one field is set at a time (oneof semantics). ListValue FieldTypeDescriptionvaluesrepeated ValueList of Value elements HumanInteractionConfig Configuration for human-in-the-loop interactions. FieldTypeDescriptionenabledboolWhether HITL is enabled for this actionmessage_typeMessageTypeType of message to present to the humantimeout_secondsint32Timeout before auto-proceeding ExternalActionInfo Metadata for actions provided by external integrations. FieldTypeDescriptionproviderActionProviderThe external action providerintegration_idstringIntegration identifieraction_idstringAction identifier within the integration ActionProvider Enum ValueIntegerDescriptionUNSPECIFIED0Default/unspecifiedEMA_BACKEND1Internal Ema backend serviceDATAINGEST2Data ingestion servicePARAGON3Paragon integrationWORKATO4Workato integrationWORKFLOW_ENGINE5Workflow engineCOMPOSIO_MCP6Composio via MCP (Model Context Protocol)EMA_PERSONA7Ema persona-backed actionCOMPOSIO_TOOL8Composio via native APIEMA_EXTERNAL_TOOL9Ema external tool (tool workflows)EMU10EMU connector Complete list of ActionProvider values from the proto definition. Related Workflow Overview -- Concepts and architecture Workflow Data Model -- Workflow-level structures Workflow API -- API endpoints

================================================================================
# Workflow Overview
URL: https://builder.ema.ai/api-reference/workflows/overview
================================================================================

Workflow Overview Workflows are the execution engine behind every AI Employee. A workflow is a directed acyclic graph (DAG) of actions, where each action performs a specific task and passes its outputs to downstream actions through input bindings. Core Concepts Workflow A workflow defines the logic an AI Employee follows when triggered. It consists of: Actions -- Individual processing steps (LLM calls, searches, API calls, etc.) Input Bindings -- Connections that route data from one action's outputs to another's inputs Workflow Inputs -- External data provided when the workflow is triggered Results / Named Results -- The final outputs produced by the workflow Actions An action is a single step in a workflow. Each action: Has a registered action type (e.g., search/v2, call_llm, external_action_caller) Declares typed inputs and outputs Can be synchronous or asynchronous May support human-in-the-loop (HITL) interaction Actions are organized into categories: CategoryDescriptionCOREBuilt-in actions (LLM calls, search, routing)INTEGRATIONExternal system connectorsTRANSFORMATIONData processing and formattingCONTROL_FLOWBranching, looping, and orchestration Input Bindings Input bindings define how data flows between actions. Each binding specifies: Source -- Where the data comes from (another action's output, workflow input, or a static value) Target -- Which input of which action receives the data Type -- The data type being transferred Binding types include: Binding TypeDescriptionACTION_OUTPUTOutput from a previous actionWORKFLOW_INPUTInput provided when the workflow startsSTATIC_VALUEA constant value defined in the workflowCONDITIONA conditional binding based on runtime evaluation Execution Flow The workflow is triggered (via chat message, dashboard row, or document request). Actions execute in topological order based on the DAG structure. Each action receives inputs from its bindings, processes them, and produces outputs. Outputs are routed to downstream actions through their input bindings. The final action(s) produce the workflow's results. [Trigger] → [Action A] → [Action B] → [Action C] → [Result] ↓ [Action D] ──────────────→ [Action E] Workflow Outputs Workflows support two output protocols: results (legacy) -- A map of result definitions. Used by existing workflows. namedResults (preferred) -- A map of named output definitions with richer metadata. Recommended for all new workflows. The namedResultsEnabled flag determines which protocol is active. The two protocols are mutually exclusive. Tools and External Actions Workflows can call external systems through: Tools -- Predefined integrations (e.g., Salesforce, Jira, Slack) External Actions -- Custom actions registered by builders through third-party providers (Paragon, Composio, Workato) External actions support: ProviderDescriptionACTION_PROVIDER_PARAGONParagon integration platformACTION_PROVIDER_COMPOSIO_MCPComposio MCP connectorACTION_PROVIDER_COMPOSIO_TOOLComposio tool connectorACTION_PROVIDER_EMA_EXTERNAL_TOOLEma native external toolACTION_PROVIDER_WORKATOWorkato integration platformACTION_PROVIDER_EMUEma universal connector Conditions Actions can have conditions that determine whether they execute. Conditions evaluate based on runtime values and support comparisons like equality, containment, and boolean logic. Related Workflow Data Model -- Full data structures Action Data Model -- Action type definitions Workflow API -- API endpoints AI Employee Overview -- How AI Employees use workflows

================================================================================
# Workflow API
URL: https://builder.ema.ai/api-reference/workflows/workflow-api
================================================================================

Workflow API This page documents the gRPC-Web API endpoints for querying workflows and actions. All endpoints use the gRPC-Web over HTTP protocol. For instructions on encoding and decoding gRPC-Web requests, see Handling gRPC-Web Requests. ListActions List all available action types. PropertyValueURL/workflows.v1.ActionManager/ListActionsHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptioninclude_deprecated_actionsboolNoWhether to include deprecated actions Response FieldTypeDescriptionactionsrepeated ActionTypeList of available action types Each ActionType includes the action's name, category, inputs, outputs, and metadata. See Action Data Model for structure details. ListActionsFromWorkflow List action types used in a specific workflow. PropertyValueURL/workflows.v1.ActionManager/ListActionsFromWorkflowHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionworkflow_nameRegisteredWorkflowNameYesThe workflow to query Response FieldTypeDescriptionactionsrepeated ActionTypeAction types used in the specified workflow ListExternalActions List available external actions from third-party providers. PropertyValueURL/workflows.v1.ActionManager/ListExternalActionsHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionproviderActionProviderNoFilter by provider (Paragon, Composio, etc.) Response FieldTypeDescriptionactionsrepeated ActionTypeList of external action types GetEdgeCandidates Retrieve valid edge candidates for connecting actions in a workflow graph. This endpoint helps determine which actions can be connected as inputs/outputs while maintaining a valid DAG structure (no cycles). PropertyValueURL/workflows.v1.WorkflowManager/GetEdgeCandidatesHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionworkflow_nameRegisteredWorkflowNameYesThe workflow to querysource_actionstringYesName of the source action instancesource_outputstringYesName of the output parameter Response FieldTypeDescriptioncandidatesrepeated EdgeCandidateValid target actions and inputs EdgeCandidate FieldTypeDescriptionaction_namestringName of the target action instanceinput_namestringName of the target input parametertype_matchboolWhether the types are compatible CreateWorkflow Create a new workflow definition. PropertyValueURL/workflows.v1.WorkflowManager/CreateWorkflowHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionworkflow_defWorkflowDefYesThe workflow definition Response FieldTypeDescriptionworkflow_nameRegisteredWorkflowNameName of the created workflow UpdateWorkflow Update an existing workflow definition. PropertyValueURL/workflows.v1.WorkflowManager/UpdateWorkflowHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionworkflow_defWorkflowDefYesUpdated workflow definition Response FieldTypeDescriptionworkflow_nameRegisteredWorkflowNameName of the updated workflow GetWorkflow Retrieve a workflow definition. PropertyValueURL/workflows.v1.WorkflowManager/GetWorkflowHTTP MethodPOSTProtocolgRPC-Web over HTTP Headers HeaderTypeRequiredDescriptionAuthorizationstringYesBearer tokenContent-TypestringYesapplication/grpc-web+protox-grpc-webstringYes1 Request FieldTypeRequiredDescriptionworkflow_nameRegisteredWorkflowNameYesName of the workflow Response FieldTypeDescriptionworkflow_defWorkflowDefThe workflow definition Related Workflow Overview -- Concepts and architecture Workflow Data Model -- WorkflowDef structure Action Data Model -- ActionType structure Handling gRPC-Web Requests -- Encoding guide

================================================================================
# Workflow Data Model
URL: https://builder.ema.ai/api-reference/workflows/workflow-data-model
================================================================================

Workflow Data Model This page defines the protobuf data structures used to define and configure workflows in the Ema platform. WorkflowDef The top-level workflow definition. FieldTypeDescriptionworkflow_nameRegisteredWorkflowNameUnique identifier for the workflowactionsrepeated ActionInstanceList of action instances in the workflowenum_typesrepeated EnumTypeEnum types used in this workflowworkflow_inputsmap<string, WorkflowInput>Map of workflow input definitionsdisplay_settings_workflow_inputsDisplaySettingsDisplay settings for workflow inputsresultsmap<string, ResultDef>Map of workflow result definitions (legacy)named_resultsmap<string, NamedOutput>Map of named output definitions (preferred)display_namestringUser-friendly display namedescriptionstringDescription of the workflownamed_results_editableboolWhether named results are editablenamed_results_enabledboolWhether named results protocol is active RegisteredWorkflowName FieldTypeDescriptionnamespacerepeated stringNamespace path (e.g., ["ema", "personas", "<id>"])namestringWorkflow name within the namespaceversionstringVersion string ActionInstance An instance of an action within a workflow, including its input bindings. FieldTypeDescriptionnamestringUnique name of this action instanceaction_typeRegisteredActionNameReference to the registered action typeinput_bindingsmap<string, InputBinding>Map of input parameter name to bindingconditionConditionOptional condition for executiondisplay_namestringUser-friendly display namedescriptionstringDescription of what this instance doestoolToolOptional tool configurationinput_parameter_overrideInputParameterOverrideOverrides for input parameters RegisteredActionName FieldTypeDescriptionnamespacerepeated stringNamespace pathnamestringAction name (e.g., search, call_llm)versionstringVersion string (e.g., v2) InputBinding Defines how an action input receives its value. FieldTypeDescriptionsourceoneofThe source of the binding (see below) Source Types Source TypeFieldsDescriptionaction_outputaction_name, output_nameOutput from another actionworkflow_inputinput_nameWorkflow-level inputstatic_valuevalueA constant Valuecondition_bindingcondition, if_true, if_falseConditional source selection ActionOutputBinding FieldTypeDescriptionaction_namestringName of the source action instanceoutput_namestringName of the output parameter Tool Configuration for an external tool used by an action. FieldTypeDescriptiontool_namestringName of the tooltool_configobjectTool-specific configurationintegration_idstringIntegration identifier Condition A condition that determines whether an action executes. FieldTypeDescriptionoperatorConditionOperatorComparison operatorleftConditionOperandLeft operandrightConditionOperandRight operand ConditionOperator Enum ValueDescriptionEQUALSExact equalityNOT_EQUALSNot equalCONTAINSLeft contains rightNOT_CONTAINSLeft does not contain rightGREATER_THANNumeric greater thanLESS_THANNumeric less thanIS_TRUEBoolean true checkIS_FALSEBoolean false check Complete list of ConditionOperator values. TypeReference A reference to a data type used in inputs and outputs. FieldTypeDescriptionwell_knownWellKnownTypeA well-known primitive typeenum_refstringReference to an EnumType by namearray_ofTypeReferenceArray of the referenced type EnumType A custom enum type used within a workflow. FieldTypeDescriptionnamestringName of the enum typevaluesrepeated stringAllowed values for the enum WorkflowInput An input parameter for the workflow. FieldTypeDescriptiontypeTypeReferenceData type of the inputdisplay_namestringUser-friendly namedescriptionstringDescription of the inputrequiredboolWhether the input is required ResultDef (Legacy) A result definition for the legacy output protocol. FieldTypeDescriptionaction_namestringName of the action producing the resultoutput_namestringName of the output parameter NamedOutput (Preferred) A named output definition for the preferred output protocol. FieldTypeDescriptionaction_namestringName of the action producing the outputoutput_namestringName of the output parameterdisplay_namestringUser-friendly name for the outputtypeTypeReferenceData type of the output Related Workflow Overview -- Concepts and architecture Action Data Model -- Action type structures Workflow API -- API endpoints

================================================================================
# Administration
URL: https://builder.ema.ai/administration
================================================================================

Administration This section covers workspace administration, security posture, access control, and user management on the Ema platform. Whether you are a Workspace Admin onboarding your organization or a Manager assigning roles, these pages provide the reference you need. In This Section PageDescriptionSecurity & ComplianceCertifications (SOC 2, ISO 27001/42001, HIPAA, GDPR, NIST), encryption, tenant isolation, PII redaction, secure SDLC, and vulnerability programs.Governance, Access & PermissionsRBAC model across Workspace, AI Employee, and Project levels. Nine preset roles, permission matrices, and inheritance rules.Workspaces & TenantsTenant management models, parent-child relationships, data isolation, and choosing the right multi-tenant architecture.User ManagementInviting users, assigning roles, and managing workspace settings.AI Employee (AIE) Audit LogChange tracking for AI Employees -- view what changed, who changed it, and when.AI Employee Export & ImportExport an AI Employee from one environment and import it into another.Integration Maintenance ModeSchedule maintenance windows and communicate downtime for integrations. Prerequisites You should be familiar with Core Concepts before diving into the administration guides. Next Steps After reviewing administration topics, see EmaFusion™ for model configuration, or Troubleshooting & Support if you encounter issues.

================================================================================
# AIE Audit Log (Change Log)
URL: https://builder.ema.ai/administration/audit-log
================================================================================

AIE Audit Log (Change Log) The AIE Audit Log tracks every significant change made to an AI Employee, providing a chronological record of who changed what and when. Use the audit log to troubleshoot unexpected behavior, satisfy compliance requirements, and maintain accountability across your team. What Gets Logged The audit log captures changes across the AI Employee lifecycle: CategoryExample EventsWorkflow changesWorkflow canvas edits, node additions/removals, connection changesConfiguration updatesAI Employee settings changes, integration configuration changes, model parameter adjustmentsPersona modificationsName changes, status changes (enabled/disabled), description updatesImport operationsAI Employee import started, completed, or failed (see Export & Import) Each log entry contains: Event type -- The specific action performed. Event category -- The broad category (workflow, configuration, persona, etc.). Summary -- A human-readable description of the change. Details -- Structured data with the specifics of the change (JSON format). Actor -- The user who performed the action (null for system-initiated events). Timestamp -- When the event occurred. Reference ID -- An optional link to a related entity (e.g., workflow ID, import request ID). Viewing the Audit Log Access Requirements Viewing the audit log requires the CAN_VIEW_PERSONA permission. At the Workspace level, this means: Workspace Admin can view audit logs for all AI Employees. AI Employee Admin and AI Employee Manager can view audit logs for their specific AI Employee. Tenant isolation is enforced -- you can only view audit logs for AI Employees within your own tenant. API Access The audit log is available through two interfaces: InterfaceEndpointFormatREST (OTEL format)GET /personas/{persona_id}/changelog/otelOpenTelemetry log records with attributesgRPCListPersonaAuditLogProtobuf PersonaAuditEntry messages REST (OTEL) Endpoint The REST endpoint returns audit log entries formatted as OpenTelemetry log records, making it compatible with observability pipelines. Request parameters: ParameterTypeDefaultDescriptionlimitinteger100Number of entries to return (1--1000).page_tokenstringnullCursor for the next page of results. Response fields: log_records -- Array of OTEL log records, each containing time_unix_nano, body.string_value (the summary), and attributes (event type, category, actor, details). next_page_token -- Pass this value as page_token in the next request to fetch the next page. Empty string when no more pages exist. gRPC Endpoint The ListPersonaAuditLog RPC returns strongly-typed PersonaAuditEntry messages. Request fields: FieldTypeDescriptionpersona_idstringThe AI Employee ID to query.page_sizeint32Entries per page (default 20, max 1000).page_tokenstringCursor for pagination. Pagination The audit log uses cursor-based pagination. Each response includes a next_page_token (base64-encoded). Pass this token in the subsequent request to retrieve the next page. When the token is empty, you have reached the end of the log. Entries are always returned in reverse chronological order (newest first). Recording Events Audit events are recorded automatically by the platform when changes occur. External services can also record events via the RecordPersonaAuditEvent gRPC endpoint. Required fields for recording: persona_id -- The AI Employee being modified. tenant_id -- Must match the authenticated user's tenant. event_type -- The action type. event_category -- The category of the change. summary -- Human-readable summary. Optional fields include details (structured JSON data), actor_user_id, and reference_id. Related Pages Governance, Access & Permissions -- Permission requirements for audit log access. AI Employee Export & Import -- Import operations are logged in the audit log.

================================================================================
# Governance, Access & Permissions
URL: https://builder.ema.ai/administration/governance-permissions
================================================================================

Governance, Access & Permissions Access control in Ema uses predefined roles (bundles of permissions) and permission bits (atomic actions) across three object levels: Workspace, AI Employee, and Project. You can assign preset roles but cannot create, edit, or delete roles or permission bits. Key Concepts TermDefinitionWorkspaceYour organization's container in Ema. Workspace roles can cascade down to all AI Employees and Projects inside it.AI EmployeeAn AI worker configured for a specific purpose. AI Employee roles control who can view, build, manage users, and create Projects.ProjectWork artifacts under an AI Employee. Project roles control who can view, edit, and share a single project. Not all AI Employees have Projects -- today their usage is restricted to Document Generation and Recruiter type AI Employees.RoleA tier that a user holds for a Workspace, AI Employee, or Project.Permission bitA single capability (e.g., invite users, edit workflow canvas). Roles are collections of these bits.Preset roles onlyRoles and permission bits are centrally defined. Builders use them; builders do not customize them.InheritanceA higher-level role can implicitly grant appropriate access at lower levels. For example, a qualifying Workspace role implies AI Employee access; some Project roles imply minimal AI Employee access so users can operate the project. Object Levels Workspace -- Use for organization-wide responsibilities (invite users, create AI Employees, see settings and metrics). When a Workspace role implies AI Employee access, it applies to all AI Employees in that Workspace. AI Employee -- Use when a person needs to build or manage one AI Employee (including its users, canvas, and evaluations) and create Projects beneath it. Project -- Use when a person only needs access to one Project. There is a single role at this level (Project User) which has all necessary permissions and is automatically assigned. Project roles automatically grant minimal AI Employee access. Role Catalog Ema provides eight preset roles across the three levels: LevelRolePrimary IntentWorkspaceWorkspace AdminFull workspace administrationWorkspaceWorkspace ManagerManage people and settings without full adminWorkspaceWorkspace BuilderCreate and organize AI EmployeesWorkspaceWorkspace GuestMinimal workspace accessAI EmployeeAI Employee Admin (PERSONA_ADMIN)Full control of one AI EmployeeAI EmployeeAI Employee Manager (PERSONA_WRITE)Manage AI Employee users and settingsAI EmployeeAI Employee Project User (PROJECT_WRITE)Access to work within projects under an AI EmployeeProjectProject UserFull access to work within a single project Permission Matrices Workspace Permissions Permission BitDescriptionAdminManagerBuilderGuestCreate AI EmployeesCreate new AI Employees in the workspaceY--Y--Invite UsersSend invitations to add usersYY----Change User PermissionsModify other users' role assignmentsYY----Remove UsersRemove users from the workspaceYY----View Tenant MetricsView workspace-level analyticsYY----View Workspace SettingsView workspace configuration pagesYY----View Audit LogsView audit and activity logsY------Create Template from AI EmployeeConvert an AI Employee into a reusable templateY------Create Child TenantCreate a child workspaceY--Y--Manage FlagsManage feature/configuration flagsY------Manage Template ListManage available templatesY------Manage Persona GroupsOrganize AI Employees into groupsYYY--Default AI Employee roleAuto-granted for all AI EmployeesAI Employee AdminAI Employee ManagerNo defaultNo default AI Employee Permissions Certain Workspace roles automatically grant AI Employee roles. Workspace Admin implies AI Employee Admin; Workspace Manager implies AI Employee Manager. These inherited permissions apply across all AI Employees in the workspace. Permission BitDescriptionAdminManagerProject UserView AI EmployeeView configurationYYYEdit AI EmployeeEdit configuration and settingsYN--Use AI EmployeeRun the AI EmployeeYYYShare AI EmployeeShare with othersYY--Delete AI EmployeeDelete the AI EmployeeY----Rename AI EmployeeRename the AI EmployeeYY--Change StatusEnable/disable the AI EmployeeYY--View UsersView all users with accessYY--Add UsersGrant users accessYY--Remove UsersRevoke users' accessYY--Edit User PermissionChange another user's roleYY--View Workflow CanvasView the workflow canvasYYYEdit Workflow CanvasEdit the workflow canvasY----Run EvaluationsRun evaluations on the AI EmployeeY----View MetricsView AI Employee-level analyticsYY--View Training & LogsView training artifacts and logsYY--Create ProjectCreate a new Project under this AI EmployeeYYYDoc Writer - Restore SectionRestore a previous Doc Writer section versionYY--Doc Writer - Approve SectionApprove a Doc Writer sectionYY-- Project Permissions Some AI Employee roles automatically grant Project access. AI Employee Admin and AI Employee Manager imply appropriate Project-level access where needed; Project roles may also come with minimal AI Employee access so users can operate the project. Permission BitDescriptionProject UserView ProjectView project artifacts and configurationYEdit ProjectEdit project artifacts and configurationYView Users in ProjectView who has accessYShare ProjectShare with othersYRemove User from ProjectRemove a user from the projectYView Parent AI EmployeeView the parent AI Employee's configurationY How to Use Choose the level. Decide whether access belongs at the Workspace, AI Employee, or Project level. Default to the lowest level that satisfies the need. Pick the preset role. Match responsibilities to a role using the catalog above. Use a Project role for single-project contributors. Use AI Employee Manager for workflow managers or AI Employee Project User for project contributors. Use Workspace Admin or Workspace Manager for workspace-wide operations. Related Pages User Management -- Inviting users and assigning roles in the UI. Workspaces & Tenants -- Tenant-level roles and hierarchical access. AIE Audit Log -- Track changes to AI Employee configurations.

================================================================================
# Integration Maintenance Mode
URL: https://builder.ema.ai/administration/maintenance-mode
================================================================================

Integration Maintenance Mode Note: Integration Maintenance Mode is a planned feature. The functionality described below is not yet available in the current platform release. Maintenance Mode allows administrators to schedule planned downtime windows for integrations, communicate upcoming maintenance to users, and ensure AI Employees gracefully handle periods when an integration is unavailable. Scheduling a Maintenance Window To schedule maintenance for an integration: Navigate to Settings > Integrations. Locate the integration and open its configuration panel. Select Schedule Maintenance. Set the start time and end time for the maintenance window. Optionally compose a maintenance message to explain the downtime to users (displayed when the integration is invoked during the window). Save the maintenance schedule. Bulk Scheduling When multiple integrations share the same maintenance window (e.g., a provider-wide outage), you can select multiple integrations and schedule them together to avoid repetitive configuration. Maintenance Communication Each maintenance window supports a custom message that is surfaced to users when they interact with an AI Employee that depends on the affected integration. The message editor supports basic formatting so you can include: The reason for the maintenance. Expected duration. Alternative actions or workarounds. Integration Maintenance Cards On the Integrations page, integrations with an active or upcoming maintenance window display a maintenance card showing: Status -- Whether the integration is currently in maintenance or has a scheduled window. Window -- The start and end time of the maintenance period. Message preview -- A snippet of the custom maintenance message. Behavior During Maintenance When an integration is in maintenance mode: AI Employees that depend on the integration will receive a maintenance notification instead of attempting to call the integration. Workflow steps that require the integration will be gracefully skipped or queued, depending on the workflow configuration. The custom maintenance message is displayed to end users who trigger the affected workflow. Schedule maintenance windows during low-traffic periods to minimize user impact. Use the Metrics page to identify your lowest-traffic hours. Related Pages Workspaces & Tenants -- Integration configurations are scoped to individual tenants.

================================================================================
# AI Employee Export & Import
URL: https://builder.ema.ai/administration/persona-export-import
================================================================================

AI Employee Export & Import The Export & Import feature allows you to copy an AI Employee's complete configuration and data from one environment (the source) into another AI Employee (the target). This is useful for promoting configurations from staging to production, duplicating a proven setup across tenants, or restoring a previous state. How This Agent Works The import process runs as a managed, multi-step workflow. The platform handles all the complexity of data replication, workflow copying, and configuration transfer automatically. Workflow Steps Backup -- The target AI Employee's current state is backed up before any changes are made. This backup is used for rollback if any subsequent step fails. Tag structure sync -- Tag dimensions and tags from the source AI Employee are ensured to exist in the target's database so that data replication can reference them. Data replication -- All widget data (knowledge bases, files, indexed content) is replicated from the source to the target. Each widget is replicated independently, and progress is tracked per widget. Poll for completion -- The platform monitors replication progress for each widget. You can track overall progress (completed nodes vs. total nodes) during this phase. Workflow copy -- The source AI Employee's workflow canvas (nodes, connections, and configuration) is deep-copied and associated with the target AI Employee. Configuration update -- The target AI Employee's configuration is updated to match the source, with widget name mappings applied to reflect the new data locations. Cleanup -- Old resources (the previous workflow and widget data) are removed from the target. Finalize -- The import request status is updated to reflect success or failure. Rollback on Failure If any step fails during the import, the platform automatically rolls back the target AI Employee to its pre-import state: The backed-up configuration is restored. Any newly created resources (new workflow, new widget data) are deleted. The import request is marked as FAILED with a detailed error message. The rollback process ensures that a failed import never leaves the target AI Employee in a broken or partially-updated state. Progress Tracking During the data replication phase, you can monitor progress through the import request status. The platform reports: Total nodes -- The total number of data nodes across all widgets that need to be replicated. Completed nodes -- The number of nodes that have been successfully replicated so far. Progress updates are written to the database after every polling cycle, so you see near-real-time status even for large imports. Timeouts and Limits ParameterValueMaximum replication poll duration1 hour per widgetMaximum consecutive poll errors5 (before the import is marked as failed)Poll interval10 seconds between status checks Requirements Both the source and target AI Employees must belong to the same tenant. The user initiating the import must have appropriate permissions on both AI Employees. Integrations used by the source AI Employee should be available and configured in the target environment. The platform validates integration availability during the import process. Related Pages AIE Audit Log -- Import events are recorded in the audit log. Workspaces & Tenants -- Understanding tenant boundaries for import operations.

================================================================================
# Security & Compliance
URL: https://builder.ema.ai/administration/security-compliance
================================================================================

Security & Compliance Ema maintains an enterprise-grade security posture backed by independent audits, automated tooling, and privacy-by-design principles. This page summarizes the certifications, architecture controls, and data-protection practices that underpin the platform. For up-to-date compliance certificates and supporting evidence, visit the Ema Trust Center. Compliance Portfolio ISO 42001 AIMS & EU AI Act Ema is one of the industry's earliest adopters of ISO 42001 AIMS (AI Management System), demonstrating that AI governance -- covering data handling, bias mitigation, and lifecycle controls -- aligns with internationally recognized best practices. The certification provides assurance that generative-AI features are designed, audited, and improved under a formal management system. Ema's alignment with the EU AI Act (effective 2025) ensures that regulated customers in healthcare, finance, and other sectors meet both current GDPR mandates and impending AI regulations without additional remediation. Core Certifications CertificationScopeSOC 2 Type IIIndependent audit confirming design and operating effectiveness of controls for security, availability, and confidentiality over a sustained period.ISO 27001International ISMS standard, audited annually to verify policies, risk processes, and technical controls.ISO 42001 AIMSAI risk management framework audited under a formal ISMS for AI, from data collection to post-deployment monitoring.CSA STAR Level 1Transparent, documented controls aligned with the CSA Security, Trust & Assurance Registry framework.HIPAA-Aligned ControlsTechnical security controls (access management, encryption, logging) meet HIPAA Security Rule requirements for Protected Health Information.GDPRData-protection policies, breach notifications, and Data Processing Addendum (DPA) satisfy EU personal-data regulations.NIST AI RMF, NIST CSF 2.0 & NIST 800-171Frameworks guiding internal risk management, serving as reference points for customers with U.S. government or defense requirements. Security Architecture & Tooling Cloud Native Application Protection Platform (CNAPP) A cloud-configuration posture and application-protection platform continuously inventories all cloud assets, runs automated misconfiguration checks against industry benchmarks, and detects container-runtime threats. Customers benefit from real-time visibility into risk exposure and automated alerts when configurations drift. Endpoint Data Loss Prevention (DLP) An endpoint DLP solution monitors and controls data in motion on managed devices, applying context-aware policies to block unauthorized exports. Sensitive information cannot leave any endpoint without meeting preconfigured security requirements. Endpoint Firewall & Mobile Device Management (MDM) Company-issued devices are hardened, patched, and continuously monitored via a central MDM platform, with host-level firewalls enforcing strict security baselines. Security Information and Events Monitoring (SIEM) A cloud-native SIEM ingests logs from audit trails, container APIs, and network sensors into a scalable data lake, enabling near-instant search across historical events for rapid threat hunting and forensic investigations. Security Orchestration, Automation, and Response (SOAR) An integrated SOAR platform orchestrates automated playbooks that enrich alerts, assign severity, and trigger containment actions such as isolating hosts or revoking credentials. Intrusion Detection System (IDS) Deep-packet inspection monitors both north-south and east-west traffic within every virtual network, identifying malware callbacks, lateral-movement attempts, and exploit activity. Web Application Firewall (WAF) & DDoS Mitigation An enterprise-grade WAF sits at the edge to protect applications and APIs by applying managed rulesets, custom signatures, and behavioral bot-management controls. Built-in DDoS mitigation absorbs volumetric and application-layer floods before they reach origin servers. Zero Trust Network Access (ZTNA) Identity-aware, MFA-gated tunnels to internal services replace traditional VPN. Only authenticated and posture-verified devices can reach sensitive internal platforms. Data Security & Privacy Encryption LayerStandardIn TransitTLS 1.2+ for all data traveling between clients, services, and third-party integrations.At RestAES-256 for all stored data -- object storage, databases, and backups. Customer-managed keys (CMEK) available in single-tenant deployments. Tenant Isolation & Segmentation Multi-Tenant (default): Logical separation via namespaces, row-level security, and strict network policies. Each customer's data and compute remain logically separated from other tenants. Single-Tenant (optional): Dedicated VPC, separate database cluster, and unique KMS keys for customers with stringent isolation or regulatory requirements. For details on tenant models and data isolation, see Workspaces & Tenants. Data Retention & Deletion Customer data is retained only as long as necessary to provide services, or as specified in the DPA. Customers act as data controllers; Ema is the data processor. Automated pipelines remove data across storage, caches, and backups upon request. PII Redaction Configurable ingestion stages can strip, mask, or hash personally identifiable information (PII) before data is stored or used in downstream indexes. Customers choose their desired level of anonymization to match regulatory requirements. Secure Development & Vulnerability Programs Secure SDLC SAST and Secret Scanning: Every pull request is scanned for vulnerabilities and secrets; critical or high-severity findings block merges until resolved. Software Composition Analysis (SCA): Real-time scanning of open-source dependencies. Detected CVEs generate pull requests; patch timelines are tracked centrally to ensure compliance with SOC 2, ISO 27001, NIST, and HIPAA. Vulnerability Assessment & Penetration Testing (VAPT) ProgramCadenceDetailsAutomated ScansWeeklyIndustry-standard crawlers and scanners run each week to catch new weaknesses from code changes.Manual PentestsOngoingSecurity engineers perform targeted reviews, simulating attacker tactics using OWASP Top 10-aligned tests.Third-Party AuditsAnnualIndependent firms validate controls and identify runtime vulnerabilities. Findings are prioritized by severity and addressed per patching-cycle SLAs. FAQs What is your data retention and disaster recovery policy? Backups are retained for 365 days by default (configurable for single-tenant customers). Recovery Time Objective (RTO) is 4 hours; Recovery Point Objective (RPO) is 30 minutes. Do you have cyber insurance? Yes. Ema maintains cyber insurance that extends to client-related incidents with no known coverage gaps. How do you handle data privacy? Ema is GDPR- and HIPAA-aligned. Customers can execute a Data Processing Addendum (DPA) that outlines processing, storage, and deletion workflows. How do you ensure tenant isolation? Multi-tenant deployments use logical separation via namespaces, row-level policies, and network segments. Single-tenant deployments provide dedicated VPCs, databases, and KMS keys. How do you handle AI bias and fairness? Ema leverages industry-standard models and inherits their baseline performance. The focus is on ensuring no additional bias is introduced and maintaining accuracy, supported by ISO 42001 certification. Do you use sub-processors? Yes. Sub-processors undergo thorough vendor risk assessment before onboarding and regular reviews thereafter. A complete list is available at trust.ema.co/subprocessors. What compliance training do employees receive? All employees complete mandatory training in compliance, ethics, and their functional areas upon hiring and annually thereafter.

================================================================================
# User Management
URL: https://builder.ema.ai/administration/user-management
================================================================================

User Management This page covers how to invite users, assign roles, and manage workspace settings in the Ema platform. Accessing User Management Sign in to the Ema platform. Navigate to Settings from the main navigation. Select the Users tab. The Users page displays all members of your workspace in a table, along with their roles and invitation status. Inviting Users Prerequisites You must hold a role with the Invite Users permission to add new members. At the Workspace level, this includes Workspace Admin and Workspace Manager. See Governance, Access & Permissions for the full permission matrix. Steps On the Settings > Users page, click Invite Users. Enter one or more email addresses. You can: Type an email and press Enter or comma to add it. Paste a comma-separated list of emails. Select a role for the invited users from the dropdown. Available roles are loaded based on your workspace's tenant-level role catalog. Click Send Invitations. Invited users receive an email with a magic login link. The link expires after 15 minutes. If the link is not received, verify: The recipient's email provider is not blocking Ema's emails or routing them to spam. The recipient is not from a geo-blocked country. Common Invitation Errors ErrorCauseResolutionInvalid emailThe entered email address does not match a valid format.Correct the email and retry.Permission deniedYour role does not have the Invite Users permission.Ask a Workspace Admin or Manager to send the invitation.Invalid emails while pastingOne or more pasted emails are malformed.Remove invalid entries and retry. Assigning and Changing Roles Role assignment and modification are available to users with the Change User Permissions permission bit (Workspace Admin, Workspace Manager). On the Settings > Users page, find the user in the table. Click the role dropdown next to the user's name. Select the new role. Confirm the change. Role changes take effect immediately. The user does not need to log out and log back in. Removing Users Users with the Remove Users permission bit (Workspace Admin, Workspace Manager) can remove members from the workspace. On the Settings > Users page, find the user in the table. Click the remove or delete action for that user. Confirm removal. Removing a user revokes their access to the workspace and all AI Employees within it. If the user also has direct AI Employee-level or Project-level roles, those must be revoked separately. Managing AI Employee-Level Access In addition to workspace-level roles, you can manage access at the individual AI Employee level: Navigate to the AI Employee's detail page. Open the user management section (accessible from the AI Employee's settings or sharing options). Add users and assign AI Employee-level roles (AI Employee Admin, Manager, Builder, or Guest). Users added at the AI Employee level do not need a workspace-level role beyond Guest (or no workspace role if they are explicitly invited to the AI Employee). Related Pages Governance, Access & Permissions -- Role catalog and permission matrices. Workspaces & Tenants -- Tenant-level roles and parent-child access.

================================================================================
# Workspaces & Tenants
URL: https://builder.ema.ai/administration/workspaces-tenants
================================================================================

Workspaces & Tenants For foundational concepts on workspaces and tenants, see Core Concepts: Workspaces & Tenants. This page focuses on administrative tasks: tenant management models, parent-child relationships, and choosing the right architecture. What Is a Tenant? A tenant is the fundamental unit of data isolation on the Ema platform. Each tenant has its own users, AI Employees, data, workflows, and configurations -- completely separated from every other tenant. PropertyDetailsData IsolationEach tenant's data is fully isolated. No data flows between tenants unless explicitly configured.Independent UsersEvery tenant manages its own users and roles. Access to other tenants must be explicitly granted.Dedicated AI EmployeesAI Employees belong to a specific tenant and operate within that tenant's data boundaries.Hierarchical RelationshipsTenants can be organized in parent-child hierarchies to enable template sharing and metrics rollup. Tenant Roles Before configuring tenant hierarchies, understand the two levels of roles. Tenant-Level Roles RoleTenant ManagementBuild AccessDefault AI Employee RoleAdminCan invite users, view metricsCan build new AI EmployeesAI Employee AdminManagerCan invite users, view metricsNo accessAI Employee ManagerBuilderNo privilegesCan build new AI Employees; receives Admin role for AI Employees they createNo access unless explicitly invitedGuestNo privilegesNo accessNo access unless explicitly invited AI Employee-Level Roles RoleManagementWorkflow AccessAudit LogsAdminCan invite users, view metricsCan edit workflowCan viewManagerCan invite users, view metricsNo accessCan viewBuilderNo privilegesCan edit workflowNo accessGuestNo privilegesNo accessNo access A user's tenant role determines their default AI Employee role, but users can be granted different roles for specific AI Employees independently. For the full permission matrix, see Governance, Access & Permissions. Parent-Child Tenant Relationships Ema supports hierarchical tenant relationships where one tenant (the parent) can have one or more child tenants. +--------------------+ | Parent Tenant | +---------+----------+ | +---------------+---------------+ v v v +---------------+ +---------------+ +---------------+ | Child Tenant | | Child Tenant | | Child Tenant | | A | | B | | C | +---------------+ +---------------+ +---------------+ CapabilityDirectionDetailsUser AccessDownwardParent users can access child tenants only on explicit invitation. Access is never automatic.Template SharingDownwardParent tenants can share AI Employee templates to child tenants.Metrics AggregationUpwardAggregated metrics roll up from child to parent via the tenant-scoped metrics dashboard. No PII or log data moves upward. Parent workspace administrators can view child-tenant metrics using the chip selectors on the Metrics page and drill into per-tenant detail tables.Data & LogsNoneNo data flows between tenants in either direction. Each tenant's data is fully isolated. Constraints A child tenant can have only one parent. Tenant hierarchies can be multiple levels deep -- child tenants can have their own children. Only a parent tenant's users can be invited to its direct child tenants. You cannot skip levels (a grandparent user must first be added to the parent, then to the child). Tenant Management Models Partners and organizations can choose from four models depending on their business needs. Model 1: Standard -- Data Isolation per Company The most common and recommended model. Each company gets its own tenant. When to use: Each customer requires full data isolation. Customers may log into the Ema platform directly. You need clear boundaries between customer environments. Benefits: Complete data isolation between all companies. Each customer manages their own users and AI Employees within their tenant. Partners can share templates downward to customer tenants. Clean, professional setup with real customer domains. Model 2: Multiple Tenants for the Same Company Internal separation by region, department, or business unit. When to use: A single company needs data isolation between internal divisions. Billing, data, or permission isolation between internal teams or regions is required. Current limitation: Every tenant requires a unique domain. Additional tenants for the same company must use a non-standard/placeholder domain (e.g., company-us.co instead of company.com). ConsiderationDetailData IsolationAchieved between sub-tenantsDomain RequirementRequires creating a non-standard/placeholder domain for additional tenantsUser ManagementUsers from the parent tenant are added via the parent hierarchyProfessionalismPlaceholder domains may appear unprofessional to some customers This model is a workaround for the current platform limitation of not having group-level isolation. A future platform enhancement for group-level permissions, metrics, and data isolation is planned. Model 3: Single Tenant Across Multiple Companies Best for embedded chatbots and API-only customers. When to use: Customers interact via embedded chatbots, SDKs, or APIs -- they do not log into the Ema UI. Customers are small or have lightweight use cases. The partner fully manages all AI Employees on behalf of customers. How data separation works: AI Employees have inherent data separation -- unless explicitly connected, data does not flow between AI Employees. Individual workflow executions are isolated, so even a single AI Employee can safely service multiple customers. Benefits: Simplest setup with the lowest operational overhead. No need for customers to manage their own tenant. Partner retains full control over all configurations. Trade-offs: Customers cannot independently manage their AI Employees. Less granular control per customer compared to dedicated tenants. Model 4: Data Localization Across Geographies For data residency and compliance requirements. When to use: Data must reside in a specific geographic region. GDPR, data sovereignty, or similar legal constraints apply. Important: Sub-tenants do NOT solve data localization. All tenants within the same environment share the same underlying infrastructure and governance policies. True data localization requires a completely separate Ema environment in the target region. Tenants across different environments cannot communicate with each other. Separate environments are more expensive and require setup by the infrastructure team. Choosing the Right Model CriteriaStandardMulti-TenantSingle TenantGeo-LocalizedData isolationFullFullAI Employee / RuntimeFull (per env)Customer logs into UIYesYesNoYesSetup complexityLowMediumLowestHighestRegulatory / data residencyNoNoNoYesBest customer sizeAnyLarge (internal separation)Small / EmbeddedAny (global)Tenant domain1 real per customerMay need placeholdersSingle partner domain1 real per customer per region Decision flow: Does the customer log into the Ema UI? No -- Does the customer need dedicated data isolation? If no, use Model 3 (Single Tenant). If yes, use Model 1 (Standard). Yes -- Does the company need internal team or region separation? If no, use Model 1 (Standard). If yes, does it have data residency requirements? If no, use Model 2 (Multi-Tenant). If yes, use Model 4 (Geo-Localized). Tenant Access: Current State and Future Current State -- Email Aliases When a partner user needs access to a child tenant, they must use an email alias (e.g., admin1+acme@partner.com) and log out/log in to switch between tenants. Future State -- Tenant Switcher An upcoming update will eliminate alias-based access: Same email and user ID will work across all tenants. A tenant switcher dropdown in the UI will enable instant switching without logging out. Access to child tenants will still require explicit invitation. Roles remain independently assigned per tenant. User Groups (future): User Groups will allow bulk management of roles across the parent tenant, child tenants, and specific AI Employees simultaneously. FAQs What is the smallest unit of data isolation on the platform? The tenant is the smallest unit of full data isolation. AI Employees also have data separation (data does not flow between AI Employees unless explicitly connected), and individual workflow executions have runtime isolation. There is no group-level isolation today. Can I change a tenant's parent after it has been set? A child tenant can only have one parent. Corrections are handled case-by-case. In the worst case, a new child tenant can be created and data migrated. Do child tenants inherit users from the parent? No. Users must be explicitly invited to each child tenant. Can templates be shared upward from child to parent? No. Templates can only be shared downward from parent to child tenants. Can a child tenant have its own child tenants? Yes. Tenant hierarchies can be nested to any depth. How do I control whether a customer can build AI Employees? Assign the appropriate tenant role. Manager and Guest roles have no build access; Admin and Builder roles allow building. Does creating sub-tenants solve data localization (e.g., GDPR)? No. All tenants within the same environment share the same infrastructure. Data localization requires a separate Ema environment in the target geography. What happens to the "plus sign" email aliases after the tenant switcher update? Existing alias-based accounts will be migrated. Going forward, the same primary email will be used across all tenants, and switching will happen via a dropdown in the UI. Related Pages Governance, Access & Permissions -- Full permission matrices. User Management -- Inviting users and assigning roles. AIE Audit Log -- Track changes across your AI Employees.

================================================================================
# Agent QA
URL: https://builder.ema.ai/agent-qa
================================================================================

Agent QA Agent QA is an AI Employee on the Ema platform that evaluates customer service voice interactions against your organization's quality standards -- automatically, at scale, and with consistent criteria. Instead of manually reviewing a small sample of calls, Agent QA processes every interaction and produces: QA Scores -- A weighted score from 0 to 100 for each interaction Scorecards -- Parameter-by-parameter Pass/Fail results with detailed reasoning and transcript evidence Analytics Dashboards -- Trends across agent performance, contact reasons, resolution rates, and sentiment Coaching Insights -- AI-identified patterns including agent strengths, improvement areas, product bugs, and competitive intelligence Real-Time Transcription -- Live speech-to-text with contextual knowledge base recommendations during active calls This guide covers everything from initial setup to daily operations, score interpretation, agent self-service, and technical integration. Who This Guide Is For RoleStart Here Platform Administrator setting up Agent QA for the first time1. Core Concepts, then 2. Setting Up Agent QA, then 3. Imports, Genesys, and Agent Mapping QA Manager or Interaction Analyst running day-to-day QA operations4. Reviewing Interactions, 6. Metrics Dashboard, 7. Insights Dashboard Supervisor or Team Lead coaching agents5. Understanding QA Scores, 7. Insights Dashboard Contact Center Agent viewing your own results10. For Agents: Viewing Your Own Results Section Contents SectionDescription Core ConceptsPipeline, key terms, evaluation mechanisms, the daily QA loop, supported languages Setting Up Agent QAPrerequisites, AI Employee creation, Auto-Learning, knowledge base, integrations, contact reasons, permissions, first call Imports, Genesys, and Agent MappingBring conversations in -- Genesys Cloud, bulk file upload, re-runs, and agent mapping Reviewing Interactions (Audit Tab)Navigation, filters, sorting, scorecard details, transcript, strengths, opportunities, CSAT analysis Understanding QA ScoresWeighted scoring formula, score ranges, critical parameters, auto-fail, N/A handling Metrics DashboardOverview KPIs, available analytics charts, filters, reading the charts Insights DashboardFive insight categories, thresholds, detail views, effective use Feedback and Continuous LearningSubmitting feedback, moderation, improvement suggestions, applying changes Managing QA ParametersEditable fields, when to re-run Auto-Learning, training material generation For Agents: Viewing Your Own ResultsAgent self-service guide for viewing evaluations and scores Roles and PermissionsFour roles, permissions matrix, permission codes Audio Ingestion APIUpload audio recordings (.mp3/.wav) for processing by Agent QA. Transcript Ingestion APIUpload pre-existing transcripts (JSON/XML/HTML) when audio is unavailable. Daily Data Export APIPull nightly QA results, scorecards, and insights as JSONL with a manifest. CSAT Ingestion APIUpload a customer satisfaction score or free-text feedback for a previously ingested call. GlossaryDefinitions of all Agent QA terms

================================================================================
# For Agents: Viewing Your Own Results
URL: https://builder.ema.ai/agent-qa/agent-view
================================================================================

For Agents: Viewing Your Own Results This section is for contact center agents who want to view and understand their own QA evaluations. 10.1 What Agent QA Means for You Your data is filtered to you. When you log in, you only see your own interactions. Other agents cannot see your evaluations. Your supervisors and QA managers can. Scores are based on defined, consistent criteria. Each evaluation uses the same parameters for everyone on your team, so scoring is objective. The goal is coaching, not punishment. Agent QA surfaces specific, actionable feedback so you can improve in targeted areas. 10.2 Viewing Your Evaluations Log in to Ema at app.ema.co Navigate to your Agent QA AI Employee Click the Audit tab You will see a list of your evaluated interactions with Interaction Details, Duration, QA Status, QA Score, and Date. 10.3 Reading Your Scorecard Open an interaction and click the Scorecard tab: Result -- Pass (green), Fail (red), or N/A (gray) Parameter name and category -- What was being evaluated Pass/Fail instruction -- The evaluation criteria used for this parameter Rationale -- A detailed explanation of why it passed or failed. Read this first. Verbatims -- Click the "Source" accordion to see the exact transcript excerpts used as evidence 10.4 Understanding Your Score Your score is calculated as: (Passed weight / Applicable weight) x 100 Parameters you pass contribute their full weight Parameters you fail contribute 0 N/A parameters are excluded entirely If your score is 0, it means a critical parameter failed. This does NOT mean everything was wrong -- it means one non-negotiable standard was not met. 10.5 Strengths and Opportunities Strengths Tab -- Highlights what you did well, with each item showing the Driver, Category, and a Key Insight justification. Use these to understand what is working so you can keep doing it consistently. Opportunities Tab -- Identifies areas where you can improve, with each item showing the Driver, Category, and a Key Insight justification with coaching recommendations. 10.6 Additional Data in Your Evaluation CSAT Analysis (sentiment, resolution status, contact reason) and talk time breakdown data are computed by the backend but are not yet displayed in the evaluation details UI. These fields will be visible once the CSAT Analysis tab is fully implemented. 10.7 Questions About Your Evaluation SituationWhat to Do You disagree with an evaluationTalk to your supervisor. They can review and submit feedback on specific parameters. You don't understand a scoreRead the Rationale for each parameter. Then click the "Source" accordion to see the transcript excerpts. A pattern keeps showing upFocus on trends, not individual calls. If the same parameter keeps failing, that is a reliable signal to work on.

================================================================================
# Audio Ingestion API
URL: https://builder.ema.ai/agent-qa/api-audio-ingestion
================================================================================

Audio Ingestion API The Audio Ingestion API uploads an audio recording (e.g., a call recording from a telephony provider) to be processed by an Agent QA AI Employee. Once uploaded, the file is transcribed, diarized, evaluated against your QA parameters, and made available in the Audit tab and the daily export. Use this endpoint when you have an audio file (.mp3 or .wav). If you already have a text transcript, use the Transcript Ingestion API instead. 12.1 Authentication & Headers For instructions on generating a Bearer token from your API key, see the internal Authentication Guide for Agent QA. All requests require the following headers: HeaderTypeRequiredDescription AuthorizationstringYesBearer token (e.g., Bearer <token>) x-persona-idUUIDYesThe unique identifier of the Agent QA AI Employee (persona). Found in the URL of the Ema web app, e.g., https://staging.ema.co/ai-employees/<persona_id>. 12.2 Upload File Uploads an audio file for processing by the AI Employee. PropertyValue URL{base_url}/api/v1/external/upload/file HTTP MethodPOST Content-Typemultipart/form-data The {base_url} is region-specific (for example, a staging EU tenant uses https://api.staging.tp-eu.ema.co). Confirm the correct host for your deployment with your Ema contact. Form-Data Fields FieldTypeRequiredDescription filefileYesThe audio file to upload. Supported formats: .mp3, .wav. agent_idstringYesIdentifier of the human agent associated with the recording. agent_emailstringYesThe human agent's email. Used for permissioning so agents can only view their own calls. resource_idstringYesExternal identifier (e.g., a Call ID from your telephony provider). languagestringNoLanguage of the audio file. channelsintegerYesNumber of channels in the call (Mono = 1, Dual/Stereo = 2). channel_mapJSONYesFor stereo calls, which channel maps to which speaker. Example: {"Agent": 0, "Customer": 1}. timestampstringYesCall timestamp. Values without timezone information are treated as UTC. case_idstringNoTicket/case ID associated with the call. customer_surveyJSONNoCustomer satisfaction/dissatisfaction survey data. agent_tenureintegerNoTenure of the associated agent in days. metadataJSONNoAny additional metadata you want attached to the call record. Constraints Maximum file size: 25 MB. Allowed MIME types: audio/mpeg, audio/wav. Success Response (200 OK) { "file_id": "550e8400-e29b-41d4-a716-446655440000", "file_name": "recording_2024_01_15.mp3", "status": "UPLOAD_COMPLETED" } 12.3 Error Codes HTTP CodeReason 400 Bad RequestMissing headers, invalid UUID format, unsupported file extension, or missing agent_id. 403 ForbiddenCredentials do not have permission to access the specified AI Employee. 413 Payload Too LargeThe uploaded file exceeds the size limit. 429 Too Many RequestsRate limit exceeded. Retry with exponential backoff. 500 Internal Server ErrorUnexpected server-side error. 12.4 Rate Limits A rate limit of 10 queries per second is enforced on the data upload API. When rate limited, the response includes a Retry-After header (in seconds). Clients should retry with exponential backoff. 12.5 Sample Python The script below explicitly sets the MIME type to audio/mpeg. Use audio/wav if uploading WAV files. The x-persona-id header is the source of truth for which AI Employee the data belongs to. import requests import time BASE_URL = "https://api.<region>.ema.co" # replace with your domain AUTH_TOKEN = "YOUR_BEARER_TOKEN" AI_EMPLOYEE_ID = "YOUR_AI_EMPLOYEE_UUID" headers = { "Authorization": f"Bearer {AUTH_TOKEN}", "x-persona-id": AI_EMPLOYEE_ID, } def upload_audio_file(file_path, agent_id, agent_email, resource_id, language, channels, channels_map, timestamp, max_retries=3): """Uploads an audio file for a specific AI Employee.""" url = f"{BASE_URL}/api/v1/external/upload/file" data = { "agent_id": agent_id, "agent_email": agent_email, "resource_id": resource_id, "language": language, "channels": channels, "channels_map": channels_map, "timestamp": timestamp, } try: with open(file_path, "rb") as f: files = {"file": (file_path, f, "audio/mpeg")} # or audio/wav for attempt in range(max_retries + 1): response = requests.post(url, headers=headers, data=data, files=files) if response.status_code == 200: return response.json() if response.status_code == 429 and attempt < max_retries: retry_after = int(response.headers.get("Retry-After", 2 ** attempt)) time.sleep(retry_after) continue print(f"Failed! Status: {response.status_code}") print(f"Error: {response.text}") return None except FileNotFoundError: print(f"Error: File {file_path} not found.") return None if __name__ == "__main__": result = upload_audio_file( file_path="sample-3s.mp3", agent_id="human_agent_001", agent_email="human_agent_001@email.com", resource_id="resource_id_123", language="en", channels=2, channels_map={"Agent": 0, "Customer": 1}, timestamp=time.time(), ) if result: print(f"New File ID: {result.get('file_id')}")

================================================================================
# CSAT Ingestion API
URL: https://builder.ema.ai/agent-qa/api-csat-ingestion
================================================================================

CSAT Ingestion API The CSAT Ingestion API uploads a customer satisfaction score or free-text feedback for a call that has already been submitted to Agent QA via the Audio Ingestion API or Transcript Ingestion API. Ema uses the CSAT signal to enrich the call's QA evaluation. The resource_id and agent_id in the CSAT payload must exactly match the values used during the original upload — they are how Ema joins the CSAT to the right call. 15.1 Authentication & Headers HeaderTypeRequiredDescription AuthorizationstringYesBearer token (e.g., Bearer <token>) Content-TypestringYesapplication/json Note — unlike the Audio and Transcript Ingestion APIs, CSAT Ingestion does not use the x-persona-id header. The Agent QA persona is passed as persona_id in the JSON body. 15.2 Upload CSAT PropertyValue URL{base_url}/api/agent-qa/upload/csat HTTP MethodPOST Content-Typeapplication/json Body Fields FieldTypeRequiredDescription resource_idstringYesExternal identifier for the call. Must match the resource_id used when uploading the voice file or transcript. agent_idstringYesIdentifier of the human agent associated with the call. Must match the agent_id used when uploading the voice file or transcript. csat_inputstringYesA numeric score ("1" through "5"), free-text feedback, or a single emoji. If parseable as an integer 1–5, it is treated as a numeric score. An emoji is interpreted using your tenant's emoji-to-score mapping. Anything else is treated as free-text feedback. The value must be sent as a string. persona_idstringYesThe unique identifier of the Agent QA AI Employee (persona). Example Request curl -X POST \ "{base_url}/api/agent-qa/upload/csat" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "resource_id": "resource_id_123", "agent_id": "human_agent_001", "persona_id": "<persona_id>", "csat_input": "4" }' Success Response (200 OK) The response indicates whether CSAT evaluation was triggered immediately or deferred. If the Agent QA workflow for the call has already finished, evaluation is triggered right away: { "status": "ok", "message": "CSAT uploaded and evaluation triggered", "csat_triggered": true } If the Agent QA workflow has not yet completed, the CSAT is stored and evaluation is automatically triggered once the workflow finishes. You do not need to re-upload the CSAT in this case: { "status": "ok", "message": "CSAT uploaded, evaluation will be triggered after call analysis completes", "csat_triggered": false } 15.3 Error Codes HTTP CodeReason 400 Bad RequestMissing required fields, invalid UUID format, or no matching call found for the provided resource_id and agent_id. 401 UnauthorizedMissing or invalid Authorization header. 403 ForbiddenCredentials do not have permission to access the specified persona. 429 Too Many RequestsRate limit exceeded. Retry with exponential backoff. 500 Internal Server ErrorUnexpected server-side error. CSAT requires a CSAT persona to be configured for your tenant. If none is configured, this endpoint does not return an error status code — it returns 200 OK with an error in the response body instead: { "status": "error", "message": "No CSAT persona configured for this tenant" } Always check the status field in the response body, not just the HTTP status code — a client that only checks for a non-200 status will silently miss this failure. Ask your Ema representative to configure a CSAT persona for your tenant if you see this message. 15.4 Sample Python import requests BASE_URL = "https://api.<region>.ema.co" # replace with your domain AUTH_TOKEN = "YOUR_BEARER_TOKEN" AI_EMPLOYEE_ID = "YOUR_AI_EMPLOYEE_UUID" headers = { "Authorization": f"Bearer {AUTH_TOKEN}", "Content-Type": "application/json", } def upload_csat(resource_id, agent_id, persona_id, csat_input): """Uploads a CSAT score or free-text feedback for a previously ingested call. Args: resource_id: Must match the resource_id used when uploading the voice file. agent_id: Must match the agent_id used when uploading the voice file. persona_id: The Agent QA AI Employee (persona) ID. csat_input: A string — either a numeric score ("1"–"5") or free-text feedback. Values outside 1–5 are treated as free-text. """ url = f"{BASE_URL}/api/agent-qa/upload/csat" payload = { "resource_id": resource_id, "agent_id": agent_id, "persona_id": persona_id, "csat_input": csat_input, } response = requests.post(url, headers=headers, json=payload) if response.status_code == 200: result = response.json() print(f"Success! csat_triggered: {result.get('csat_triggered')}") return result print(f"Failed! Status: {response.status_code}") print(f"Error: {response.text}") return None if __name__ == "__main__": # Example 1 — CSAT as a numeric score ("1"–"5" as a string). upload_csat( resource_id="resource_id_123", agent_id="human_agent_001", persona_id=AI_EMPLOYEE_ID, csat_input="4", ) # Example 2 — CSAT as free-text feedback. upload_csat( resource_id="resource_id_456", agent_id="human_agent_002", persona_id=AI_EMPLOYEE_ID, csat_input="The agent was very helpful and resolved my issue quickly.", )

================================================================================
# Daily Data Export API
URL: https://builder.ema.ai/agent-qa/api-daily-export
================================================================================

Daily Data Export API The Daily Data Export API returns presigned download URLs for an AI Employee's Agent QA daily export and its manifest file. The export is generated nightly by Ema's internal workflow and covers all calls processed on the specified UTC date. Use this API to pull evaluation results, scorecards, and insights into your own data warehouse, BI tool, or downstream analytics system. 14.1 Authentication & Headers HeaderTypeRequiredDescription AuthorizationstringYesBearer token (e.g., Bearer <token>) 14.2 Get Daily Export Data PropertyValue URL{base_url}/api/agent-qa/get_daily_data HTTP MethodGET Query Parameters FieldTypeRequiredDescription persona_idUUIDYesThe unique identifier of the AI Employee (persona). Found in the URL of the Ema web app. datestringYesUTC date to retrieve, in YYYY-MM-DD format. Must be strictly in the past (UTC). Today or future dates are rejected. Example Request curl -X GET \ "{base_url}/api/agent-qa/get_daily_data?persona_id=<persona_id>&date=2025-06-01" \ -H "Authorization: Bearer <token>" Response A successful response (200 OK) returns a JSON object with the following fields: FieldTypeDescription signed_urlstringPresigned download URL for the daily data export file (JSONL format). manifest_signed_urlstringPresigned download URL for the manifest JSON file. expires_in_secondsintegerNumber of seconds until the presigned URLs expire. Currently 3600 (1 hour). 14.3 File Structure The two presigned URLs point to files stored in Ema's internal cloud storage. One is a data file containing the actual records and results. The other is a manifest file describing the export partition. URLs expire within an hour; re-request if needed. Data File (signed_url → agent_qa_export.jsonl) The data file is JSONL (newline-delimited JSON). Each line is a self-contained JSON object representing one processed call record, corresponding to a single resource_id. The schema is defined by AgentQACallRecord. FieldTypeRequiredDescription resource_idstringYesUnique external call identifier sent by the client (e.g., a Call ID). agent_idstringYesIdentifier of the human agent involved in the call. agent_emailstringNoEmail of the agent. Used for permissioning. call_timetimestampYesISO 8601 UTC timestamp of when the call occurred. persona_idstringYesIdentifier of the Agent QA AI Employee that processed this call. final_scorefloatNoCalculated QA score on a 0–100 scale. Null if evaluation did not complete. sentimentenumNoOverall sentiment. One of: POSITIVE, NEGATIVE, NEUTRAL. resolution_statusenumNoWhether the issue was resolved. One of: RESOLVED, NOT_RESOLVED. contact_reason_categorylist[string]NoOrdered list of categories explaining why the customer contacted support. call_driver_reasonstringNoDetailed free-text reason for the call. non_resolution_reason_categorylist[string]NoReasons the call was not resolved. Only populated when resolution_status is NOT_RESOLVED. agent_talk_timefloatNoDuration (seconds) the agent was speaking. user_talk_timefloatNoDuration (seconds) the user was speaking. dead_airfloatNoDuration (seconds) of silence/dead air. total_audio_timefloatNoTotal audio duration (seconds). case_idstringNoTicket/case ID associated with the call. agent_tenureintegerNoAgent tenure in days. rule_resultslist[object]YesList of QA rule evaluation results. See below. insightslist[object]YesList of behavioural insights. See below. transcriptlist[object]YesThe diarized call transcript as an ordered list of utterances, each {role, message, start, end} (start/end in seconds from call start). A successfully transcribed call with no utterances exports as an empty list, not an error. Insight Attributes FieldTypeDescription insight_typeenumOne of: STRENGTH, WEAKNESS, BUG, FEEDBACK, COMPETITOR. driverstringHigh-level behavioural driver (e.g., "Information verification"). categorystringSub-category within the driver (e.g., "Active listening"). justificationstringExplanation for why this insight was surfaced. verbatimstringTranscript snippet supporting this insight. Rule Result Attributes FieldTypeDescription rule_namestringName of the QA rule being evaluated. rule_categorystringGrouping of rules (e.g., "Customer experience", "Call management"). rule_weightfloatWeighting of this rule when calculating the final score. is_criticalboolWhether this is a critical rule. If any critical rule fails, the recording receives a final score of 0. rule_mechanismenumInformation source used. One of: TRANSCRIPT, TRANSCRIPT_WITH_KNOWLEDGE_BASE. resultenumOne of: PASS, FAIL, NOT_APPLICABLE. rationalestringExplanation of why this rule passed, failed, or was not applicable. verbatimslist[string]Transcript snippets supporting the evaluation result. Manifest File (manifest_signed_url → manifest.json) The manifest file is a single JSON object describing the export partition. It is written alongside the data file after the nightly export completes successfully. The schema is defined by AgentQAExportManifest. FieldTypeDescription tenant_idstringThe Ema tenant that owns this export. persona_idstringThe AI Employee persona for this export partition. datestringCalendar date of the export partition in YYYY-MM-DD format. window_startstringISO 8601 UTC start of the export window (inclusive). window_endstringISO 8601 UTC end of the export window (exclusive). row_countintegerNumber of call records written to the data file. 14.4 Error Codes HTTP CodeReason 400 Bad RequestInvalid persona_id format or other malformed request parameters. 401 UnauthorizedMissing or invalid Authorization header. 403 ForbiddenCredentials do not have edit-level permission to access the specified persona. 404 Not FoundPersona does not exist, or no export is available for the requested date. 422 Unprocessable Entitydate is not in YYYY-MM-DD format, or is today/future (must be a past UTC date). 400 Bad RequestThe requested date is older than your tenant's data retention window -- see 2.8 Additional Configuration Tab Settings for retention periods. This applies regardless of whether a partition for that date still physically exists. 500 Internal Server ErrorUnexpected server-side error. 14.5 Rate Limits A rate limit of 1 query per second is enforced on this API. 14.6 Sample Python The snippet below downloads and parses agent_qa_export.jsonl from the presigned URL returned by the API. import json import urllib.request # Step 1 — call the API to get the presigned URLs req = urllib.request.Request( "https://api.<region>.ema.co/api/agent-qa/get_daily_data" "?persona_id=<persona_id>&date=2025-06-01", headers={ "Authorization": "Bearer <token>", "x-persona-id": "<persona_id>", }, ) with urllib.request.urlopen(req) as resp: urls = json.load(resp) signed_url = urls["signed_url"] manifest_signed_url = urls["manifest_signed_url"] # Step 2 — download and parse the JSONL data file records = [] with urllib.request.urlopen(signed_url) as resp: for line in resp: line = line.strip() if line: records.append(json.loads(line)) # Step 3 — work with the records for record in records: resource_id = record["resource_id"] agent_id = record["agent_id"] final_score = record.get("final_score") sentiment = record.get("sentiment") resolution = record.get("resolution_status") rule_results = record["rule_results"] insights = record["insights"] print(f"{resource_id} | agent={agent_id} | score={final_score} | {sentiment} | {resolution}") for rule in rule_results: print(f" [{rule['result']}] {rule['rule_name']} (weight={rule['rule_weight']})") for insight in insights: print(f" [{insight['insight_type']}] {insight['driver']} — {insight['category']}") # Step 4 — download and parse the manifest with urllib.request.urlopen(manifest_signed_url) as resp: manifest = json.load(resp) print(f"Export date : {manifest['date']}") print(f"Window : {manifest['window_start']} → {manifest['window_end']}") print(f"Row count : {manifest['row_count']}") 14.7 On-Demand Current-Day Export The nightly export (above) always covers a past, completed UTC day. To pull data from the current calendar day before the next nightly run, request the live export from the Audit tab's export action. It's delivered asynchronously rather than as a direct download, since a busy day's export can take up to a minute to build: Requesting the export starts a background build and returns a request ID immediately -- there's no waiting on the request itself. The UI polls status until the build completes. Once complete, a signed download URL is provided, valid for 1 hour. Today's data is a partial snapshot -- calls still being processed won't appear until a later export. This is expected: the current-day export is for freshness, not completeness. Use the nightly export for a fully settled day.

================================================================================
# Transcript Ingestion API
URL: https://builder.ema.ai/agent-qa/api-transcript-ingestion
================================================================================

Transcript Ingestion API The Transcript Ingestion API uploads a pre-existing text transcript for processing by the Agent QA AI Employee. Use this endpoint when audio is not available and you already have the conversation transcript in JSON, XML, or HTML format. If you have an audio file instead, use the Audio Ingestion API. 13.1 Authentication & Headers All requests require the same headers as the Audio Ingestion API: HeaderTypeRequiredDescription AuthorizationstringYesBearer token (e.g., Bearer <token>) x-persona-idUUIDYesThe unique identifier of the Agent QA AI Employee (persona). 13.2 Upload Transcript PropertyValue URL{base_url}/api/v1/external/upload/transcript HTTP MethodPOST Content-Typeapplication/json Body Fields FieldTypeRequiredDescription formatstringYesFormat of raw_transcript. Supported values: json, xml, html. raw_transcriptstringYesFull transcript serialised as a string in the specified format. See format examples below. agent_idstringYesIdentifier of the human agent associated with the recording. agent_emailstringYesThe human agent's email. Used for permissioning. resource_idstringYesExternal identifier (e.g., Call ID from your telephony provider). languagestringNoLanguage of the transcript. timestampstringYesCall timestamp. Values without timezone information are treated as UTC. case_idstringNoTicket/case ID associated with the call. customer_surveyJSONNoCustomer satisfaction/dissatisfaction survey data. agent_tenureintegerNoTenure of the associated agent in days. json format A JSON array where each element is one utterance. The time field is optional and accepts ISO 8601, HH:MM:SS, HH:MM, and common date-time variants. When omitted, all utterances are assigned a timestamp of 0. [ { "time": "09:15:00", "role": "Agent", "text": "Hello, how can I help you?" }, { "time": "09:15:05", "role": "Customer", "text": "I have an issue with my account." } ] xml or html format An XML chat document. The time attribute is optional. <chat> <message time="09:15:00" role="Agent">Hello, how can I help you?</message> <message time="09:15:05" role="Customer">I have an issue with my account.</message> </chat> Success Response (200 OK) { "file_id": "550e8400-e29b-41d4-a716-446655440000", "file_name": "resource_id_123", "status": "UPLOAD_COMPLETED" } 13.3 Error Codes HTTP CodeReason 400 Bad RequestMissing headers, invalid UUID format, unsupported format, or missing agent_id. 403 ForbiddenCredentials do not have permission to access the specified AI Employee. 429 Too Many RequestsRate limit exceeded. Retry with exponential backoff. 500 Internal Server ErrorUnexpected server-side error. 13.4 Rate Limits A rate limit of 10 queries per second is enforced on the data upload API. 13.5 Sample Python import requests import time import json BASE_URL = "https://api.<region>.ema.co" # replace with your domain AUTH_TOKEN = "YOUR_BEARER_TOKEN" AI_EMPLOYEE_ID = "YOUR_AI_EMPLOYEE_UUID" headers = { "Authorization": f"Bearer {AUTH_TOKEN}", "x-persona-id": AI_EMPLOYEE_ID, } def upload_transcript(transcript, agent_id, agent_email, resource_id, timestamp, max_retries=3): """Uploads a text transcript for a specific AI Employee. transcript: list of dicts with keys: time (optional), role, text. """ url = f"{BASE_URL}/api/v1/external/upload/transcript" payload = { "format": "json", "raw_transcript": json.dumps(transcript), "agent_id": agent_id, "agent_email": agent_email, "resource_id": resource_id, "timestamp": timestamp, } for attempt in range(max_retries + 1): response = requests.post(url, headers=headers, json=payload) if response.status_code == 200: return response.json() if response.status_code == 429 and attempt < max_retries: retry_after = int(response.headers.get("Retry-After", 2 ** attempt)) time.sleep(retry_after) continue print(f"Failed! Status: {response.status_code}") print(f"Error: {response.text}") return None if __name__ == "__main__": result = upload_transcript( transcript=[ {"time": "09:15:00", "role": "Agent", "text": "Hello, how can I help you?"}, {"time": "09:15:05", "role": "Customer", "text": "I have an issue with my account."}, {"time": "09:15:10", "role": "Agent", "text": "I'd be happy to help with that."}, ], agent_id="human_agent_001", agent_email="human_agent_001@email.com", resource_id="resource_id_456", timestamp=time.strftime("%Y-%m-%d %H:%M:%S"), ) if result: print(f"New File ID: {result.get('file_id')}")

================================================================================
# Reviewing Interactions (The Audit Tab)
URL: https://builder.ema.ai/agent-qa/audit
================================================================================

Reviewing Interactions (The Audit Tab) The Audit tab is where you review individual evaluated interactions. This is the starting point for daily QA work -- finding calls to review, examining scorecards, reading transcripts, and submitting feedback. 4.1 Navigate the Audit Tab Log in to Ema at app.ema.co Navigate to your Agent QA AI Employee Click the Audit tab The list syncs automatically, and shows when it last did so (e.g. "Synced a few seconds ago" or "Not synced yet"). Click Refresh at any time to pull the latest data without waiting. Each row in the interaction list displays: FieldDescription Interaction DetailsCombined column showing the Interaction ID (resource_id, truncated to first 12 characters with # prefix) and the Agent ID displayed below it. A New badge appears next to interactions you haven't opened yet, and clears once you view that interaction's details. DurationCall length in seconds QA StatusThe current state of the evaluation QA ScoreOverall score out of 100. If the score has not been computed yet, it displays as "--". Call Time (UTC)When the call actually took place. Immutable -- unaffected by reruns. Ingested At (UTC)When the interaction was last processed by Ema. Normally the same as when it was first ingested, but a rerun (see 4.3 Rerunning an Interaction) updates this timestamp and floats the row to the top of the list, while Call Time stays fixed. FeedbackCount of feedback items submitted on this interaction's scorecard. QA Status Values StatusWhat It Means QA completedEvaluation is finished and the score is available. Click in to see full details. QA in progressThe system is still processing this interaction. Check back shortly. QA failedSomething went wrong during processing. Ema automatically retries a failed or stuck interaction internally for a period before treating it as permanently failed. If it's still failed after that, use Rerun (4.3) to trigger it manually, or check audio quality, file format, or contact your administrator. A transcript missing an agent turn, missing a customer turn, or with no utterances at all cannot be evaluated. These rows show QA failed with a status-cell tooltip and, in the detail view, a "Could not evaluate this interaction" empty state naming the specific reason -- rather than being silently scored. 4.2 Filters and Sorting Available Filters FilterDescription Date rangeCustom date range (UTC). Presets: Today, Last 7 Days, Last Week, Last 14 Days, Last 30 Days, Last Month, or custom range. AgentDropdown to select a specific agent or view all agents. Interaction IDText search field to find a specific call by resource ID (UCID). QA StatusFilter by evaluation status. QA ScoreFilter by preset score bands: Auto-fail (0), Low (1-50), Medium (51-75), High (76-100). Sorting Options Sort ByDirections Call Date (default)Ascending or Descending Call LengthAscending or Descending Pagination Results display 25 interactions per page. Navigation uses token-based pagination. 4.3 Rerunning an Interaction Permission required: Builder, Manager, or Admin. A rerun re-processes an interaction end to end -- re-transcribing/re-redacting and re-scoring -- and refreshes the same row in place with new verdicts, score, insights, and CSAT. Use it after editing a rule, fixing a processing issue, or when an interaction is stuck or failed. In the Audit tab, select one interaction, or multi-select any number of them. Click Rerun. Confirm the warning -- rerunning deletes any existing feedback on the selected interaction(s). For a multi-select, the warning states how many of the selected interactions have feedback that will be lost. The row shows "QA in progress" while it reprocesses, then settles with refreshed results. Its Ingested At timestamp updates to the rerun time (floating it to the top of the list), while Call Time never changes. An interaction can only be rerun while its raw source (audio or transcript) is still within its data-retention window -- see 2. Setting Up Agent QA for retention periods. Interactions past that window are shown blocked/non-selectable, since there is no longer a source to re-process. 4.4 View Interaction Details Click View Details on any interaction to open the detailed view. Interaction Summary A collapsible panel at the top of the detail view gives an AI-generated plain-language summary of the call -- what the customer needed, what the agent did, and how it was resolved. It uses the same PII redaction as the transcript, so sensitive values appear as redaction placeholders (e.g. a masked name or account number) rather than the original text. Below the summary, the detail view has the following tabs: Scorecard Tab The core evaluation view. A summary bar at the top shows the total parameter count with Pass and Fail totals. FieldDescription ResultColor-coded badge -- Pass (green), Fail (red), or N/A (gray) Parameter name and categoryWhat was being evaluated and which group it belongs to Pass/Fail instructionThe evaluation criteria used for this parameter RationaleDetailed, plain-language explanation of why the parameter passed or failed. This is the most important field for understanding a score. VerbatimsClick the "Source" accordion to expand and see the exact transcript excerpts used as evidence Transcript Tab Full conversation text with speaker labels and timestamps. Every speaker the transcript carries is shown under its own label -- not just Agent and Customer. A supervisor, an IVR/bot segment, or an external third party (e.g. a hotel receptionist or interpreter brought into the call) appears under its own descriptive label. QA scoring still evaluates only the interaction's designated agent; every other party, including third parties, is treated as context. The Transcript tab does not currently have an in-panel search feature. Strengths Tab Positive agent behaviors identified during the interaction. FieldDescription DriverThe positive behavior identified (e.g., "Clear policy explanation"), displayed as bold title CategoryThe broader behavioral category (e.g., "Communication Skills"), displayed as a badge JustificationWhy this was identified as a strength, labeled "Key insight" in the UI Opportunities Tab Areas for improvement with coaching recommendations. FieldDescription DriverThe issue identified (e.g., "Did not confirm customer understanding"), displayed as bold title CategoryThe broader behavioral category (e.g., "Active Listening"), displayed as a badge JustificationWhy this was identified as an opportunity and what could have been done differently CSAT Mapping Tab Shows Ema's AI-derived customer satisfaction analysis for the interaction, plus any customer-submitted survey feedback ingested via the CSAT Ingestion API. FieldDescription Overall SummaryA banner giving the overall sentiment (positive, negative, or neutral) and a plain-language summary of the customer's experience. Customer SatisfactionSentiment badge, evaluation text, and supporting transcript verbatims (via the "Source" accordion) for how satisfied the customer appeared. Issue ResolutionSentiment badge, evaluation text, and sources for whether the customer's issue was resolved. Call to ActionSentiment badge, evaluation text, and sources for any follow-up action expected from the call. Customer BehaviorSentiment badge, evaluation text, and sources describing how the customer behaved during the call. Customer FeedbackA survey score or comment submitted via the CSAT Ingestion API. A value of 1-5 renders as a star rating; anything else (including an emoji-derived score) renders as text. Hidden if no survey feedback was submitted. If Ema has not yet produced a CSAT analysis for this interaction, the tab shows an empty state instead of the fields above. Additional Data Agent Talk Time, User Talk Time, and Dead Air are computed in the backend and stored in the database, but are not currently displayed in the evaluation details drawer in the UI. FieldDescription Agent Talk TimeHow much of the call the agent was speaking User Talk TimeHow much the customer was speaking Third-Party Talk TimeHow much any other speaker (supervisor, IVR/bot, external third party) was speaking. Only populated when the transcript carries a third party and per-utterance timestamps. Dead AirPeriods of silence during the call

================================================================================
# Core Concepts
URL: https://builder.ema.ai/agent-qa/core-concepts
================================================================================

Core Concepts Before diving into setup or daily use, it helps to understand the key ideas behind Agent QA. 1.1 How Agent QA Works Agent QA follows a multi-stage pipeline: Audio uploaded via the ingestion API Transcribed -- speech-to-text with PII masking and speaker diarization GWE workflow evaluates the transcript against your QA parameters Callback processes results -- extracts rule outcomes, contact reasons, sentiment, and insights QA score computed -- weighted average with critical-rule auto-fail Score and Scorecard saved and visible on the Audit tab Every call goes through this pipeline automatically. The entire flow -- from audio upload to a completed scorecard -- typically takes 2 to 5 minutes. 1.2 Key Terms TermWhat It Means AI EmployeeA configured workflow on the Ema platform. Agent QA is a type of AI Employee. You may also see this called a "persona" in technical contexts. Parameter (also called a "rule")A single quality criterion used to evaluate agent performance. Examples: "Greeting," "Empathy," "Issue Resolution." Each parameter has pass/fail criteria and a weight. ScorecardThe detailed breakdown of an interaction's evaluation -- one result per parameter, with rationale and transcript evidence. QA ScoreA number from 0 to 100 representing overall quality. Calculated from weighted parameter results. Auto-LearningThe system that generates and refines your QA parameter instructions using a set of human-graded example calls (your "golden dataset"). Continuous LearningThe ongoing process of improving evaluation accuracy through feedback submitted by your review team. Golden DatasetA collection of call recordings with verified human evaluations (Pass/Fail/N/A per parameter) used to calibrate Auto-Learning. Also referred to as "label data" in the setup interface. Critical ParameterA parameter where failure automatically sets the entire interaction score to 0, regardless of other results. Used for non-negotiable standards like regulatory compliance. N/A (Not Applicable)When a parameter does not apply to a particular call. N/A results are excluded from scoring entirely -- they do not help or hurt the score. Contact ReasonA three-level categorization of why customers are calling: L1 (broad category), L2 (subcategory), L3/Call Driver (specific reason). UCIDUnique Call Identifier -- the unique ID for each call recording. VerbatimA direct quote from the transcript used as evidence for an evaluation decision. 1.3 Evaluation Mechanisms Each parameter uses one of three mechanisms that determine what data is consulted during evaluation: MechanismWhat It ChecksWhen to Use Transcript OnlyThe call transcript aloneGreeting, empathy, communication skills -- anything observable from the conversation Knowledge VerifiedTranscript + your knowledge base documentsInformation accuracy, policy compliance -- anything requiring verification against reference materials Action BasedTranscript + actions in external systems (CRM, ticketing)Case creation, ticket updates -- anything requiring verification of what the agent did in their tools 1.4 The Daily QA Loop Agent QA delivers the most value when used as a continuous cycle: Audit -- review interactions Metrics -- spot trends Insights -- identify coaching priorities Feedback -- correct evaluations Improve -- refine rules Back to Audit Each stage feeds into the next. Reviewing interactions surfaces evaluation disagreements. Metrics reveal patterns. Insights pinpoint coaching priorities. Feedback corrects individual evaluations. Improvements refine the underlying rules. 1.5 Languages Supported Agent QA supports transcription and evaluation for a wide range of languages including: Arabic, Belarusian, Bengali, Bosnian, Bulgarian, Catalan, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, Flemish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Kannada, Korean, Latvian, Lithuanian, Macedonian, Malay, Marathi, Norwegian, Persian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swedish, Tagalog, Tamil, Telugu, Turkish, Ukrainian, Urdu, and Vietnamese.

================================================================================
# Feedback and Continuous Learning
URL: https://builder.ema.ai/agent-qa/feedback
================================================================================

Feedback and Continuous Learning Continuous Learning improves evaluation accuracy over time through reviewer feedback. Unlike Auto-Learning (which uses a batch of golden data during initial setup), Continuous Learning incorporates corrections incrementally as your team reviews evaluations. 8.1 Submitting Feedback Permission required: CAN_SUBMIT_FEEDBACK (Metrics Viewer, SelfMetrics Viewer for their own interactions, Manager, or Admin) In the Audit tab, click View Details on an interaction In the Scorecard, find the parameter you want to comment on Click the thumbs down icon (disagree with evaluation) or thumbs up icon (agree) Enter a feedback comment explaining your assessment Click Submit What Makes Feedback Effective Good example: "The agent did say 'Team Portugal' at 0:15, which should count as company identification. Ensure that any variation of the company name in the opening counts toward this rule." Tips: Be specific about what happened in the call (reference timestamps if possible). Explain what the correct evaluation should be and why. Describe the general principle, not just the one-off correction. Avoid vague comments like "This is wrong." Rules for feedback management: Only the feedback creator can update or delete their own feedback Updating feedback resets its status to unprocessed, requiring re-moderation 8.2 Moderating Feedback Permission required: CAN_APPROVE_FEEDBACK (Manager or Admin) Navigate to the Audit tab and open the Accepted Feedback view Review pending (unprocessed) feedback items For each item: read the original evaluation result and rationale, read the feedback comment, check the transcript for context Click Accept to approve, or Reject to ignore Feedback Lifecycle StatusDescription UnprocessedSubmitted, awaiting moderation ApprovedAccepted by a moderator. Eligible for the Continuous Learning pipeline. ProcessedAlready consumed by the Continuous Learning pipeline. Will not be reused. IgnoredRejected during moderation. Visible but not used for learning. 8.3 Generating Improvement Suggestions Permission required: Manager or Admin. Once feedback has been approved for a rule, you can ask Ema to suggest an updated rule instruction directly from the Accepted Feedback view: Open the Accepted Feedback view. Rules with approved feedback are listed as cards, each showing the rule name, category, description, and a feedback-count badge. Click a rule's card to open the Feedback Selection Drawer, listing every approved feedback item for that rule as a checkbox (all pre-selected by default — deselect any you don't want to include). Click Suggest improvements. Ema analyzes the selected feedback and generates an updated rule instruction. A Suggested Improvements modal opens immediately with a loading state ("Generating suggestions... Ema is refining your QA instructions based on the latest feedback") while the pipeline runs. The pipeline runs through Queued/Running → Completed, Failed, or Timed Out. The modal polls automatically — you don't need to refresh or re-open it. A timed-out run can be re-submitted. One Improvement Run at a Time, Per Rule Only one improvement pipeline can run per rule at a time. If another Manager or Admin has already triggered one for the same rule, the drawer shows a banner instead of the checkboxes: "A pipeline has been started by [name] — please wait for it to complete." The Suggest improvements button is hidden until that run reaches a terminal state (Completed, Failed, or Timed Out). 8.4 Applying Improvements When the pipeline completes, the modal shows the original instruction and Ema's suggested instruction side by side — only the pass/fail instruction and the not-applicable (alternate-rule) instruction fields are shown; name, category, and weight are unchanged and not part of the suggestion. Review the suggested instructions against the originals. You can edit the suggested text directly in the modal before deciding. Click Update instruction to apply the suggestion, or Cancel to discard it with no changes made. On success, a confirmation toast appears with a link back to the Configuration tab. The updated instructions take effect immediately for all new evaluations. Applying an improvement does not automatically update the rule's auto-learn accuracy score. To recalibrate accuracy, re-run Auto-Learning (see 2. Setting Up Agent QA). Manual rule editing from the Configuration tab's QA Parameters remains available as before and is unaffected by this pipeline. 8.5 Continuous Learning Governance API To pull a persona's feedback funnel and auto-learn accuracy into an external BI tool or governance report, use the Rule Metrics API. This requires the same elevated persona access as other Agent QA data-pull APIs. PropertyValue URL{base_url}/api/agent-qa/rule_metrics HTTP MethodGET Query Parameters FieldTypeRequiredDescription persona_idUUIDYesThe unique identifier of the AI Employee (persona). start_datestringNoUTC date in YYYY-MM-DD format. Inclusive start of the window. Omit both dates for all-time. end_datestringNoUTC date in YYYY-MM-DD format. Inclusive end of the window. Example Request curl -X GET \ "{base_url}/api/agent-qa/rule_metrics?persona_id=<persona_id>&start_date=2026-07-01&end_date=2026-07-28" \ -H "Authorization: Bearer <token>" Response A successful response (200 OK) returns one object per active rule: FieldTypeDescription persona_idstringEchoes the requested persona. start_date / end_datestringThe resolved date window. ruleslist[object]One entry per active rule. See below. Rule Entry FieldTypeDescription rule_namestringThe QA parameter's name. auto_learn_accuracyfloat or null0–1 accuracy from the rule's most recent auto-learn run. null if the rule has no auto-learn history yet — for example, it was added manually or renamed since the last run. givenintegerTotal feedback submitted for this rule in the window. approvedintegerFeedback with status Approved or Processed. improvedintegerFeedback with status Processed — i.e., actually incorporated by Continuous Learning. Use given → approved → improved as the feedback funnel for a rule, and compare it against auto_learn_accuracy to see whether feedback volume is translating into measurable accuracy gains.

================================================================================
# Glossary
URL: https://builder.ema.ai/agent-qa/glossary
================================================================================

Glossary TermDefinition Action Based RuleA QA parameter that verifies actions in external systems (CRM, ticketing). Agent (Platform)A modular AI component within Ema that performs a specific task (transcription, categorization, rule validation). Agent (Contact Center)A human customer service representative whose calls are evaluated by Agent QA. AI EmployeeA configured workflow on the Ema platform. Agent QA is an AI Employee template. Also called a "persona" internally. Auto-FailWhen a critical parameter fails, the interaction automatically receives a score of 0. Auto-LearningBatch calibration that generates and refines parameter instructions from golden data. Call DriverThe L3 (most specific) level of contact reason categorization. Channel MapA JSON mapping of audio channels to speakers (Agent/Customer) in stereo recordings. Continuous LearningIncremental improvement of evaluation accuracy through moderated feedback. Contact ReasonThree-level categorization of why customers call: L1, L2, L3/Call Driver. Critical ParameterA parameter where failure automatically scores the interaction at 0. CSATCustomer Satisfaction -- predicted by AI analysis of the interaction. Dead AirSilence during a call where neither party is speaking. Measured in seconds. DiarizationSeparating audio into segments by speaker (Agent vs. Customer). EmaFusion™Ema's multi-model AI architecture that selects the optimal LLM for each task. Golden DatasetCall recordings with verified human evaluations used for Auto-Learning calibration. GWE (Generative Workflow Engine)Ema's orchestration layer coordinating multiple agents in a workflow. InsightA pattern identified across multiple interactions. Types: Strength, Opportunity, Bug, Feedback, Competitor. InteractionA single customer service call processed by Agent QA. Knowledge BaseDocuments (policies, procedures, FAQs) that Ema references for Knowledge Verified rules. Knowledge Verified RuleA parameter that cross-references transcript content against knowledge base documents. N/A (Not Applicable)Evaluation result indicating the parameter does not apply to a particular call. Excluded from scoring. Non-Resolution ReasonCategorization of why a customer's issue was not resolved (L1, L2). ParameterA single QA evaluation criterion with pass/fail criteria and a weight. Also called a "rule." PII (Personally Identifiable Information)Sensitive data detected and masked. Redacted by default via two independent passes, so PII missed by one pass can still be caught by the other. QA ScoreWeighted overall score (0-100). Formula: (passed_weight_sum / applicable_weight_sum) x 100. Set to 0 on auto-fail. QA FormCSV file defining evaluation parameters, criteria, weights, and criticality. Resource IDExternal identifier for a call. Corresponds to resource_id in the API and UCID in golden data. ScorecardSummary view of all parameter evaluations for a single interaction. Sentiment AnalysisAI analysis of customer emotional state: POSITIVE, NEGATIVE, or NEUTRAL. Transcript Only RuleA parameter evaluated based solely on conversation content. UCID (Unique Call Identifier)Unique identifier for each call recording. Matches resource_id in the API. VerbatimA direct transcript quote supporting an evaluation rationale. WeightNumerical value indicating a parameter's importance in scoring. Must be > 0. Workflow BuilderVisual interface for creating and modifying AI Employee workflows.

================================================================================
# Imports, Genesys, and Agent Mapping
URL: https://builder.ema.ai/agent-qa/imports
================================================================================

Imports, Genesys, and Agent Mapping The Imports tab is where conversations enter Agent QA. This section covers every way to bring calls in -- pulling them automatically from Genesys Cloud, uploading a batch of files yourself, or re-processing interactions you already imported -- and the agent-mapping configuration all three depend on. Imports covers bulk ingestion from the builder interface. To push interactions one at a time from your own systems, use the Audio Ingestion API or the Transcript Ingestion API instead. 3.1 How Imports Work The tab has two sub-tabs: Sub-tabWhat It Does ImportsLists every import job -- name, source, call window, status, progress, and last update. Click New import to start one. Agent MappingMaps the agent identifier your source system uses to a known Ema employee. See Agent Mapping. The list syncs on its own and shows how fresh it is -- "Synced a few seconds ago", or "Not synced yet" before the first sync. Click Refresh at any time to pull the latest status without waiting for the next sync. Import Types TypeDescription Genesys CCaaSPull call recordings automatically from Genesys Cloud for a date range. See Running a Genesys Import. Bulk upload -- audioUpload a batch of recordings from your computer with a metadata CSV. See Bulk File Upload. Bulk upload -- transcriptsUpload a batch of transcripts from your computer with a metadata CSV. Re-runRe-process interactions you already imported against your current rules. See Re-running Interactions. Whichever route you use, the back half of the pipeline is the same: Ema attributes each conversation to an employee, hands the file to transcription, and evaluates it. Results appear in the Audit tab, which remains the source of truth for QA outcomes. The Imports tab tracks a file only up to the point it is handed off for processing. Single interactions pushed through the ingestion APIs also appear in the job list, labelled Single file upload. They are shown for visibility -- there is nothing to configure. 3.2 Connecting Genesys Cloud Genesys Cloud is the first Contact-Center-as-a-Service (CCaaS) provider Agent QA connects to. Connect it once, then start imports whenever you need them. What You Need From Genesys Ema authenticates with the OAuth2 Client Credentials grant. In your Genesys org, create an OAuth client of type Client Credentials Grant and note its credentials. ValueDetail Client IDFrom the OAuth client you created in Genesys. Client secretFrom the same OAuth client. Treat it as a credential -- Ema stores it encrypted. RegionThe Genesys region your org runs in. See Supported Genesys Regions. There is no browser redirect, consent screen, or callback URL in this flow, and no refresh token to manage. Ema requests a fresh access token with the stored credentials whenever it needs one. If you rotate the secret in Genesys, update it in Ema or imports will start failing to authenticate. Supported Genesys Regions Your region determines which Genesys hosts Ema talks to. Pick the one matching your Genesys org. RegionCodeGenesys Domain Americas (US East)us-east-1mypurecloud.com Americas (US East 2)us-east-2use2.us-gov-pure.cloud Americas (US West 2)us-west-2usw2.pure.cloud Americas (Canada Central)ca-central-1cac1.pure.cloud Americas (Sao Paulo)sa-east-1sae1.pure.cloud EMEA (Ireland)eu-west-1mypurecloud.ie EMEA (London)eu-west-2euw2.pure.cloud EMEA (Frankfurt)eu-central-1mypurecloud.de EMEA (Zurich)eu-central-2euc2.pure.cloud EMEA (UAE)me-central-1mec1.pure.cloud Asia Pacific (Mumbai)ap-south-1aps1.pure.cloud Asia Pacific (Tokyo)ap-northeast-1mypurecloud.jp Asia Pacific (Seoul)ap-northeast-2apne2.pure.cloud Asia Pacific (Osaka)ap-northeast-3apne3.pure.cloud Asia Pacific (Sydney)ap-southeast-2mypurecloud.com.au Verifying the Connection Open New import and choose Genesys. If the connection is healthy, the window picker appears. If it is not, the drawer says so instead: MessageWhat It Means Connect this source to start an importNo active connection exists for your organisation. Connect Genesys from the Integrations page, then come back. Couldn't check your connectionEma could not reach the connector to confirm its state. Retry; if it persists, contact support. 3.3 Running a Genesys Import An import pulls every voice recording in a time window and queues it for evaluation. Recordings pulled from Genesys must be in WAV format. Support for additional CCaaS providers, and for other file formats over this path, is on the roadmap. To bring in other formats today, use Bulk File Upload. Window Rules All times are in UTC, including the presets. RuleDetail Maximum window24 hours per import. To cover a longer period, submit several imports. Minimum ageThe end of the window must be at least 1 hour in the past. Recordings for very recent calls may not be available from Genesys yet. Oldest windowCalls up to 1 year old. Starting an Import Go to Imports and click New import. Choose Genesys CCaaS. Pick a call window -- use a preset (Last 24 hours, Today (UTC), Yesterday (UTC)) or set a Custom range. Optionally give the import a name, such as "May 28 -- overnight shift". Names make the job list readable later and can be edited at any time. Under Advanced Settings, optionally set a language. Leave it on Auto-detect unless every call in the window is in the same language -- setting it explicitly transcribes all of them in that language rather than detecting per call. Click Submit. The job is queued immediately and the drawer closes. You do not need to wait for it, and you can start other work or queue further imports right away. Submitting is retry-safe. If the request times out or you click twice, Ema returns the job it already created rather than starting a duplicate. What Happens Next Queued. The job waits for a free processing slot. Listing. Ema pages through Genesys and creates one tracked row per matching call. Rows that cannot be ingested end here -- a call with no agent participant, or a transferred call involving more than one agent. Agent mapping. Each call carries an agent identifier from Genesys. Ema matches it to an employee using your agent-mapping configuration. Your input, only if needed. If some agents are not recognised, the job pauses. See Resolving a Paused Import. Download and hand-off. Ema fetches each recording into Ema storage and hands it to transcription at a paced rate, so one large import cannot crowd out other work. Triggered. Every recording has been handed off. QA scores appear in the Audit tab as evaluation completes. 3.4 Bulk File Upload Use bulk upload when your calls are not in a connected CCaaS provider, or when you simply have a folder of files to evaluate. You supply the recordings or transcripts plus a CSV describing them. Limits and Formats RequirementDetail Files per importUp to 500. A selection that would take you over the cap is rejected in full, not partially accepted. Maximum file size25 MB per file Audio formatsMP3, WAV, Opus, OGG, or WebM Transcript formatsJSON, XML, or HTML MetadataOne CSV, one row per file An import is either audio or transcripts, not both. Choose the type when you start the wizard -- a transcript in an audio import (or the reverse) is rejected at the check step. The Upload Wizard Upload files. Select your recordings or transcripts and the metadata CSV. Files upload as you go; you can keep adding until you hit the cap. Map columns. Match each CSV header to an Ema field. Headers that already match a field name are mapped for you. Any column you leave unmapped is preserved as extra metadata on the interaction rather than discarded. Check. Ema validates every row against the files you uploaded and highlights problems inline. See Fixing Upload Errors. Launch. Submit the import. It joins the same queue as a Genesys import and behaves identically from that point on. Metadata CSV Columns ColumnRequiredDetail FilenameYesThe uploaded file's name, for example call-12345.mp3. The extension is stripped when matching to the file. Agent IDYesThe agent identifier from your source system. This is what agent mapping resolves. Agent emailYesSSO email. Used for per-agent permissioning. Call timestampYesISO 8601 in UTC, for example 2026-05-27T14:32:00Z. A value with no timezone is read as UTC. ChannelsAudio only1 for mono, 2 for stereo. There is no default -- an empty cell is an error. Channel mapStereo onlyRequired when Channels is 2. JSON, for example {"0":"Agent","1":"Customer"}. LanguageNoTranscribe this interaction in a specific language instead of auto-detecting. Case IDNoYour ticket or case reference. Agent tenure (days)NoHow long the agent had been in the role, used for tenure-based analysis. Example: filename,agent_id,agent_email,call_timestamp,channels,channel_map,case_id call-12345.mp3,A-4471,sarah.jones@example.com,2026-05-27T14:32:00Z,2,"{""0"":""Agent"",""1"":""Customer""}",CS-88213 call-12346.mp3,A-4472,mike.chen@example.com,2026-05-27T15:04:11Z,1,,CS-88219 Fixing Upload Errors The check step reports two kinds of problem, and nothing is committed while any remain. ProblemWhat It MeansFix File not foundThe CSV names a file that was not uploaded, or whose upload did not finish.Upload the missing file, or skip the row. Wrong file typeThe file does not match the import type -- a transcript in an audio import, or the reverse.Remove the file, or start the right kind of import. Missing required valueA required column is empty for that row.Fill the cell in the check step. Wrong formatA value cannot be read as expected -- a non-numeric channel count, an unparseable timestamp.Correct the value in the check step. Skipping a row excludes it from the import entirely -- it is not validated, not uploaded, and not evaluated. Use it when a file is genuinely unavailable and you would rather proceed without it than hold up the whole batch. 3.5 Re-running Interactions Re-run re-processes interactions you have already imported against your current rules. Use it after changing QA parameters, or to retry interactions that failed. Click New import, then Re-run interactions. Choose which interactions: All interactions in the range, Failed interactions only, or Interactions with incorporated feedback. Set the ingestion window (UTC). The default is the last 7 days. Submit. Re-running is billable. Each interaction is processed end to end, exactly like a new evaluation. Re-running deletes reviewer feedback. Any feedback on the selected interactions is removed -- both approved and pending. If that feedback has not yet been incorporated through continuous learning, it cannot be recovered. When an Interaction Cannot Be Re-run Re-run can also be started per row from the Audit tab. Where the action is unavailable, hovering it explains why: ReasonWhat To Do Evaluation in progressWait for the current evaluation to finish, then retry. Already queued for processingA re-run is already pending for this interaction. Past its retention periodThe raw call file has been deleted under your data-retention settings, so there is nothing left to re-process. See Setting Up Agent QA for retention configuration. Re-run limit reachedThe last 3 re-runs of this call failed. Investigate the underlying failure rather than retrying again. 3.6 Job Statuses and Progress Job Statuses StatusMeaning DraftA bulk upload you started but have not submitted. Click Resume to continue where you left off. QueuedSubmitted, waiting for a free processing slot. Listing interactionsEma is enumerating matching calls from the source. Rows appear as they are found. Pending agent mappingCalls have been listed and are being matched to employees. Awaiting user inputOne or more agents could not be matched. The job is waiting on you. Ready to runEvery file has a decided outcome; waiting for a free processing slot. ProcessingRecordings are being fetched and handed off for transcription and evaluation. TriggeredSuccess. Every file has been handed off. QA results appear in the Audit tab. No interactions foundThe source had nothing matching your window. Nothing to do. SkippedEvery file in the job was skipped. ExpiredThe job sat awaiting your input for more than 24 hours. Start a new import for the same window. FailedThe job could not complete. Contact support if it recurs for the same window. Triggered means the import succeeded, not that grading is finished. The Imports tab's job is to get conversations into processing. Transcription and evaluation continue afterwards, and their outcome is shown in the Audit tab. Progress Counters Each job shows how its files are distributed. The four counts always add up to the total: CounterWhat It Counts SucceededFiles that reached a final outcome without failing -- handed off, skipped by you, or a recording that was never available. FailedFiles that ended in an error. In progressFiles still moving through the pipeline. AwaitingFiles waiting on an agent mapping from you. Why a Job Sits in Queued Ema limits how many imports run at once -- up to 10 per AI Employee and 40 per organisation -- and rotates work fairly across AI Employees and customers. A large import is interleaved with everything else rather than monopolising the system, so a queued job is normal during busy periods and needs no action. Jobs waiting purely on capacity never expire. 3.7 Agent Mapping Every conversation must be attributed to a specific employee before it can be evaluated. Agent mapping is the link between the agent identifier your source system uses -- a Genesys user ID, or the Agent ID column in your CSV -- and a known Ema employee. The Identity Schema Open Schema settings (the gear icon on the Agent Mapping tab) to define what an agent record looks like for your organisation. SettingDetail Primary identifier labelWhat you call your own agent ID, for example "BMS ID". This renames the field everywhere it appears; it does not change any data. Custom attributesExtra fields to capture per agent, such as Team, Country, or Tenure. Each has a type of Text, Number, or Date. The type is fixed once created. Define the schema before your first import. Until it exists, agents cannot be mapped at all -- the resolve step will block and point you back here. Declaring your custom attributes early also means every later resolve form captures them inline, so records do not land half-filled. Removing a custom attribute deletes its values from every existing mapping row. Ema tells you how many rows are affected before you save. What a Mapping Row Contains FieldRequiredDetail Source IDYesThe agent identifier from your source system, for example a Genesys user ID. UPNYesThe employee's SSO email. This is what drives per-agent permissions. Primary identifierYesYour own agent ID, under whatever label you set in the schema. Agent nameNoDisplay name. Effective fromYesStart of the validity window, in UTC. Blank means today. Effective toNoEnd of the validity window, in UTC. Blank means open-ended. Custom attributesVariesWhatever you defined in the schema. Mappings are time-aware, which is what makes historical imports correct. If a source ID was reassigned to a different person in March, give the first mapping an Effective to of March and the second an Effective from of March. Calls from January are then attributed to the right employee even though you import them today. Uploading Mappings in Bulk Click Upload mapping for a four-step wizard. Choose CSV. Up to 5 MB and 10,000 rows. Map columns. Match your headers to Ema's fields. Ema suggests obvious matches; you can override any of them. Pick mode. See the table below. Review. Ema validates the file and shows exactly what would change before anything is written. ModeEffect AdditiveAdds new rows and updates matching ones. Rows not in the CSV are left alone. Replace allClears the existing mappings and inserts the CSV from scratch. Any row not in the file is removed. Replace all removes mappings that are not in your file. Always read the review step's counts before confirming -- it tells you how many rows would be added, updated, removed, and left unchanged, with samples of each. Upload Validation Errors block the upload. Warnings can be acknowledged and applied. IssueSeverityMeaning Required value missingErrorSource ID, UPN, or your primary identifier is empty. Invalid emailErrorThe UPN is not email-shaped. Wrong typeErrorA value does not match its attribute type -- text in a Number field, or a date that is not YYYY-MM-DD. Dates invertedErrorEffective to is earlier than Effective from. Overlapping windowErrorAnother row -- in this CSV or already saved -- covers the same source ID over an overlapping period. ReassignmentWarningThis source ID is already mapped to a different person over an overlapping window. Acknowledge it to overwrite the existing mapping. Duplicate columnErrorTwo CSV headers were mapped to the same Ema field. Downloading and Retiring Mappings ActionDetail Download mappingExports every mapping as CSV, ignoring whatever search filter is active. The usual way to bulk-edit is download, edit, re-upload. SearchMatches across source ID, your primary identifier, and agent name. RetireCloses the mapping's window by setting Effective to to today. The row stays visible, struck through, and still applies to imports of calls from within its window. Retire rather than delete when someone leaves. Deleting removes the link that past evaluations were attributed through; retiring keeps history intact and simply stops the mapping applying to new calls. 3.8 Resolving a Paused Import When an import finds agents it does not recognise, it pauses at Awaiting user input and shows how many agents need attention. Nothing is lost while it waits -- the calls that did match are already on their way. Using Resolve Agents Click Resolve agents on the job. You get one card per unrecognised agent, showing the source ID and the range of call times seen for it. Enter the UPN -- the employee's SSO email -- and your primary identifier. Set the validity window. The hints under each date field tell you the earliest and latest conversation for that agent; the window must cover the whole range or those calls stay unresolved after you save. Fill in any custom attributes your schema defines. Click Save & next to move to the following agent. Saving a mapping here also unsticks every other paused import waiting on that same agent, not just the one in front of you. If the source ID already maps to someone else over an overlapping window, Ema warns you and asks you to confirm. Confirming retires the existing mapping and replaces it with yours. Skipping and Resuming ActionEffect Skip for nowSets the card aside for this session only. Nothing is submitted and nothing changes -- use Undo skip to bring it back. Skip rows on the jobPermanently excludes those calls from the import. They are never evaluated. Once the last awaiting row is skipped or mapped, the job continues on its own. ResumeRe-runs agent matching for the job so mappings you added elsewhere -- on the Agent Mapping tab, or by CSV upload -- get picked up. A job left awaiting input expires after 24 hours and cannot be resumed. If that happens, add the missing mappings and submit a fresh import for the same window. 3.9 File Outcomes and Troubleshooting Open a job to see every file and its outcome. Some outcomes are dead ends by design rather than errors -- they do not mean the import failed. OutcomeWhat HappenedWhat To Do Awaiting user inputThe agent on this call is not mapped.Use Resolve agents, or skip the row. SkippedYou excluded this call from the import.Nothing. Re-import the window if you skipped it by mistake. Multiple agents detectedTwo or more agents handled the conversation, usually a transfer. Agent QA does not currently split a call between agents.Nothing today. Evaluate transferred calls through a separate upload if you need them scored. Recording not foundGenesys has no recording for this conversation.Check that recording was enabled for the queue at the time of the call. Recording not readyThe recording exists but Genesys has not finished preparing it.Re-import the window later. Recording archivedThe recording has been moved to archival storage in Genesys.Restore it in Genesys, then re-import. Multiple recordings availableThe conversation has more than one recording and Ema cannot tell which to evaluate.Upload the correct recording through bulk upload. Recording too largeThe audio exceeds the 25 MB limit.Compress or split the recording and upload it manually. ExpiredThe file waited more than 24 hours for an agent mapping.Add the mapping, then re-import the window. FailedEma could not fetch or hand off the file.Re-import the window. Contact support if the same files fail again. Use the search box inside a job to find a specific call by conversation ID, source agent ID, agent email, or your own agent ID, and the status filter to isolate everything that failed. 3.10 Permissions Access to the Imports tab is controlled by CAN_VIEW_IMPORTS, held by the Builder, Manager, and Admin roles. Metrics Viewer and SelfMetrics Viewer cannot see or start imports. For the full matrix, see Roles and Permissions.

================================================================================
# Using the Insights Dashboard
URL: https://builder.ema.ai/agent-qa/insights
================================================================================

Using the Insights Dashboard The Insights tab surfaces AI-generated patterns across all evaluated interactions. Unlike Metrics (which shows aggregate numbers), Insights tells you what is happening and why. Insights can be filtered by agent (via dropdown) and date range (same presets as the Audit tab). 7.1 Five Insight Categories Agent Performance: CategoryWhat It Surfaces Top StrengthsPositive agent behaviors identified across interactions OpportunitiesAreas needing improvement, with coaching recommendations Product Insights: CategoryWhat It Surfaces Product BugsTechnical issues surfaced from customer conversations Product FeedbackFeature requests and suggestions mentioned by customers Competitor Insights: CategoryWhat It Surfaces CompetitorsReferences to competitors in customer calls Product Bugs, Product Feedback, and Competitors are all generated by a single configurable agent in the standard template, not three separate mechanisms -- they're grouped here by what they surface, not by how they're produced. 7.2 Each Insight Contains ColumnDescription DriverHigh-level behavioral topic with instance count (e.g., "Information verification") CategorySub-category within the driver (e.g., "Active listening") Verbatim examplesRepresentative transcript snippets. The first verbatim is shown by default; click to expand for additional examples. InstancesA button showing the total count that opens the detail drawer 7.3 Insight Thresholds Not all insights are displayed. The system applies minimum thresholds to surface only meaningful patterns: Agent Performance insights (Strengths and Opportunities): ScopeMinimum Count Required Single agent>= 2 instances Team (all agents)>= 3 instances Product insights (Bugs and Feedback): Shown if the insight is in the top 20% by count OR has a count >= 5. Competitor Mentions: All mentions are displayed (count >= 1). 7.4 Viewing Insight Details Click the Instances button on any insight row to open a detail drawer showing: DetailDescription SummaryThe driver name with category badge and total instance count Matching instancesIndividual instance cards, each showing the UCID (linked to the Audit tab), justification, and source verbatims in an expandable accordion 7.5 Using Insights Effectively CategoryHow to Use It Top StrengthsShare with teams for positive reinforcement. Document best practices. OpportunitiesBuild targeted coaching plans. Prioritize by count -- higher counts = more widespread issues. Product BugsRoute to engineering and product teams. These are real customer pain points. Product FeedbackForward to product management as voice-of-customer data. CompetitorsShare with strategy and marketing. Track which competitors are mentioned most. 7.6 Coaching Reports Generate a personalized training document for an individual agent, tailored to their specific improvement areas: From the Insights tab, select the agent to generate a report for Ema analyzes that agent's QA feedback and insights A training document is produced, focused on that agent's specific improvement areas

================================================================================
# Using the Metrics Dashboard
URL: https://builder.ema.ai/agent-qa/metrics
================================================================================

Using the Metrics Dashboard The Metrics tab provides aggregate analytics across all evaluated interactions via an embedded dashboard. Use it for weekly and monthly quality reviews. 6.1 Overview KPIs Five key metrics appear at the top, each with period-over-period comparison: MetricWhat It Shows Interactions AuditedTotal processed calls with period-over-period comparison (e.g., 1,242, +12.3%) Average QA ScoreMean score across all calls in the selected date range Average Handling TimeMean call duration Interactions Auto FailedPercentage of calls that triggered an auto-fail Negative Feedback RatePercentage of reviewed interactions that received negative (thumbs-down) feedback 6.2 Available Analytics Charts are grouped into four sections: Key Performance Metrics ChartWhat It Shows Average Handling Time vs. Call VolumeCombined view of call volume and average handling time over the selected period QA Score BreakdownDistribution of interactions across QA score bands over time Resolution & Engagement Metrics ChartWhat It Shows Resolved vs. UnresolvedResolution rates over time Silence Time %Breakdown of agent talk, customer talk, and dead air Sentiment AnalysisDistribution of positive, neutral, and negative sentiment Contact Reason Metrics ChartWhat It Shows L1 Contact ReasonBroad reasons customers are calling (max 8 displayed) L2 Contact ReasonSubcategories within L1 (max 8 displayed) Top Call Drivers (L3)Most specific reasons for calls (max 8 displayed) Non-Resolution ReasonsWhy calls are not resolved (L1 and L2) Agent Performance ChartWhat It Shows Agent Quality DistributionAgents grouped by QA score ranges Agent Performance by ParametersTop 10 agents with per-parameter scores Click any chart element (bar, data point, segment) to drill down. 6.3 Filters FilterDescription Agent dropdownSelect a specific agent or view all Date range pickerPresets (Today, Yesterday, This Week, Last Month) or custom range 6.4 Reading the Charts Contact Reason charts (L1, L2, L3): Identify which call types dominate your volume and where to focus training. Resolved vs. Unresolved: A rising unresolved rate may indicate process issues, knowledge gaps, or new product problems. Sentiment Analysis: Combine with Agent Quality Distribution to see if low sentiment correlates with specific agents or score ranges. Silence Time %: High dead air percentages may indicate agents struggling to find information or long hold times. Non-Resolution Reasons: When calls are not resolved, these charts show why -- People, Process, Technical, or End User factors. Agent Quality Distribution: Quickly identify how many agents fall below performance thresholds. Agent Performance by Parameters: Identify which specific skills are strong or weak across your top performers.

================================================================================
# Managing QA Parameters
URL: https://builder.ema.ai/agent-qa/parameters
================================================================================

Managing QA Parameters You can adjust your QA parameters at any time. Changes take effect for new evaluations immediately. Existing evaluations are not retroactively updated. 9.1 What You Can Change ChangeWhereNotes Edit parameter instructionsConfiguration > QA ParametersUpdates pass/fail and N/A instructions Change weightConfiguration > QA ParametersMust be > 0 Change criticalityConfiguration > QA ParametersCritical = auto-fail on failure Change mechanismConfiguration > QA ParametersTranscript Only, Knowledge Verified, or Action Based Add parametersConfiguration > QA Parameters > Add, or via Auto-LearningMaximum 50 per request. Adding via Auto-Learning learns only the new parameters -- see 2.4 Configure QA Parameters with Auto-Learning Delete parametersConfiguration > QA ParametersSoft delete -- parameter is hidden but data is preserved. Select multiple (or all) via checkboxes to bulk delete, including down to an empty set Add/delete contact reasonsWorkflow BuilderChanges the categorization structure Edit contact reason instructionsConfiguration pageUpdates behavior without changing structure 9.2 When to Re-Run Auto-Learning Consider re-running when: You have made significant changes to multiple parameters Substantial feedback has been accumulated and applied through Continuous Learning You want updated accuracy metrics measured against your golden data Your evaluation standards have meaningfully shifted Re-running is not required for every small change. Individual edits and Continuous Learning improvements take effect immediately. 9.3 Training Material Generation Personalized training documents for individual agents are generated as Coaching Reports, available from the Insights tab rather than from QA Parameters -- see 7. Using the Insights Dashboard for the full walkthrough.

================================================================================
# Roles and Permissions
URL: https://builder.ema.ai/agent-qa/roles
================================================================================

Roles and Permissions Agent QA uses five roles. Each role grants a specific set of permissions that control what a user can see and do on an Agent QA AI Employee. 11.1 Role Definitions RoleIntended UsersKey Capabilities AdminAI Employee owners, QA program leadsFull control over the AI Employee — configuration, workflow canvas, permissions, imports, feedback approval, and lifecycle (rename / enable / delete). The only role that can delete the AI Employee. ManagerQA managers, operations leadsManages persona permissions, approves feedback, views metrics/audit/insights, and can view and edit the Configuration tab, imports, and export audit data. Cannot edit the workflow canvas and cannot delete the AI Employee. BuilderPersona configurators, technical ownersConfigures QA parameters, edits the workflow canvas, manages imports, and exports audit data. Cannot view/edit persona permissions and cannot approve feedback. Metrics ViewerLeadership, reporting / BI stakeholdersRead-only across every agent — can view Metrics, Audit, and Insights, and can add feedback. No edit access anywhere (Configuration, workflow canvas, permissions, imports, exports). SelfMetrics ViewerContact center agents viewing their own resultsSame as Metrics Viewer, but scoped to the user's own Agent ID only for Metrics, Audit, and Feedback. Cannot view Insights (team-wide trends) or anything else. The Guest role is no longer applicable to Agent QA personas and has been removed. To revoke a user's access, remove their role assignment on the AI Employee entirely rather than downgrading them to a zero-permission role. 11.2 Permissions Matrix Y = allowed, N = not available. Where noted, a role's access is conditional — scoped to the user's own Agent ID rather than the whole team. PermissionMetrics ViewerSelfMetrics ViewerBuilderManagerAdmin View PersonaNNYYY View and Edit Configuration tabNNYYY View workflow canvasNNYYY Edit workflow canvasNNYNY View / Edit persona permissionsNNNYY View MetricsYOwn Agent ID onlyNYY View AuditYOwn Agent ID onlyYYY View InsightsYNNYY Adding FeedbackYOwn Agent ID onlyNYY Feedback ApprovalNNNYY Rename PersonaNNYYY Delete PersonaNNNNY Change Persona status (enable / disable)NNYYY Imports tabNNYYY Export data (Audit tab)NNYYY 11.3 Permission Codes For programmatic access checks (API integrations, audit logs, and SSO claims), permissions are exposed as the following codes: Permission CodeWhat It ControlsRoles CAN_VIEW_PERSONAOpen the AI Employee pageBuilder, Manager, Admin CAN_EDIT_PERSONAView and edit the Configuration tab — QA parameters, rules, data sourcesBuilder, Manager, Admin CAN_EDIT_WORKFLOW_CANVASEdit the workflow canvasBuilder, Admin CAN_VIEW_PERSONA_PERMISSIONSView and edit who has access to the AI Employee and their roleManager, Admin CAN_VIEW_PERSONA_METRICSView metrics and insights across all agentsMetrics Viewer, Manager, Admin CAN_VIEW_SELF_PERSONA_METRICSView metrics and audit data scoped to the user's own Agent IDSelfMetrics Viewer CAN_SUBMIT_FEEDBACKAdd thumbs-up / thumbs-down feedback on rule evaluationsMetrics Viewer, SelfMetrics Viewer (own Agent ID), Manager, Admin CAN_APPROVE_FEEDBACKReview and approve submitted feedback for use in continuous learningManager, Admin CAN_RENAME_PERSONARename the AI EmployeeBuilder, Manager, Admin CAN_CHANGE_PERSONA_STATUSEnable or disable the AI EmployeeBuilder, Manager, Admin CAN_DELETE_PERSONAPermanently delete the AI EmployeeAdmin CAN_VIEW_IMPORTSOpen the Imports tab and manage data ingestion jobsBuilder, Manager, Admin CAN_EXPORT_AUDIT_DATAExport interaction / audit data from the Audit tabBuilder, Manager, Admin 11.4 Recommended Role Assignment For a typical Agent QA deployment: Assign Admin to a small number of QA supervisors who own the AI Employee end-to-end. Assign Builder to the team configuring QA rules and the workflow canvas. Assign Manager to operations leads who need to manage permissions, approve feedback, and review performance, without editing the workflow canvas. Assign Metrics Viewer to leadership or reporting stakeholders who need visibility across all agents but no edit access. Assign SelfMetrics Viewer to contact center agents who should see only their own results — see 10. For Agents: Viewing Your Own Results. Remove a user's role assignment entirely to revoke their access — there is no longer a separate zero-permission role for this.

================================================================================
# Understanding QA Scores and Scorecards
URL: https://builder.ema.ai/agent-qa/scores
================================================================================

Understanding QA Scores and Scorecards 5.1 How Scores Are Calculated QA scores use a weighted average: Score = (Sum of passed parameter weights / Sum of applicable parameter weights) x 100 In plain terms: Every parameter has a weight reflecting its importance. Higher-weight parameters have a bigger impact on the score. If you pass a parameter, its full weight counts toward the score. If you fail a parameter, it contributes 0. If a parameter is N/A, it is excluded entirely -- it does not help or hurt the score. Matching between criteria names and rule tags is case-sensitive exact match. Worked Example ParameterWeightResultContribution Greeting4Pass4 Empathy6Fail0 Issue Resolution10Pass10 Hold Time6N/AExcluded Passed weight: 4 + 10 = 14 Total applicable weight: 4 + 6 + 10 = 20 (Hold Time excluded because N/A) Score: 14 / 20 x 100 = 70 Edge Cases ScenarioScoreExplanation All parameters N/A100No applicable parameters means nothing failed. The system returns a perfect score. No parameters configured0No rules to evaluate against. The system returns 0. Critical parameter failed0Auto-fail overrides the weighted calculation. 5.2 Score Ranges ScoreWhat It Means 76-100High. Meeting or exceeding quality standards. 51-75Medium. Room for improvement. Review which parameters failed. 1-50Low. Open the Scorecard and read the Rationale and Verbatims for failed parameters. 0Auto-fail. A critical parameter failed, or no applicable criteria were found. Your organization may set different thresholds -- check with your QA manager for your team's standards. 5.3 Critical Parameters and Auto-Fail Parameters marked as Critical represent non-negotiable quality standards (e.g., regulatory compliance, inappropriate behavior). If any critical parameter fails, the entire interaction scores 0, regardless of how well everything else went. A score of 0 does NOT mean everything was wrong. It means one critical standard was not met. All other parameters may have passed. To find which parameter caused the auto-fail: Open the interaction details Go to the Scorecard tab Look for the parameter marked Failed with a Critical indicator Read the Rationale to understand the specific issue Click the "Source" accordion to see the transcript evidence 5.4 Parameter Weights Each parameter has a weight (must be > 0) that determines its relative importance in scoring. You configure weights per organization -- either generated by Auto-Learning based on your QA form, or set manually during parameter configuration. Weights are relative, not absolute percentages. The score formula normalizes based on the sum of applicable weights, so the raw total does not need to equal 100. 5.5 What N/A Means Sometimes a parameter is marked N/A (Not Applicable). This means the rule did not apply to that particular call. Common examples: Hold time evaluation when the agent did not put the customer on hold Upsell evaluation when the call type did not involve a sales opportunity Greeting evaluation when the recording started mid-conversation N/A does NOT count against you. These parameters are removed from the calculation entirely.

================================================================================
# Setting Up Agent QA
URL: https://builder.ema.ai/agent-qa/setup
================================================================================

Setting Up Agent QA This section walks you through configuring Agent QA from scratch. By the end, you will have a fully working QA system evaluating your customer service calls automatically. 2.1 Prerequisites Before starting setup, prepare three sets of files. The quality of these inputs directly determines the accuracy of your evaluations. Golden Call Recordings Representative audio files that cover your typical call scenarios. RequirementDetail ContentDiverse scenarios -- routine calls, escalations, edge cases, different agents, different outcomes Supported formatsMP3, WAV, Opus Maximum file size25 MB per file Audio qualityClear speech, reasonable duration, minimal background noise Tips for selecting golden recordings: Include calls with diverse outcomes (successful resolutions, escalations, transfers, unresolved issues). Cover all major contact reason categories. Balance between high-performing and low-performing examples. Include calls from multiple agents to avoid bias. Aim for 20 to 50 examples per QA parameter for best calibration results. Label Data CSV A spreadsheet containing your human reviewers' Pass/Fail/N/A grades for each golden call recording. RequirementDetail FormatCSV file, UTF-8 encoded Required columnFilename -- must match audio file names without the file extension Parameter columnsOne column per QA parameter, with values of exactly Pass, Fail, or N/A No empty cellsEvery parameter cell must contain Pass, Fail, or N/A Example: UCID,Transcript,Greeting,Customer Verification,Issue Resolution,Empathy,Hold Time call-001,"Good morning, thank you for calling...",Pass,Pass,Fail,Pass,N/A call-002,"Yeah what do you need?",Fail,Pass,Pass,Fail,Pass call-003,"Hello, this is Sarah from Support...",Pass,N/A,Pass,Pass,Pass The UCID value call-001 must correspond to an audio file named call-001.mp3, call-001.wav, or call-001.opus. The Transcript column is optional -- if omitted, the system transcribes from audio. Column headers become your parameter names, so use clear, descriptive names. QA Form RequirementDetail FormatCSV ContentParameter names, detailed descriptions, scoring criteria (what constitutes Pass vs. Fail), weight assignments, and criticality indicators 2.2 Create Your AI Employee Log in at app.ema.co Navigate to AI Employees in the left sidebar Click Create on "Pre-built AI Employee" Select the Agent QA template from the catalog Enter a Name (e.g., "QA Assistant - Customer Service") Enter a Description (e.g., "Evaluates all inbound customer service calls against our 25-parameter QA scorecard") Select the Language for evaluations (this determines the language used in scorecard reasoning and insights) Click Continue Your AI Employee is created in Disabled state. You must complete all configuration steps before enabling it. After creation, you will see six tabs: TabPurpose ConfigurationSet up QA parameters, data sources, integrations, and contact reasons ImportsBring call data into the AI Employee -- manual upload, CCaaS connectors, and agent-mapping management AuditReview evaluated interactions with scorecards and transcripts (empty until processing begins) MetricsView aggregate analytics -- agent performance trends, contact reason breakdowns, resolution rates, sentiment distributions InsightsBrowse AI-generated patterns -- strengths, improvement areas, product feedback, competitive intelligence PermissionsManage user access -- invite users, assign roles, control visibility 2.3 Import Your Data Before Agent QA can evaluate anything, conversations have to reach it. The Imports tab is where that happens -- pull recordings automatically from Genesys Cloud, upload a batch of audio files or transcripts yourself, or re-process interactions you already imported. Imports also depends on agent mapping: the link between the agent identifier your source system uses and a known Ema employee. Set the identity schema up before your first import, or agents cannot be resolved and imports will pause waiting for you. Imports, the Genesys Cloud connection, and agent mapping are covered in full in 3. Imports, Genesys, and Agent Mapping -- including window rules, file limits, the metadata CSV format, job and file statuses, and how to unstick a paused import. Come back here for 2.4 Configure QA Parameters with Auto-Learning once your data is flowing. 2.4 Configure QA Parameters with Auto-Learning Auto-Learning is the fastest and most accurate way to configure your evaluation rules. It uses your golden dataset to generate, calibrate, and iteratively refine parameter instructions until they align with your human reviewers' grades. Upload Your Files Open your AI Employee and click the Configuration tab Scroll to QA Parameters and click Setup QA Parameters Upload all files: FileInstructions Audio filesSelect your golden call recordings. Supported formats: MP3, WAV, Opus. Max 25 MB per file. TranscriptSelect your golden transcripts. Supported formats: JSON, XML, HTML. Label dataClick Download sample first to confirm the expected format. CSV with Pass/Fail/N/A values. QA formClick Download sample to check the expected format. Upload the QA form CSV. Previously uploaded files are visible in this screen after a page reload or in a new session -- the setup shows your most recent upload, not a full history. Reopening the setup pre-populates those files by default; to run with different data, delete the previous files and re-upload. A persona whose Auto-Learning has never run opens with no pre-populated state. Validation Before Auto-Learning Can Start ValidationRequirement Column matchingParameter columns in your label data CSV must match the parameter definitions in your QA form CSV exactly Transcription readinessAll uploaded audio files must have completed transcription before Auto-Learning can start Label data valuesEvery cell must contain exactly Pass, Fail, N/A, or NOT_APPLICABLE No concurrent pipelinesOnly one Auto-Learning pipeline can actively run per AI Employee at a time. A pending review (a completed run awaiting approval) does not block starting another append run -- see Appending New Parameters. Files must finish processing firstYou cannot trigger a run while any uploaded golden-data or QA-form file is still being processed. Wait for processing to finish, then retry. Run Auto-Learning After all files are uploaded and validated, click Generate Parameters Auto-Learning begins processing through multiple stages What you see during processing: A split-panel view: the left pane displays the parameters list with per-iteration accuracy data, while the right pane shows an overall accuracy chart tracking improvement across iterations You can click Run in background to continue configuring other settings while it runs If processing fails, a Retry button appears to restart the pipeline Processing typically takes 15 to 45 minutes depending on the number of golden recordings While a run is active, manual rule editing (add/edit/delete) is disabled with an explanatory notice -- it re-enables once the run finishes What happens behind the scenes: The system runs up to 3 improvement iterations by default, stopping early if accuracy converges (i.e., improvement between consecutive iterations falls below a 1% threshold). Parameters with accuracy below 90% are targeted for instruction rewriting in each iteration. After the initial run completes, you can click Deep Optimize to run additional iterations (up to 20) if accuracy on certain parameters is below your target. Deep Optimize also uses convergence-based early stopping. If you have unsaved manual edits to existing parameters when you start a run, you'll be prompted to save or discard them first -- a run never silently overwrites edits you haven't saved. Review and Approve Parameters After Auto-Learning completes: Click Review Parameters For each parameter, review: FieldDescription Parameter NameThe name of the QA criterion (must be unique) CategoryGrouping label for related parameters WeightHow much this parameter contributes to the overall score (must be greater than 0) CriticalityCritical = auto-fail if this parameter fails; Non-Critical = weighted contribution only MechanismTranscript Only, Knowledge Verified, or Action Based Generated InstructionsA pass/fail instruction and a not-applicable instruction generated by Auto-Learning AccuracyPercentage match between the system's evaluation and your human grades Edit any parameter by clicking on it -- you can modify instruction text, weight, criticality, or mechanism All parameters are selected by default. Deselect any you want to discard, then click Approve Parameters Understanding Accuracy Results AccuracyInterpretationRecommended Action 95-100%Excellent alignment with human gradesNo action needed 90-94%Strong alignmentNo action needed 85-89%AcceptableConsider adding more golden data examples or refining instruction text Below 85%Needs attentionReview golden data quality; consider splitting complex parameters into simpler ones Appending New Parameters Auto-Learning is not a one-time, one-shot setup -- you can add more rules to a persona that already has approved parameters: Upload additional golden data (audio/transcripts, label data, and, if needed, an updated QA form covering only the new parameters) Click Generate Parameters as before Auto-Learning runs only for the newly added parameters -- your existing approved parameters, their results, and their pipeline state are untouched. Once the run completes, approving it merges the new parameters into your existing set; it never replaces or clears what's already there. You get the same options as a first-ever run: approve as-is, or Deep Optimize the new parameters further before approving. A new parameter name that exactly matches an existing one is rejected before anything runs. A name that's merely similar produces a non-blocking warning you can proceed past. Adding Parameters Manually You can also add parameters without Auto-Learning: In Configuration > QA Parameters, click Add Define the parameter name, category, weight, criticality, mechanism, pass/fail instruction, and N/A instruction Click Save Manual parameters do not have accuracy scores since they have not been tested against golden data. Consider running Auto-Learning again after adding manual parameters to validate their performance. Bulk Delete and Reset Select multiple parameters via checkboxes (or select all) to delete them at once -- including all of them, down to an empty parameter set. Resetting to zero shows a warning first, since any continuous-learning corrections tied to the deleted parameters are lost. From an empty set, you can rebuild via Auto-Learning (as a fresh first run) or by adding parameters manually. 2.5 Add a Knowledge Base Skip this step if all of your parameters use the Transcript Only mechanism. A knowledge base is only required for parameters using the Knowledge Verified mechanism. Setting Up Data Sources In the Configuration tab, scroll to Data Sources Click Add and select your source type: Source TypeBest ForSync Behavior File UploadQuick setup, static documentsManual -- re-upload when documents change Google DriveOrganizations using Google WorkspaceAutomatic -- refreshes within ~10 minutes of changes SharePointOrganizations using Microsoft 365Automatic sync ConfluenceOrganizations using Atlassian toolsAutomatic sync URL ScrapingPublic-facing knowledge bases, help centersCrawls up to two levels deep from each seed URL Create a folder name to organize your documents (e.g., "Return Policies," "Product Guides") Upload or connect your files Optionally, assign tags to documents for precise filtering when connecting folders to specific parameters Adding a large number of links to a URL Scraping folder -- several hundred or more, such as an entire support-site crawl -- is best done as an assisted bulk import. Contact your Ema representative rather than adding them one at a time. Supported File Formats CategoryFormats Production-readyPDF, DOCX, PPTX, TXT, HTML, MD Limited supportXLSB, CSV, XLSX, XML, JSON Not supportedLegacy Office binaries (.doc, .xls), source code files, audio/video, native Google Docs/Sheets/Slides Scanned documents pass through OCR automatically. Diagrams are not interpreted -- add text captions for important visual content. 2.6 Add Integrations Skip this step if none of your parameters use the Action Based mechanism. Available Integrations IntegrationTypical Use Cases SalesforceCase creation, CRM field updates, opportunity logging ZendeskTicket creation and update verification GenesysCall metadata retrieval, disposition codes Setup Steps In the Configuration tab, scroll to Integrations Click Add Integration and select the type Enter credentials -- API URL, API Key or OAuth credentials, integration-specific settings Click Test Connection to verify connectivity Configure field mappings -- specify which data fields to retrieve and how to match them to call interactions Click Save Connect the integration to your Action Based parameters in the QA Parameters section 2.7 Configure Contact Reasons Contact reasons categorize why customers are calling. This classification powers the analytics in your Metrics dashboard. Each level of your contact reason hierarchy -- and the Call Driver and Competitor Names categorizations -- runs as its own agent in the underlying workflow, wired together automatically when you use the setup below. You don't need to build these agents yourself. The Three-Level Hierarchy LevelDescriptionExample L1High-level categoryReservations L2Detailed breakdown within L1Modify Reservation L3 (Call Driver)Specific root causeVoluntary Date Change Configure Non-Resolution Reasons Non-resolution reasons categorize why an issue was not resolved. The default L1 categories are: L1 CategoryDescriptionExample L2 Subcategories PeopleAgent-related issuesKnowledge gap, communication issues, insufficient training ProcessWorkflow or policy limitationsScope limitation, policy restriction, approval required TechnicalSystem issuesSystem downtime, integration failure, tool malfunction End UserCustomer-related factorsCustomer unresponsive, call disconnected, customer declined solution Where to Make Changes What You Want to DoWhere to Do It Edit existing category instructionsConfiguration page within your AI Employee Add or delete categories (new L1/L2/L3 entries)Workflow Builder -- click "Go to AI Employee builder" from the Configuration page Keep categories mutually exclusive -- each call should clearly belong to one category at each level. Aim for 5 to 10 L1 categories, 3 to 8 L2 per L1, and specific L3 call drivers under each L2. Review and update categories quarterly. For a very large or multi-brand/multi-level taxonomy, rebuilding the whole categorization structure in bulk is available -- contact your Ema representative rather than adding entries one by one in the Workflow Builder. 2.8 Additional Configuration Tab Settings Glossary Upload company-specific terms and their definitions so Ema understands your organization's vocabulary -- product names, internal abbreviations, or jargon that a general-purpose model wouldn't otherwise recognize. Call Processing Controls how call audio is processed before it undergoes QA evaluation. By default, audio calls are redacted with two independent passes for personally identifiable information (PII) -- rather than a single pass -- so that PII missed by one pass can still be caught by the other. Redacted values are shown as their specific category (e.g. [FIRST_NAME], [SSN]) rather than a generic placeholder. A Hide sensitive information from audit toggle controls whether redaction is applied, and an expandable Redacted entity types list (31 entity types by default) lets you see and adjust which categories of information are removed. Changes apply only to new calls processed after saving -- past interactions are unaffected. Output Language Sets the output language for this persona. Insights, Audit rationale, CSAT, and Coaching Reports are generated in the selected language. The transcript and rule definitions are never translated, and verbatim quotes from the transcript remain in their original language. Changes apply only to new calls processed after saving. Configure EmaFusion By default, Ema intelligently combines multiple large language models to give your persona the best performance. You can instead choose a specific set of models, or bring your own via API details. If you limit to specific models, choose an Optimization Priority: Auto (balances accuracy, latency, and cost by task type), Fastest, Cheapest, or Most Accurate. This setting applies to every agent in the persona by default; you can override it per agent if needed. Data Retention Raw call audio and raw uploaded transcripts are automatically deleted after a retention period -- 30 days by default, configurable per tenant or per persona (a persona-level setting overrides the tenant default, which overrides the platform default). Processed transcripts and evaluation records (scores, scorecards, insights) have no retention limit and are kept indefinitely. Once a raw recording or transcript passes its retention period, it can no longer be re-processed -- this is also why Rerun (see 4.3 Rerunning an Interaction) is only available for interactions still inside their retention window. 2.9 Set Up Permissions Agent QA uses role-based access control with five roles. See Roles and Permissions for the full reference. Click the Permissions tab in your AI Employee Click Add User Enter the user's email address Select the appropriate role Click Send Invitation 2.10 Enable and Send Your First Call Pre-Enable Checklist QA parameters configured and approved (via Auto-Learning or manually) Knowledge base connected and documents indexed (if using Knowledge Verified parameters) Integrations added and connections tested (if using Action Based parameters) Contact reasons configured at all three levels (L1, L2, L3) Non-resolution reasons configured (L1 and L2) Permissions assigned and invitations sent Enable Your AI Employee Navigate to the Configuration tab Click Save changes if any pending changes are indicated Click the Enable toggle at the top of the page and confirm Verify with a Test Call Upload a test call via the API to verify end-to-end processing: API endpoints: Audio Files: POST https://api.ema.co/api/v1/external/upload/file Transcript File: POST https://api.ema.co/api/v1/external/upload/transcript Required headers: HeaderValue x-persona-idYour AI Employee's persona ID (found in Configuration tab URL or settings) AuthorizationBearer <your-jwt-token> Required form fields: FieldTypeDescription resource_idstringA unique identifier for the call (e.g., test-call-001) agent_idstringThe agent's UUID in your system agent_emailstringThe agent's email address (used for Agent-role permission filtering) channelsstringNumber of audio channels ("1" for mono, "2" for stereo) timestampstringCall timestamp in YYYY-MM-DD HH:MM:SS format is_golden_datastring"false" for regular evaluation calls filefileThe audio file (MP3, WAV, or Opus, max 25 MB) Example (Python): import requests API_URL = "https://api.ema.co/api/v1/external/upload/file" PERSONA_ID = "your-persona-id" BEARER_TOKEN = "your-jwt-token" headers = { "x-persona-id": PERSONA_ID, "Authorization": f"Bearer {BEARER_TOKEN}", } data = { "resource_id": "test-call-001", "agent_id": "agent-uuid", "agent_email": "agent@example.com", "channels": "1", "timestamp": "2024-01-15 14:30:00", "is_golden_data": "false", } with open("test_call.wav", "rb") as f: files = {"file": ("test_call.wav", f, "audio/wav")} response = requests.post(API_URL, headers=headers, data=data, files=files) print(response.status_code, response.text) Expected response: HTTP 200 with a confirmation message. Verify the Results Wait 2 to 5 minutes for processing Navigate to the Audit tab Your test interaction should appear with a status of "QA completed" Click View Details to review the scorecard, transcript, and reasoning Troubleshooting a Failed Test Call IssueWhat to Check Unsupported formatAudio must be MP3, WAV, or Opus. Transcript can be JSON, XML, or HTML. File too largeMust be under 25 MB. Compress or split longer recordings. Poor audio qualityEnsure clear speech. Very short recordings (under 10 seconds) or recordings with no speech may fail. Authentication errorVerify your bearer token is valid and the x-persona-id header matches your AI Employee. AI Employee disabledConfirm the Enable toggle is set to Enabled.

================================================================================
# EmaFusion™
URL: https://builder.ema.ai/emafusion
================================================================================

EmaFusion™ EmaFusion is Ema's proprietary mixture-of-experts model that routes across 40+ large language models from 9+ providers to maximize accuracy, speed, and cost efficiency. Instead of relying on a single model, EmaFusion automatically selects the best model for each sub-task. In This Section PageDescriptionHow It WorksArchitecture overview, mixture-of-experts routing, benefits, and example use cases.Setup & ConfigurationConfiguring EmaFusion at the AI Employee level and agent level, optimization modes, model restrictions, and Bring Your Own Model (BYOM). Prerequisites You should be familiar with AI Employees and the Workflow Canvas before configuring EmaFusion settings. Next Steps For troubleshooting model-related issues, see Troubleshooting & Support.

================================================================================
# How EmaFusion Works
URL: https://builder.ema.ai/emafusion/how-it-works
================================================================================

How EmaFusion Works EmaFusion is Ema's proprietary mixture-of-experts model. It routes across 40+ large language models from 9+ providers -- including OpenAI GPT and O-series, Anthropic Claude, Google Gemini, Meta Llama, Mistral, Moonshot Kimi, Alibaba Qwen, and enterprise-trained custom models -- to deliver optimal results for every sub-task an AI Employee performs. Architecture When a task is created, the EmaFusion model recognizes the sub-task type and selects the single best model for that task's framework from its broad catalog of providers. Unlike AI tools locked to one model, EmaFusion dynamically picks the right model for each sub-task -- and, if that model's response falls below a confidence threshold, it cascades to the next-best candidate. Cross-model validation across multiple models only runs in select high-stakes scenarios; routing to a single best model is the default behavior. Routing Logic Task analysis -- EmaFusion examines the incoming sub-task (e.g., conversation generation, structured query, reasoning, summarization). Model selection -- Based on benchmarked performance, cost, and latency data, EmaFusion ranks candidate models and picks the single best one for the sub-task. Execution with cascading fallback -- The selected model processes the task. If its response falls below the confidence threshold for the chosen optimization mode, EmaFusion cascades to the next-best model in the ranked list. Continuous improvement -- Ema regularly benchmarks and updates model performance data, so routing decisions improve over time. Supported Model Families EmaFusion routes across a broad set of model families. The following are the primary families available in the current release: ProviderModelsTypical StrengthsOpenAI (GPT)GPT-5, GPT-5.2, GPT-5.4, GPT-5.4-mini, GPT-4o, GPT-4o-mini, GPT-4.1, GPT-4.1-mini, and earlier variantsGeneral-purpose generation, structured output, tool callingOpenAI (O-series)O1, O1-mini, O3, O3-mini, O4-miniAdvanced reasoning, step-by-step problem solving, math and codeAnthropicClaude Opus, Claude Sonnet, Claude Haiku (multiple 3.x and 4.x variants)Reasoning, long-context tasks, safety-sensitive contentGoogleGemini Pro, Gemini Flash (1.5, 2.x, 2.5, 3 variants including Lite)Structured queries, multimodal tasks, translationMetaLlama 3.1Cost-effective generation, open-weight flexibilityMistralMistral LargeMultilingual tasks, code generationMoonshotKimi K2Long-context understanding, agentic tasksAlibabaQwenMultilingual generation, codeDeepSeekDeepSeek V3, DeepSeek R1Reasoning, code generation, cost efficiencyCustom (BYOM)Your private modelsDomain-specific, compliance-restricted tasks GPT-5.4 and GPT-5.4-mini are the latest additions to the OpenAI family available through EmaFusion. These models support temperature control and are used as the default for many agent types including search reranking, entity extraction, and SDR email generation. Benefits BenefitDescriptionMaximize accuracy, minimize costUses the right model for each sub-task -- avoiding the cost of always defaulting to a single premium model for every request.Continuous improvementEma benchmarks and updates model performance regularly. New models are integrated as they become available.Future-proofNew models are added seamlessly with no vendor lock-in. Your AI Employees automatically benefit from advances in the LLM ecosystem.Fewer hallucinationsOutputs can be cross-checked across multiple models, reducing the likelihood of hallucinated content.Privacy by designEma automatically obfuscates sensitive data (names, emails, phone numbers) before sending to models. Bring Your Own Model (BYOM) To personalize output further, you can use BYOM to integrate your custom-trained models for specialized tasks. This is useful for: Domain-specific models trained on proprietary data. Models hosted in your own infrastructure for compliance reasons. Private instances of commercial models (e.g., Azure OpenAI, private Gemini endpoints). BYOM supports any model endpoint that exposes an OpenAI-compatible chat completions API. You provide the API URL and API key, and EmaFusion routes all requests for that AI Employee to your endpoint. BYOM limits to be aware of: One custom model per AI Employee. You cannot configure multiple BYOM endpoints on the same AI Employee -- the one you set becomes the sole model for all of its agents. Not supported at the agent level. BYOM is configured at the AI Employee level only. Individual agents cannot override it with a different custom model. Capability mismatches can cause failures. If your custom model does not support a capability an agent requires (for example, FUNCTION_CALLING, STRUCTURED_OUTPUT, or VISION), that agent will fail at runtime. Confirm your endpoint supports the features your workflow needs. See Setup & Configuration for instructions on configuring BYOM. Example Use Cases Customer Support AI Employee: Uses GPT-5.4 for conversation, Claude for reasoning, and Gemini for structured queries. Finance Analyst AI Employee: Routes to an enterprise-trained proprietary model for compliance-sensitive tasks, with fallback to GPT-4o for summaries. Healthcare AI Employee: Uses a private BYOM model with a HIPAA-compliant API for patient data. Voice AI Employee: Routes speech-to-text diarization to GPT-5.4 for high-accuracy transcription, with downstream agents using EmaFusion's balanced routing for response generation. Configuration Hierarchy EmaFusion configuration is resolved through a two-level hierarchy: a default set at the AI Employee level, and optional per-agent overrides that replace the default for a specific node in a workflow. AI Employee default. Every AI Employee has a default EmaFusion configuration -- the selected models, optimization mode, and any BYOM settings -- stored on the AI Employee itself. This is the configuration all agents use unless they override it. Agent-level inheritance. By default, every agent references the AI Employee's EmaFusion configuration and inherits any changes to it. This is why updating the AI Employee-level default automatically flows through to all agents that have not been overridden. Agent-level override. Each agent has an Override default configuration toggle in its Advanced Settings. Enabling it unbinds the agent from the AI Employee default and lets you set an agent-specific model, optimization mode, or custom model. Disabling it re-binds the agent to the AI Employee default. BYOM is AI Employee-scoped only. Custom models configured via BYOM are set on the AI Employee and apply to every agent underneath it. There is no agent-level BYOM override. As a rule of thumb: configure the AI Employee-level default to match what most of your agents should use, and reach for agent-level overrides only when a specific agent has different requirements (e.g., a reasoning model for a planner, or a faster model for a latency-sensitive step). References EmaFusion Research Paper (arXiv) EmaFusion Launch Blog EmaFusion Product Page

================================================================================
# EmaFusion Setup & Configuration
URL: https://builder.ema.ai/emafusion/setup
================================================================================

EmaFusion Setup & Configuration EmaFusion can be configured at two levels: the AI Employee level (applies to all agents within the AI Employee) and the individual agent level (overrides the AI Employee default for a specific agent). AI Employee-Level Configuration Step 1 -- Open Configuration Go to your AI Employee Dashboard. Select the AI Employee you want to configure. Click Configuration in the left-hand menu. Step 2 -- Choose a Model Setting You will see three configuration options: Option 1: Use All Available Large Language Models (Recommended) EmaFusion selects from 40+ models automatically. You can further select how to optimize model selection: Optimization ModeBehaviorBalanced / Auto (default)Prioritize models based on task type, optimizing between accuracy, latency, and cost.FastestPrioritize models with the lowest response time.CheapestPrioritize models with the lowest cost.Most AccuratePrioritize models with the highest accuracy for the task. Option 2: Limit to Specific Models Choose which models (e.g., GPT-5.4, Claude, Gemini) EmaFusion can use from the model picker dropdown. EmaFusion will only select among the specified models. If you select two or more models, you can further select an optimization mode (Balanced, Fastest, Cheapest, Most Accurate). The model picker dropdown shows only models that are compatible with the agents in your workflow. If agents have not had their model configuration overridden, the dropdown displays the union of eligible models across all such agents and disables the rest. See Model and Agent Capabilities below for details. Trade-off: Restricting models may reduce overall performance. Option 3: Use Your Custom Model (BYOM) Enter your API URL and API Key for your custom model. This connects your private OpenAI, Gemini, or internal LLM instance. Important: Currently, only one custom model can be set per AI Employee. Agent-Level Configuration Each agent inside an AI Employee can have its own EmaFusion configuration. Steps Go to your AI Employee and open the Agents tab. Select the agent you want to configure. Click Advanced Settings and then EmaFusion Configuration. Behavior By default, all newly added agents inherit the model configuration from the AI Employee. You can override the default by selecting the Override default configuration toggle and changing settings. Custom models (BYOM) are not supported at agent level. If a custom model is set at the AI Employee level, all agents will use it. For the "Limit to the following Large Language Models" option at agent level, only models that have the capabilities needed by that specific agent will be enabled in the dropdown. Model and Agent Capabilities Under the hood, every agent and model has a predefined set of capabilities: Model capabilities describe what the model can do (e.g., text generation, structured output). Agent capabilities describe what model capabilities the agent needs. When you select "Limit to the following Large Language Models" at either the agent or AI Employee level, a filtering mechanism enables only models that are eligible for the agent or AI Employee. This prevents runtime issues where an agent attempts to use a model that lacks a required capability. Capability Mismatch Errors If an agent inherits its model configuration from the AI Employee, and an ineligible model has been set at the AI Employee level, an error will be displayed for that agent. To resolve the error: Click Override default configuration on the agent. Select one of the eligible models from the dropdown, or Select Use all available Large Language Models, or Specify a custom model if you have one. Best Practices Start with Use all available LLMs (the default) and the Balanced optimization mode. This gives EmaFusion the widest selection for optimal routing. Only restrict models when you have a specific requirement (compliance, cost ceiling, latency SLA). Use agent-level overrides sparingly -- for example, when a particular agent needs a model with specialized capabilities that differs from the AI Employee default. When using BYOM, ensure your custom model's API is reliable and low-latency, as it becomes the sole model for the AI Employee. If you need different models for different agents, override at the agent level rather than restricting the AI Employee-level configuration. This preserves EmaFusion's flexibility for agents that do not require a specific model. Related Pages How EmaFusion Works -- Architecture, routing, and benefits. Troubleshooting & Support -- Common errors and how to address them.

================================================================================
# Troubleshooting & Support
URL: https://builder.ema.ai/troubleshooting
================================================================================

Troubleshooting & Support When something goes wrong, this section helps you identify the issue, apply a fix, and reach the right support channel if needed. In This Section PageDescriptionCommon Failure ModesError messages, root causes, and resolution steps for general errors, workflow errors, external tool calling errors, Custom Code Agent errors, Voice AI issues.SupportHow to contact support, what information to include, escalation guidance, and available support query types. Before You Troubleshoot Check the AI Employee status. Is it active and ready? Review the trigger. Is the trigger correctly configured for the interaction type? Trace the execution. Where in the workflow does the failure occur? Inspect integrations. Are connected apps authenticated and operational? Next Steps If the issue is not covered here, contact Ema support through the Helpdesk.

================================================================================
# Common Failure Modes
URL: https://builder.ema.ai/troubleshooting/common-failures
================================================================================

Common Failure Modes This page catalogs frequent errors encountered on the Ema platform, organized by category: general errors, workflow errors, external tool calling errors, Custom Code Agent errors, Voice AI issues. General Errors Error / SymptomRoot CausesHow to AddressUser unable to login with a magic link or OAuth(1) User is trying to use an expired magic link -- login links expire after 15 minutes. (2) User is trying to use a link that has already been used. (3) User has not been invited to the tenant. (4) User is logging in from the wrong URL (e.g., customer.ema.co vs demo.ema.co).(1) Request a new magic link and use it within 15 minutes. (2) Request a fresh link -- each link is single-use. (3) Ask a Workspace Admin or Manager to invite the user to the correct tenant. (4) Confirm the correct login URL for the target environment.User is not getting a magic login link(1) The user's company is blocking Ema's emails or sending them to spam. (2) The user is from a geo-blocked country.(1) Check spam/junk folders. Whitelist Ema's sending domain in the company's email security settings. (2) Confirm whether the user's region is supported. Contact Ema support if a geo-block exception is needed. Workflow Errors Error / SymptomRoot CausesHow to AddressThe output of the workflow was empty(1) No workflow created for specific categories in a categorizer. (2) No output published for a workflow branch.(1) Ensure every category in the categorizer -- including Fallback -- has a corresponding workflow branch. (2) Verify that all workflow paths terminate at WORKFLOW_OUTPUT and that the final agent's output is correctly mapped. External Tool Calling Errors Error / SymptomRoot CausesHow to AddressCan't see tools from connected apps in External Tool Caller agentTool may not be enabled for AI Employees.On the Integrations page, select the app (e.g., Jira), open the Tools tab, and enable the specific tool you want to make available to AI Employees.Tool calls failingApp may not be connected, or the tool is not enabled.Check app connections from the Integrations page. If connected, enable the tools to be available for AI Employees."I'm unable to complete this request at the moment, but we're continuously expanding our capabilities. Please contact your administrator for further assistance."The correct action may not yet be available, or the agent is selecting the incorrect action.If the action is available, the issue is likely the agent not selecting the right tool. Add more specific instructions in the External Tool Caller agent to guide tool selection."Sorry, it looks like your request took longer than expected. Please try again in a moment."The connected app is experiencing high latency, crossing the timeout threshold.Check the status of the app's APIs and confirm they are operational. Retry after the app recovers."I'm unable to complete your request to [action type] at the moment. Please try again shortly."HITL (Human-in-the-Loop) may be disabled, and the agent needs more information from the user.Turn on HITL for the tool. If you do not want Ema to always pause, enable HITL but turn off the "pause always" setting."Looks like [App Name] is currently down or under maintenance. Please try again shortly."The connected app is unavailable.Check the app's status page. Retry when the app is back online. Custom Code Agent Errors Error / SymptomRoot CausesHow to AddressCustom Code Agent execution fails with a runtime error(1) Syntax error in the provided code. (2) The code references an unavailable library or module. (3) The code exceeds the execution timeout.(1) Review the code in the Custom Code Agent configuration panel. Check for syntax issues, missing imports, or unsupported language features. (2) Confirm that only supported standard libraries are used. Custom external dependencies are not available in the sandboxed execution environment. (3) Optimize the code to run within the timeout window. Break complex logic into smaller steps across multiple agents if needed.Custom Code Agent returns unexpected output formatThe code produces output that does not match the expected schema for downstream agents.Verify that the output matches the data type expected by the next agent in the workflow. Use explicit type casting or structured output (JSON) to ensure compatibility. Test the agent in isolation before wiring it into a larger workflow. Voice AI Errors Error / SymptomRoot CausesHow to AddressVoice AI Employee not responding to calls(1) SIP trunk configuration is incorrect or incomplete. (2) The Voice AI Employee is not in an active state.(1) Verify the SIP endpoint configuration in the Voice AI Employee settings. Ensure the phone number and trunk are correctly provisioned. (2) Check that the AI Employee status is active and the voice trigger is enabled.Poor transcription accuracy(1) Audio quality is low (background noise, poor microphone). (2) The caller's accent or language is not well-supported by the speech-to-text model.(1) Advise callers to use a quiet environment and a high-quality microphone. (2) If accuracy is consistently poor for a specific language or accent, contact Ema support to discuss model tuning options.Voice AI Employee responds with long latency(1) The downstream workflow is complex, adding processing time. (2) The speech-to-text or text-to-speech service is experiencing high load.(1) Simplify the workflow for voice interactions -- minimize the number of agent hops between the voice trigger and the response. (2) If latency persists, contact Ema support to investigate service-level performance. Debugging Tips Check AI Employee status -- Confirm the AI Employee is active and ready. Review trigger configuration -- Ensure the trigger type matches the interaction mode (chat, voice, document, email, scheduled). Identify AI Employee type -- Dashboard AI Employees debug differently from chat/voice. Dashboard rows trigger workflow runs, not conversations. Trace execution -- Use the execution trace to identify where the workflow fails. Inspect inputs -- Verify that inputs are reaching agents correctly and that types are compatible. Check integrations -- Confirm that connectors are authenticated and the external service is operational. Review categorizer -- Ensure the categorizer has all category edges, including Fallback. Verify Workflow Outputs -- Confirm that all branching paths lead to Workflow outputs being set. Validate types -- Check that all connections are type-compatible. Use conversation_to_search_query when converting chat conversations to search inputs. Check audit log -- Review the audit log for recent configuration changes that may have introduced the issue. See Administration. Review version history -- If the issue appeared after a recent change, use version history to compare the current workflow configuration against a previous working version. Related Pages Support -- How to contact Ema support and what to include in your request. EmaFusion™ Setup -- Model capability mismatch errors and resolution.

================================================================================
# Support
URL: https://builder.ema.ai/troubleshooting/support
================================================================================

Support Ema is committed to providing responsive and effective support so you can get the most out of the platform. Whether you have encountered an issue, need guidance, or want to share ideas for improvement, the support team is ready to assist. How to Contact Support Submit a request through the dedicated Helpdesk. After submission, the team will review your request and respond to the email address you provided. Follow-up questions may be sent to ensure the issue is fully understood. Support Query Types Ema handles three main types of support queries: TypeDescriptionWhen to UseTechnical SupportAssistance with installing, configuring, troubleshooting, or using Ema.You need help setting up an integration, configuring an AI Employee, or resolving an operational issue.Report a BugReport problems you are experiencing on the platform.Something is not working as expected -- errors, incorrect behavior, UI issues.Suggest a New FeatureShare an idea for a new feature or improvement.You have a workflow need that is not currently supported, or you want to propose an enhancement. What to Include in a Support Request Providing detailed information upfront helps the support team resolve your issue faster. For Technical Issues and Bug Reports ItemDetailsAI Employee name and IDWhich AI Employee is affected? Include the persona ID if available.EnvironmentWhich environment are you working in (e.g., customer.ema.co, demo.ema.co)?Steps to reproduceWhat actions lead to the issue? Be as specific as possible.Expected behaviorWhat should have happened?Actual behaviorWhat happened instead? Include error messages verbatim.Screenshots or recordingsVisual evidence of the issue, if applicable.Browser and OSWhich browser and operating system you are using.TimestampWhen the issue occurred. This helps the team locate relevant logs. For Feature Requests Describe the use case or workflow you are trying to accomplish. Explain why existing features do not meet the need. Include examples or mockups if available. Escalation Guidance If your issue is urgent or has not been addressed within the expected timeframe, follow these escalation steps: Reply to your existing ticket in the Helpdesk with additional context or urgency details. Do not create a duplicate ticket. Contact your Ema account manager if you have one. They can escalate internally on your behalf. For production-blocking issues, indicate the severity and business impact in your ticket. The support team prioritizes based on impact. Self-Service Resources Before contacting support, check these resources: Common Failure Modes -- Known errors with documented resolutions. EmaFusion Setup -- Model configuration and capability mismatch troubleshooting. Governance, Access & Permissions -- Role and permission issues. Ema Trust Center -- Security certifications and compliance documentation. Related Pages Common Failure Modes -- Error reference with root causes and fixes. Administration -- Workspace, user, and security management.

================================================================================
# Use Cases & Patterns
URL: https://builder.ema.ai/use-cases-patterns
================================================================================

Use Cases & Patterns This section bridges the gap between what the Ema Builder Platform can do and how to apply it to real problems. While Core Concepts explains the platform's building blocks and Builder Guides teaches you how to construct workflows, this section shows you how those capabilities come together to solve specific categories of business problems. What Is a Pattern? A pattern is a repeatable approach to solving a class of problems on the Ema platform. Unlike templates, which are ready-to-deploy configurations, patterns describe the underlying workflow structures, agent combinations, and data strategies that make those configurations work. Use Cases Use CaseDescriptionCustomer Support & EngagementAI Employees for customer Q&A, agent assist, and knowledge base auditing.Sales Development & OutreachSDR automation, prospecting workflows, and email sequence generation.Talent Acquisition & RecruitmentCandidate discovery, resume scoring, and automated outreach.HR & Employee ServicePolicy Q&A, IT support triage, and internal workflow automation.Document Processing & ExtractionContract evaluation, claims intake, and structured data extraction from documents.Healthcare & CompliancePrior authorization, clinical document processing, and eligibility determination.Analytics & InsightsVoice of customer analysis, sentiment trends, and feedback processing at scale.Voice AIInbound and outbound voice interactions, IVR replacement, and phone-based customer engagement.Custom Code PatternsExtending workflows with custom logic using the Custom Code Agent. How to Use This Section Find the closest use case above to evaluate feasibility and plan your build. If you want a working AI Employee quickly, start with Templates and come back here to understand or customize the design. For hands-on tutorials, see Builder Guides. Related Sections Templates -- Pre-built AI Employee configurations that implement many of the patterns described here. Builder Guides -- Hands-on tutorials for constructing workflows in the Generative Workflow Engine. Core Concepts -- Foundational platform concepts including GWE, agents, bindings, and the type system. API Reference -- Programmatic access to AI Employees, workflows, and platform resources.

================================================================================
# Custom Code Patterns
URL: https://builder.ema.ai/use-cases-patterns/custom-code
================================================================================

Custom Code Patterns The Custom Code Agent extends the Ema Builder Platform with arbitrary logic that cannot be expressed through the standard agent library. When a workflow requires data transformation, custom validation, mathematical computation, or integration with a proprietary algorithm, the Custom Code Agent provides a sandboxed JavaScript or TypeScript execution environment within the workflow pipeline. This page covers common patterns for using the Custom Code Agent effectively, including data transformation, conditional routing, and hybrid workflows that combine custom code with standard agents. For the full API reference, see Custom Code Agent. When to Use Custom Code Use the Custom Code Agent when: You need to parse, filter, or reshape data (CSV, JSON, text) with precise control over the output format. You need custom mathematical or statistical computation (scoring algorithms, weighted averages, threshold calculations). You need deterministic branching or conditional logic that is more complex than what trigger-when conditions support. You need to parse or restructure data from an external API response before passing it to a downstream agent. Pattern 1: Data Transformation and Computation Problem You have data -- a CSV file, a JSON structure, a block of text -- that needs to be parsed, filtered, reshaped, or computed on. Examples include parsing CSV into structured rows, filtering by criteria, computing aggregates (totals, averages, weighted scores), or reformatting data for a specific output. Approach Pass the data into the Custom Code Agent as a named input. Write code that parses, transforms, or computes on the input and returns the result as a string. Example // Parse CSV, filter rows with score >= 80, compute total and return summary function main(inputs) { var rows = Papa.parse(inputs.csv_data[0].text, { header: true, skipEmptyLines: true }).data; var high = rows.filter(function(r) { return parseInt(r.score, 10) >= 80; }); var total = high.reduce(function(sum, r) { return sum + parseInt(r.score, 10); }, 0); return JSON.stringify({ count: high.length, total: total, names: high.map(function(r) { return r.name; }) }); } Pattern 2: Custom Scoring and Routing Problem You need to apply a proprietary scoring algorithm to data extracted by an upstream agent, then route the workflow based on the score. For example, a lead scoring model that weighs multiple factors in a custom formula, or a risk assessment that applies domain-specific rules beyond what the Rule Validation agent supports. Components Extract Entities Agent --> Custom Code Agent (compute score) --> Categorizer (route based on score threshold) --> [high score] --> Branch A --> [low score] --> Branch B Approach Extract the relevant data points with an upstream agent. In the Custom Code Agent, implement your scoring formula. Return the score as a structured output. Use the Categorizer agent downstream to route the workflow based on the score value. Watch Out For Keep the code simple. Complex algorithms with many dependencies are hard to debug in a sandboxed environment. If the scoring logic is highly complex, consider calling an external API via call_ema_connector() or using the External Tool Caller agent instead. Test with edge cases. Scores of zero, negative values, missing input fields, and extreme outliers should all produce reasonable behavior. Pattern 3: Hybrid Workflows Problem Some workflows require a mix of AI-driven steps (search, summarization, classification) and deterministic logic (date calculations, format validation, lookup tables). The Custom Code Agent lets you insert deterministic steps into an otherwise AI-driven pipeline. Approach Use standard agents for tasks they excel at: search, summarization, classification, tool calling. Insert Custom Code Agent steps where you need deterministic, reproducible logic: date math, format validation, lookup tables, conditional formatting. Use call_llm() within the same script when you need both deterministic logic and LLM reasoning in a single step -- for example, transforming data and then summarizing the result. Example // Filter high-value rows, then ask the LLM to summarize function main(inputs) { var parsed = Papa.parse(inputs.csv_data[0].text, { header: true, skipEmptyLines: true }); var high = parsed.data.filter(function(row) { return parseFloat(row.amount) >= 1000; }); if (high.length === 0) return "No high-value transactions found."; var summary = call_llm( "Summarize the following transactions:\n\n" + JSON.stringify(high), "You are a financial analyst. Return a concise 2-3 sentence summary." ); return summary; } Watch Out For Do not hand-write NLP logic in code. If you find yourself implementing text classification or entity extraction manually, use call_llm() within the script or a dedicated agent like Categorizer instead. Keep code stateless. Each Custom Code Agent execution is independent. Do not rely on state from a previous execution -- pass all required data through the workflow. Tips Always return a string. Returning an object produces "[object Object]". Use JSON.stringify() for structured data. Guard against null inputs. If an upstream agent was skipped or returned nothing, the input is null. Check before accessing properties. Use log.info() to debug. Log messages appear in the Show Work panel -- more useful than code comments for tracing execution. Test with real data. Copy inputs from a previous workflow run (Show Work → Execution logs → Script Inputs) and paste them into the test modal. Related Resources Custom Code Agent: Custom Code Agent -- Full API reference, supported libraries, input types, and testing. Agent Reference: Agent Reference -- Full catalog of standard agents. Builder Guides: Builder Guides -- Workflow construction tutorials. Core Concepts: Workflows and Actions -- How agents compose in the GWE. Troubleshooting: Common Failure Modes -- Custom Code Agent error reference.

================================================================================
# Voice AI
URL: https://builder.ema.ai/use-cases-patterns/voice-ai
================================================================================

Voice AI Voice AI Employees handle real-time phone conversations -- answering inbound calls, conducting outbound campaigns, and replacing static IVR trees with natural language interactions. Instead of forcing callers through a menu of button presses, a Voice AI Employee listens, understands intent, retrieves relevant information, and responds conversationally. This page covers the core patterns for building voice-based AI Employees on Ema's platform, from simple inbound call handling to complex multi-step voice workflows with tool calling and escalation. What You'll Need Builder or Admin access to your Ema workspace. A provisioned phone number with SIP trunk configuration for inbound or outbound calls. Knowledge base content -- the same documentation, FAQs, and policy documents you would use for a chat AI Employee. Identity and purpose instructions -- a description of who the Voice AI Employee is, what it does, and how it should behave on calls (tone, pacing, escalation rules). Familiarity with the AI Employee builder -- voice workflows use the same GWE canvas as chat workflows, with a voice-specific trigger. Why Voice? Many customer interactions still happen over the phone -- especially in healthcare, insurance, financial services, and customer support. Traditional IVR systems are rigid: they force callers into predefined paths and cannot handle nuance. Voice AI Employees combine the natural language understanding of a chat AI Employee with the immediacy and accessibility of a phone call. Pattern 1: Inbound Call Handling Problem Callers reach a phone line and expect immediate help. Traditional IVR menus are frustrating and slow. Human agents are expensive and have limited availability. The result is long hold times, high abandonment rates, and inconsistent service quality. Components Voice Trigger (inbound call) --> Speech-to-Text (transcription) --> Intent Classification --> Search knowledge base --> Generate response --> Text-to-Speech (spoken response) --> [If unresolved] Escalate to human agent Voice Trigger -- Activates the workflow when a call arrives on the provisioned phone number. Speech-to-Text -- Converts the caller's speech into text using high-accuracy transcription (GPT-5.4 for diarization by default). Workflow execution -- The transcribed text flows through the same agent pipeline as a chat workflow: intent classification, knowledge retrieval, response generation. Text-to-Speech -- Converts the generated text response back into natural-sounding speech for the caller. Setup Steps Create a Voice AI Employee. Navigate to AI Employees, click + New Employee, and select Voice as the interaction type. Configure the phone number. Provision a phone number and configure the SIP trunk in the Voice AI Employee settings. Set identity and purpose. Write clear instructions that define the AI Employee's persona for phone interactions: name, role, tone of voice, pacing, and what topics it should and should not discuss. Add your knowledge base. Upload or connect the same documentation, FAQs, and policy files you use for chat-based support. Build the workflow. Use the GWE canvas to construct the call handling flow. A simple pattern: Voice Trigger --> Search/v2 --> Call LLM (respond) --> Workflow Output. Configure escalation. Add a branch that transfers the call to a human agent when the AI Employee cannot resolve the issue or when the caller explicitly requests a human. Test with real calls. Place test calls covering your most common inquiry types. Listen to the full interaction and verify transcription accuracy, response relevance, and conversational flow. Watch Out For Latency is critical. Unlike chat, voice interactions feel broken when there is more than a second or two of silence. Keep workflows short -- minimize the number of agent hops between the voice trigger and the response. Transcription accuracy varies. Background noise, accents, and poor audio quality all affect speech-to-text accuracy. Test with realistic audio conditions, not just quiet studio recordings. Conversation pacing differs from chat. Voice responses should be shorter and more conversational than chat responses. Instruct the response agent to keep answers concise and to pause for the caller's acknowledgment before continuing with lengthy explanations. Always provide an escalation path. Callers who cannot get help from the AI Employee and have no way to reach a human will have a very negative experience. Ensure every voice workflow includes a clear handoff mechanism. Pattern 2: Voice with Tool Calling Problem Callers often need the AI Employee to take action on their behalf -- check an order status, schedule an appointment, reset a password, or file a claim. A voice AI Employee that can only answer questions but cannot act is limited in value. Components Voice Trigger (inbound call) --> Speech-to-Text --> Intent Classification --> [information] --> Search KB --> Respond --> [action] --> External Tool Caller --> Respond with Tool Result --> Text-to-Speech This pattern extends Pattern 1 by adding an action branch. When the intent classifier identifies an action request, the workflow routes to the External Tool Caller agent, which executes the action in the connected system and returns the result to the caller via text-to-speech. Setup Steps Start from Pattern 1. Build the inbound call handling workflow first. Add the intent classifier. Configure categories for information requests (handled by search + respond) and action requests (handled by tool calling). Connect enterprise applications. On the Integrations page, connect the systems the AI Employee will interact with (CRM, ticketing, scheduling, etc.). Enable tools for the ETC agent. Select which actions the AI Employee can perform on each connected application. Enable HITL for sensitive actions. For actions that modify data (creating tickets, scheduling appointments), enable Human-in-the-Loop confirmation so the AI Employee verbally confirms the action with the caller before executing. Test end-to-end. Call in, request an action, confirm the action is executed in the target system, and verify the caller receives a clear confirmation. Watch Out For Confirm before acting. In a voice context, misunderstood speech can lead to the wrong action. Always confirm action parameters with the caller before executing. Keep HITL prompts natural. The confirmation message should sound like a natural conversation, not a form read-back. "Just to confirm, you'd like me to schedule that appointment for Thursday at 2 PM -- is that right?" is better than "Confirm: action=schedule, date=Thursday, time=14:00." Handle tool failures gracefully. If the external system is down, the AI Employee should say something helpful ("I'm unable to check that right now, but I can transfer you to someone who can help") rather than going silent or returning a technical error. Design Considerations Voice vs. Chat Voice AI Employees and chat AI Employees share the same underlying workflow engine, but they have different user experience constraints: ConsiderationChatVoiceLatency toleranceUsers tolerate 3-5 seconds of "thinking"More than 1-2 seconds of silence feels brokenResponse lengthCan be detailed with links and formattingMust be concise and conversationalError recoveryUser can re-read and re-tryMisunderstandings compound quicklyEscalationLink or button to human agentLive call transferMulti-turnFull conversation history visibleCaller may forget earlier context Optimizing for Voice Latency Use the Fastest EmaFusion™ optimization mode for voice workflows to minimize model response time. Keep workflows linear where possible -- parallel branches add coordination overhead. Instruct response agents to produce short, direct answers. Avoid agents that generate lengthy explanations. Related Resources Core Concepts: AI Employees -- Interaction types including voice. Builder Guides: Creating Your First Workflow -- The GWE canvas works the same for voice and chat. Agent Reference: Categorize Conversations and Route, Agentic Search and Respond Integrations: Integration List -- Supported external systems for tool calling. EmaFusion: Setup & Configuration -- Optimization modes for voice latency.