AI Agents

AI agents are first-class entities in Nembl that operate alongside users in the entity hierarchy. They triage requests, assist with service intake, execute workflow phases, and automate routine decisions — all governed by the IAM policy engine.

Sources: Managed vs Custom

Every agent has a source that determines who owns its behavior:

MANAGED vs CUSTOM — which to pick

Default to MANAGED. Reach for CUSTOM only when behavior diverges meaningfully from what the managed agents cover.

Pick MANAGED to get value out of the box; pick CUSTOM when you have specific behavior the managed agents don't cover.

External agents

External agents are customer-hosted: you run the agent code in your own infrastructure (any language, any framework — LangChain, LangGraph, OpenAI SDK, a Lambda, an MCP toolkit), and Nembl dispatches workflow-phase events to your endpoint when the phase activates.

How the responsibilities split

Two transports

• WEBHOOK — Nembl POSTs a signed envelope to your HTTPS endpoint; you reply with an AgentResult. Lowest barrier; works with anything that can receive HTTP.
• MCP — Nembl acts as an MCP client against your MCP server; you expose a single tool that returns an AgentResult via structuredContent. Best fit if you've already built MCP tools.

A2A is reserved for a future release.

Capabilities + auth

Register a connection at Admin → External Agent Connections → New Connection. You declare:

• Capabilities — an allowlist of workflow actions your endpoint may propose (add_comment, create_task, update_variables, request_approval, escalate, advance_phase, …). Anything outside the allowlist is dropped server-side.
• Auth type — BEARER, API_KEY_HEADER, or HMAC (webhook only — HMAC is recommended; MCP supports BEARER and API_KEY_HEADER). The auth secret lives in your Nembl Vault and rotates with the vault.

Then create an Agent (Admin → IAM → Agents → New Agent), pick the External backend, and link your connection. Same RACI engagement, same autonomy levels, same audit trail as MANAGED and CUSTOM agents.

When to pick EXTERNAL vs MANAGED / CUSTOM

See the full integration contract at External Agent Contract. Working reference receivers (webhook + MCP) live under docs/examples/ (opens in a new tab) in the repo.

Agent Types

Three agent types map to where the agent operates in the request lifecycle.

Queue Intake Agent

Attached to an inbox/queue. Decides intake outcomes (accept, reject, route, prioritize) when a request lands.

Service Assist Agent

Attached to a service or offering. Helps users complete request forms during submission.

Workflow Phase Agent

Assigned as a Responsibility (Responsible / Accountable / Consulted) on a phase. Runs when the phase activates.

The Phase Advisor managed agent listens for nembl.workflow.phase.start events and acts as the CONSULTED agent on phases that need analysis.

Providers

Nembl runs agents on provider-specific handler functions. The Provider you pick determines which handler executes the agent and which API key it uses.

The default for new agents is Anthropic (the v1 default). OpenAI is selectable in the UI today; Bedrock is on the roadmap for the agent admin UI.

BYOK — Bring Your Own Key

Each agent invocation uses your Anthropic / OpenAI API key, not Nembl's. You provide keys via a Nembl Vault; the agent invocation handler fetches the matching vault value at run time (the agent's effective principal needs secret:reveal permission on the bound vault).

Why BYOK?

• Audit + spend control — every prompt/response shows up in your provider's console; you control rate limits and budgets.
• Compliance — sensitive prompt content never traverses Nembl-shared infrastructure with other customers' keys.
• Bedrock alternative — companies that need to keep all inference inside their own cloud account use Bedrock instead; the inference call resolves against their own Bedrock entitlement.

If a key is missing, expired, or rejected, the agent's AgentLog row records errorCode: API_KEY_UNAUTHORIZED and the agent stays at INACTIVE status until the key is replaced.

RAG — Retrieval-Augmented Generation

Agents can ground their responses in your company's own documentation, runbooks, and reference material via Retrieval- Augmented Generation (RAG). Instead of jamming every prompt document into the agent's system prompt (which is slow, expensive, and quickly exceeds context limits), Nembl indexes your documents into a vector store and retrieves only the relevant chunks at invocation time.

How it works:

1. You add prompt documents to your company library — articles, SOPs, FAQs, anything textual the agent might need to reference
2. Nembl embeds each document on write (fire-and-forget) using the configured embedding provider. Voyage is the primary provider for v1; OpenAI is the fallback if Voyage is unavailable. Customers don't choose — the platform picks
3. At invocation time, the agent calls the retrieve_documents MCP tool with a query string. The tool returns the top-N most semantically similar chunks with similarity scores
4. The agent uses those chunks as grounded context for its response or tool calls

Access policies: RAG respects the same tag-based ABAC policies as the rest of Nembl. If a document is tagged sensitivity: high and the agent's effective principal doesn't have a policy allowing read on high-sensitivity documents, the chunk won't appear in retrieval results. The agent can't bypass tag policies by clever phrasing — the filter applies before the agent ever sees the chunks.

Updates take effect on the next invocation. Edit a prompt document and the re-embedding fires fire-and-forget; subsequent retrieve_documents calls use the new embedding without any explicit reindex step.

When NOT to use RAG: If the content is short enough to fit in the agent's system prompt comfortably and is needed on every invocation, putting it in the prompt directly avoids the retrieval round-trip. RAG shines for medium-to-large libraries (10s to 1000s of documents) where only a few are relevant to any given query.

Configuring an Agent

1. Admin → IAM → Agents → New Agent
2. Pick the Type (Queue Intake / Service Assist / Workflow Phase)
3. Pick the Source — MANAGED to use a Nembl-provided agent template, or CUSTOM to define your own
4. Pick the Provider + Model
5. Bind a Nembl Vault that holds the API key (BYOK)
6. Set the Autonomy Level
7. Save as INACTIVE; flip to ACTIVE once the agent is wired to its scope (queue / service / phase)

The agent JSON config persists under Agent.config (and Agent.baseConfig for MANAGED templates). Customers usually don't edit it directly — the admin UI exposes the relevant fields per type.

Autonomy Levels

Autonomy levels control how independent the agent can act. Set globally per agent and overridable per assignment when used as a workflow Responsibility.

Agents are also bound by the IAM policy engine. A "Fully autonomous" agent can still only take actions its assigned IAM Role allows — Deny policies create hard guardrails that no autonomy level can override.

Prompt Layers

Nembl uses a hierarchical prompt system. Each layer adds context; the most specific layer takes precedence on conflicts.

Company prompt    → "We are a B2B SaaS company. Always be professional."
  ↓
Organization prompt → "Engineering: reference our coding guidelines."
  ↓
Team prompt        → "Frontend team: focus on UI/UX quality."
  ↓
Agent prompt       → "Triage incoming feature requests by impact."

For MANAGED agents the agent-level prompt is fixed (managed by Nembl); customer prompts apply at the Company / Organization / Team layers above.

Monitoring

AgentLog

Every invocation writes one AgentLog row with:

• action — e.g. intake_triage, workflow_phase, service_assist
• input / output — what the agent received and decided
• policyResult — ALLOWED or DENIED (the policy engine's verdict before the call)
• status — SUCCESS / ERROR / POLICY_DENIED / CANCELLED
• errorCode — populated on failure (e.g. API_KEY_UNAUTHORIZED, PROVIDER_ERROR)
• decision — agent's structured outcome (e.g. accept, reject, flag_for_review)

View per-agent logs from Admin → IAM → Agents → <agent> → Activity.

AgentInvocation

Handler-side invocation tracking, including provider latency, token counts, and cost estimates. Surfaces in Admin → Analytics.

Best Practices

• Start at "Suggest" autonomy. Let the agent recommend for a couple of weeks while your team evaluates it. Promote to higher autonomy as confidence grows.
• Bind per-agent IAM Roles. Even Fully Autonomous agents are subject to the policy engine. Use Roles + Deny policies as hard guardrails.
• Pick MANAGED first. Most use cases are covered by the managed agents (inbox triage, phase advisor, service assist). Reach for CUSTOM when behavior diverges meaningfully.
• Use Bedrock when inference can't leave your own cloud account. Companies with strict data residency requirements should pick Bedrock as the provider so all inference resolves against their own Bedrock entitlement.
• Monitor cost and policy denials. A high POLICY_DENIED rate usually means the agent has tools enabled that its Role doesn't allow — tighten the agent's tool list rather than loosening the Role.