AppEngine AI APIs: Employees, Assistant, Work and Approvals

Video chapters

Written guide

Build an application that configures an AI employee, connects a real runtime, talks to it, assigns work, presents human approvals and verifies the resulting records. Then integrate a configured AI Assistant that answers a request using an explicitly selected platform tool.

This course assumes ordinary HTTP and programming knowledge. It teaches AppEngine's identities, settings, work lifecycle and integration contracts. The sample interface consumes real AppEngine APIs; it is a custom client, not Appmint Studio. The downloadable companion supports JavaScript, TypeScript and Python and includes the existing runtime source plus the official JavaScript client snapshot. Exact current operations and schemas belong in the maintained API reference.

The demo app source on GitHub is the maintained companion. The ZIP retains the recording-time snapshot. The GitHub runtime requires your own provider key and contains no bundled development key.

1. Choose an employee or an Assistant

An AI employee has an organization staff user, groups, working hours, a budget and a queue. AppEngine manages that identity and work. A separate runtime signs in as the employee, receives its current briefing, leases a job and performs permitted operations. Provider provisioning, employee sign-in and a finished job are three separate results.

An AI Assistant is a stored configuration of instructions, capabilities, tools and optional triggers. Your authenticated application invokes it, and AppEngine runs the configured model/tool loop for that caller. It does not obtain the employee's identity or consume that employee's queue.

Use an employee when a continuing staff identity, assignments, schedules, approvals and shared work matter. Use an Assistant when your application needs a bounded response or supported tool action in the current interaction. The examples below show both; neither substitutes a hard-coded reply for model execution.

2. Get the organization and staff session

Complete API Foundations — sign in as the owner. Obtain the AppEngine base URL, organization ID and a completed ordinary staff session. Finish any password-change or security challenge before using its access token. Organization Owner or ConfigAdmin manages AI employees; platform/root organization membership is not required.

Keep that staff session on your trusted host. The sample browser uses a same-origin cookie and an explicit action allowlist. For a deployed application, implement the authentication boundary in Custom API Gateway, rather than shipping the sample's environment token to a browser.

Open the maintained reference, search AI Employees, and inspect the selected operation's method, path, authorization, request and response. Start with employee list and create employee. Do not treat an old summary mentioning a stub or a per-job token as the current runtime contract. The worker operations below use the employee's own completed staff session.

For rehearsal, use an organization you control and non-sensitive records. The recorded organization disables outgoing email and has no employee phone or external channel assigned. Internal saved messages are demonstrated; delivery of customer email, SMS or phone calls is not claimed.

3. Company guidance, defaults and templates

Read GET /ai-employees/config. It returns {config, from, isPlatform}. from explains where each effective section came from: the organization, platform defaults or built-in fallback. The company, knowledge, defaults and escalation sections have different purposes; inspect the relevant section rather than copying a complete settings object blindly.

Defaults seed a new employee. They do not mean that changing a default rewrites every existing employee. Creation combines defaults, the selected template and explicit profile values. Choose a template with GET /ai-employees/templates, read its actual job description and permissions implications, then override the parts that belong to this employee.

Organization instructions are separate from the employee's job description. Read GET /ai-employees/instructions and the chosen employee's GET /ai-employees/{name}/instructions. The organization response omits platform-internal instructions; do not imply that an administrator sees every instruction supplied by the platform. The runtime receives current effective guidance through its briefing.

Save only the sections you intend to change. A null configuration section resets that organization override. Review the returned effective values and their source after saving. A new template or a saved description is configuration evidence; it is not evidence that a runtime has acted on it.

4. Create the employee and grant useful access

Create through POST /ai-employees, not by inserting an ai_employee record through Repository. AppEngine creates and links the employee's staff user, records its generated staff email and initializes its draft state. Keep the returned employee handle and userEmail; do not invent them from a display title.

The recorded Ava profile uses:

An internal Workspace job description, with no external communications.
runtime.provider: "session-manager" and a model supported by that runtime.
An explicit timezone and always-on training hours.
A daily budget, one concurrent job and one attempt for bounded rehearsal.
Approval requirements for destructive, bulk, monetary and permission-changing work.

The mandatory AI group identifies the employee. Additional groups give it useful application access. Inspect GET /ai-employees/{name}/access, select the least access required, then save the chosen group names with the matching PUT operation. This example adds User, sufficient for its permitted Workspace work. Do not grant Owner, ConfigAdmin or System simply to avoid understanding a refusal. Platform/root groups are refused by employee access management.

Read the profile again. The detail includes record, access, setup, queue, activity, contact and runtime connection information. A saved group list is not proof that every requested API is permitted: the employee's actual operation must still pass the relevant route and record checks.

When updating nested settings, preserve sibling values. For example, changing a model must not erase the existing runtime provider; changing hours must retain the intended timezone and days. The supplied host explicitly merges the allowed settings before saving.

Actual sample client reading the saved AppEngine employee. The identity and setup checks are real; the interface is not Appmint Studio.

5. Connect the runtime in both directions

The existing Appmint ai-employee session-manager example, included under runtime/ in the download, is a real runtime: it runs bounded Claude Code sessions and exposes the ae command for AppEngine operations. Reuse that example rather than creating an unrelated SDK or simulating an AI reply.

There are two connections:

AppEngine → session manager. Configure AI_EMPLOYEE_SESSION_MANAGER_URL and AI_EMPLOYEE_SESSION_MANAGER_KEY on AppEngine. The runtime's AIE_PROVIDER_KEY must match. These are private deployment settings, not browser fields.
Runtime → AppEngine. The handover includes the API base URL, organization and the employee's own sign-in. The runtime must reach that URL and complete employee sign-in plus its authenticator challenge.

In the supplied runtime checkout, install its dependencies and start its server with environment settings such as:

AIE_HOST=127.0.0.1 \
AIE_PORT=3400 \
AIE_DATA_DIR=/private/path/to/this-runtime \
AIE_PROVIDER_KEY="$PRIVATE_PROVIDER_KEY" \
AIE_MAX_TURNS=12 AIE_JOB_TIMEOUT_MIN=3 \
node src/server.mjs

Use an address reachable from your deployment. Loopback works only when the caller is on the same host. Authenticate the model runtime according to its README and select a supported model. The development fallback key is not a deployment credential. The data directory holds private employee sign-ins and sessions; never serve or package it. A fresh isolated directory avoids resuming unrelated employees during a demonstration.

Provision the employee through POST /ai-employees/{name}/provision, then switch it on. Provisioning transfers its private sign-in to a provider that supports that contract. The employee remains unable to sign in while its user is locked. Do not display the handover password or authenticator seed in recordings or return it through the sample browser.

Verify both provider-status and the employee's own connection.firstSeenAt/hello. Then verify a real completed job. A green provider state alone cannot establish useful work. The stub provider explicitly creates no real agent. An external runtime cannot be inspected through the same provider contract; its own sign-in and hello provide a different kind of evidence.

Issuing a new manual handover replaces the prior employee sign-in. Use that deliberately for an external runtime; do not repeatedly rotate it to diagnose an unrelated job failure.

6. Native Chat and direct Workspace conversations

These are distinct integrations. The recorded example verifies both.

Native Chat: connect to the /chat Socket.IO namespace with the staff token and organization in the authentication handshake. Wait for authentication, emit create-chat with the employee participant, and retain ack.chat.chatId. Send the message through sendMessage, then inspect the saved history and the employee-authored reply. A missing acknowledgement is ambiguous: read history before sending the same message again.

The recorded native question receives the actual reply, “Yes, I can reply in this native Chat conversation.” The work item has source message and a ref whose datatype is chat. The runtime uses the employee's own Chat connection to answer.

Direct Workspace conversation: POST /workspace with type: "conversation", direct: true and the employee member finds or creates that private conversation. Save its returned id, post a message through /workspace/{id}/item, and read /workspace/{id}/items. Those items are flat presentation objects; their data field is an attachment/reference array, not a record wrapper.

A human message in a direct Workspace conversation reaches the employee without an explicit mention. The recorded identity reply is authored by the employee email. A message in a shared Workspace needs an explicit employee mention. Employee-authored messages do not recursively wake other employees through this intake.

Native Chat with genuine replies from the employee

Actual native Chat readback. The separate Workspace conversation is available through its own tab and contract.

7. Assign real work and inspect its result

Giving direct work through POST /ai-employees/{name}/work is useful for an instruction that is not already a business record. Assigning an existing task, ticket or lead is a separate entry into the queue.

The example creates a Workspace task with the employee email in task.assignTo. AppEngine produces a queued item with source: "assigned" and ref pointing to the actual task. Follow the work detail from queued to in-progress, inspect reported steps, and verify the original record after the job finishes.

In the recorded assignment the employee writes the requested internal Workspace message and marks its handling of the task done. Its first completion report also claims the task itself is done, but the actual task read still says new. The runtime used the handling command, which updates handling.status; it did not update the task's business status. The recovery sends the employee the exact Workspace task GET/PATCH path and requires a readback of status: "done". Do not manually change the task and present that as the employee's result. A separate rehearsal also showed why free-form completed is unsuitable: Workspace closed-task counts recognize done.

The work item's status and the task's status describe different objects. A done work item records the runtime's completion report; it does not automatically prove that the referenced task, ticket or lead reached its intended state. Keep the reference visible in the application and provide a direct way to inspect the affected record.

8. Build around leases, steps and recovery

A custom worker signs in as the employee, calls me/hello, reads me/briefing and requests a lease using its stable worker ID. The response contains work and profile/policy context; it does not issue a new worker JWT. The employee identity may act only for its own employee and work records.

No available job, inactive status, off-shift hours, exhausted budget and concurrency limits are different outcomes. Inspect the returned reason. Do not treat an empty lease as a failed request and create duplicate jobs.

Report meaningful steps while working. Complete only after verifying the intended result; report failure with an explicit retry choice when the operation did not finish. If a write may have succeeded but its acknowledgement or subsequent read failed, reconcile the target record before retrying. Increasing attempts is not a substitute for idempotent business operations.

The worker class in the companion demonstrates these contracts. It is an integration wrapper, not the AI engine. The recorded model execution comes from the existing real session-manager runtime.

9. Shared Workspace, goals and reports

Read GET /ai-employees/team to find the existing team Workspace. The first hire can create the private AI team and join the employee and hirer. Reuse that relationship; changing the organization team points all its employees at a different shared context.

Post a shared-room message with an explicit employee email in mentions. Read the resulting message work and same-Workspace reply. An unmentioned shared-room message should not be presented as equivalent to a direct conversation.

Workspace agendas organize goals; tasks can attach to an agenda, and meetings provide scheduled context. Inspect the actual agenda, task assignments and upcoming meeting context before claiming the employee can use them. The briefing can include this shared context; a saved future meeting does not by itself prove the employee attended or executed something at that time.

For reports, have the employee call its own summary for an explicit time window, then post the actual counts and titles. The recorded report used the returned summary and named a real completed job. Its count is a snapshot: completing the report itself changes later work totals. Do not compare it with a later all-time count and call the earlier report incorrect.

10. Approval is a work transition, not a blanket API firewall

The runtime must explicitly request approval before the selected action. The example asks to post one harmless internal review note with action: "other". The work becomes waiting_approval, the lease is released, and the human sees pendingApproval with the requested summary and category.

Approve or reject through /ai-employees/work/{id}/decide as the supervisor, never as the AI employee. After approval, the runtime obtains the work again, confirms the unchanged request is allowed, performs that action and verifies its saved result. Follow the same work ID through waiting, decision and completion.

Important current boundary: approval reuse on the same job matches the action category and, for money, its amount. It is not cryptographic binding of the complete summary or payload. Keep a job's approved action narrow and unchanged; use separate work/approval for a different operation. The broader API permission checks remain essential. Do not claim this approval API automatically intercepts arbitrary writes made by the runtime.

For rejection, the worker must not perform the declined action. It should report that outcome and leave the original target unchanged. Do not silently retry a rejected action under a different wording. The companion includes this branch even when the recorded demonstration uses approval.

11. Channels, claims and contact configuration

The employee's generated email is its staff identity; it is not automatically a deliverable customer mailbox. Actual contact information depends on configured email accounts and phone assignments. Listening settings decide which intake wakes an employee. Provider setup, queue participation, record claim and sending permission are separate choices.

An employee work lease prevents two workers from processing that employee job together. It does not necessarily claim the underlying shared customer chat or business record. Use the relevant Chat Agent Desk or handling operation before acting on shared customer work. Link the CRM APIs course when the implementation needs those business operations.

This demonstration keeps channels and phone assignments empty. It does not prove email delivery, a phone conversation or a customer handoff. Those require their actual provider and identity setup, intended recipient/session and a separately verified outcome. Do not turn a saved contact field into a claim of delivery.

12. Pause, budgets and memory

Pausing stops new work and locks the employee login; a token already held by its runtime does not bypass the next server-side identity check. Switching on unlocks the identity and allows permitted work again. Working hours and the employee timezone govern whether it is on shift.

The recorded control demonstration pauses the employee and switches it on again. After the demonstrations, the training employee was paused once more; readback showed no queued or active work. Its audit records and runtime data remain available for review.

Budget accounting uses costs reported by the runtime. Show actual spend and returned status; do not label a configured budget as a demonstrated hard stop unless that refusal occurred. Limits on concurrency and attempts serve different purposes.

Stored notes and resumable provider sessions are separate forms of memory. Inspect memory before removing it. Forgetting sessions changes what the provider can resume; it is not equivalent to deleting every business record or note. Restart, forget, pause and delete are distinct controls. Deleting an employee locks its identity and cancels unfinished work while keeping the audit records.

13. Configure an Assistant deliberately

Use the actual tool, capability and trigger registries to choose the supported behavior. The recorded Assistant starts with no tools and no triggers, then enables exactly one read-only tool, get_ticket, for a bounded lookup of an owned training ticket.

Be explicit about the tool list: current runtime behavior treats missing/null tools as all tools, [] as none, and a selected list as only those enabled tools. Do not omit tools when your intent is a text-only Assistant. Capabilities supply handling playbooks; they do not replace the executable tool selection. Triggers select incoming events and conditions; they are not necessary for a direct execute call.

Save active status, intended visibility, behavior rules, memory policy and selected tools. The recorded Assistant has no outgoing message tool or automatic trigger. Its internal visibility is not a customer-facing authorization promise: current execution checks the actual authenticated actor, and individual tools enforce their own data access.

14. Execute with the caller and inspect tool evidence

Invoke /crm/ai-assistant/{id}/execute with a specific task and the ordinary caller session. The course asks for the title and current status of training ticket S2RW5LX5. The recorded model calls get_ticket, receives the actual title “Preparing for my assessment” and status new, and answers from that result. The ticket is not modified.

Inspect both the natural-language answer and toolResults. A text answer that happens to look correct is not tool proof. The activity history records execution and tool use; it is useful for application review, but does not establish any external delivery that was never performed.

Ticket number or email is a lookup selector, not authentication. The current get_ticket tool passes the authenticated actor to TicketsService; customer and staff permissions differ. Do not replace that actor with a body field from an untrusted browser.

The streaming operation is an alternative for incremental UI feedback. Keep its events separate from a final saved business outcome. A test/execute result does not demonstrate every enabled trigger or action: exercise the particular workflow your application relies on.

Saved Assistant activity with the read-only tool result

Actual model answer after get_ticket returned the saved title and status. No ticket update or external message occurred.

15. Run and adapt the companion

Use the supplied custom client through its trusted Node host, keeping organization/session configuration outside the browser. The JavaScript/TypeScript wrappers use the official Appmint SDK's request transport; the Python client follows the same platform sequence. Native Chat uses the existing Socket.IO contract. The examples do not invent a separate employee SDK.

Configure your own employee handle, conversation, team Workspace and Assistant IDs from real create/read responses. Never copy recording-only private sign-ins. The README explains the runtime checkout, environment settings, direct request examples, expected outcomes and limitations. The downloadable package includes the runnable sample UI and trusted host, JavaScript/TypeScript/Python examples, curl and Postman requests, the existing session-manager runtime source, and the official JavaScript SDK snapshot. Follow its README to install dependencies and use your own organization and identities.

For your application, expose specific operations and render their meaningful state: the selected identity, queued or waiting work, approved action, saved task, employee-authored message and actual tool result. Leave changing complete schemas in the maintained API reference, linked beside the implementation.

Limitations and checks

Current local rehearsal verifies real session-manager provisioning, own-identity hello, direct Workspace reply, native Chat reply, source:assigned work, internal task/message changes, actual summary-based reporting, a waiting approval and bounded AI Assistant execution with a real read-only ticket tool. The approved internal note was written exactly once and the same work item completed. Final capture outcomes are tracked in the production evidence; the course is not a released video merely because its manuscript is updated.

No physical action, customer payment, outgoing email, SMS or phone call is part of this demonstration. documented alternatives are identified in their section rather than presented as observed outcomes.