AI API Mapper
Technical walkthrough →
Technical walkthrough →
/ docs · functional specification

The full platform
functional reference.

Every functional area of AI API Mapper documented at implementation depth so architects, security reviewers, and platform engineers can evaluate the product with real technical context.

A2A · Hosted Agent mode
On this page

A2A Hosted Agent Mode

Purpose

This functional area lets an administrator turn a registered agent into an LLM-backed reasoning agent that runs inside ApiMapper, instead of a proxy to a remote peer. Where Concentrator mode answers "who else can our agents talk to," Hosted Agent mode answers "can our own agent understand an incomplete or ambiguous request instead of just failing it" — the gap that made task resumption (input-required) impossible for server-mode skills before this existed: recognizing "this request is missing something" is a semantic judgment, and a deterministic Mapping-tool skill has no way to make one.

Main Capabilities

  • give a registered agent a system prompt and an LLM connection, turning it into a HostedAgent
  • define one or more Skills on a hosted agent — a name, a skill-level prompt, and an explicit, curated subset of the tenant's MCP toolsets and ESRA (knowledge-base retrieval) exposures marked available to Hosted Agents
  • mark an MCP toolset or an ESRA exposure "Hosted Agents only" or "MCP clients + Hosted Agents" (in addition to the existing "MCP clients only") — a toolset built purely for agent use needs no MCP client application assigned to it at all
  • a skill's LLM turn recognizes an incomplete request and pauses the task (TASK_STATE_INPUT_REQUIRED) instead of failing it, asking a clarifying question the caller can answer to resume the same conversation
  • a skill's LLM turn recognizes a credential-rejected downstream call (401/403) and pauses the task (TASK_STATE_AUTH_REQUIRED) the same way, distinguishing "the request was wrong" from "the credentials need fixing"
  • every tool the LLM invokes goes through the exact same governed invocation pipeline — authorization, credential brokering, downstream call, audit — a deterministic skill invocation uses; the LLM never gets a bypass path to a downstream API
  • every LLM turn is audited with its actual decision content — which tool it chose (if any), the clarifying question it asked (if any), and the turn's token spend — not just success or failure

How It Works

Choosing a kind: RemoteAgent or HostedAgent

RegisteredAgent carries a Kind set once at creation and never changed afterward (delete and recreate to change it — there is no migration ceremony for switching kinds). A RemoteAgent carries a target system and authentication profile, exactly as Concentrator mode already describes. A HostedAgent carries a system prompt and a reference to an existing LlmConnection instead — the same connection type the Portal's AI Settings page already manages for semantic enrichment, reused as-is rather than duplicated. Only one set of fields is ever populated for a given agent; the other kind's fields are always null.

Authoring Skills

A Skill is the unit an admin actually designs around: a name (also the A2A skillId a caller addresses), a description, a prompt fragment appended to the agent's own system prompt for that skill's turns, and an explicit set of individual tools it may call — picked from the tenant's MCP toolsets and ESRA exposures that are marked available to Hosted Agents. A skill is not required to correspond to a single tool: one skill can bundle a handful of search tools drawn from several different toolsets (e.g. "search job postings" across three separate job-board toolsets) while deliberately leaving out each toolset's write-shaped tools (e.g. "create job posting"), something a whole-toolset grant could never express. A sibling skill on the same agent can draw from a completely different set of toolsets/exposures. This is the primary structural defense against prompt injection: a skill's LLM turn can only ever see and invoke the exact tools the admin selected, never a toolset's or exposure's full tool list, never another skill's tools.

Binding a Skill to individual tools drawn from McpToolsets and ESRA exposures — rather than to whole Mappings — means a Hosted Agent's tools reuse exactly the same downstream call configuration (target system, credential binding, schema discovery, per-endpoint overrides) that MCP clients already use for the same toolset, and the same governed knowledge-base retrieval configuration ESRA exposures already resolve. There is no separate resolution path to keep in sync.

Running a turn

When a caller sends a message naming a hosted agent's skill, the platform builds a reasoning agent scoped to exactly that skill's prompt and exactly that skill's tools, runs the caller's message through it, and looks at what happened:

  • If the LLM invoked a tool and the downstream call succeeded, the task completes (TASK_STATE_COMPLETED) with the tool's result.
  • If the LLM invoked a tool and the downstream call failed with a credential-shaped status (401/403), the task pauses (TASK_STATE_AUTH_REQUIRED) instead of failing outright.
  • If the LLM invoked a tool and the downstream call failed for any other reason, the task fails (TASK_STATE_FAILED) with the tool id and downstream status preserved, not swallowed.
  • If the LLM did not invoke any tool at all this turn, that is read as a request for more information — the task pauses (TASK_STATE_INPUT_REQUIRED) and the LLM's response becomes the clarifying question. No separate "incompleteness detector" exists; recognizing insufficient information is inherent to a competent LLM's own tool-selection judgment.

A paused task's full conversation state is serialized and persisted alongside the task record. A caller's follow-up message, correlated by the same context id the original request used, resumes that exact conversation rather than starting over — the LLM sees the original request and the new information together in one continuous session, so ApiMapper never has to mechanically merge two partial payloads itself.

Prompt-injection defense

Two layers, both mandatory, neither sufficient alone:

  1. Structural tool scoping — a skill's LLM turn only ever has the tools the admin explicitly assigned to it. This bounds the damage a successful injection can do regardless of what the caller's message says, because there is nothing outside the assigned tool set to redirect the LLM toward.
  2. Message-role separation — the admin-authored system prompt and the caller's message text travel on distinct channels into the model; caller-supplied text is submitted only as the conversation's user turn and can never rewrite or append to the system-level instructions.

Governance and audit

A hosted agent's skill invocation is authorized through the same access-policy check Concentrator mode uses (agent, optionally narrowed to a skill, caller, client application) — one governance model for both kinds of registered agent, not two. Every turn is audited under the platform's existing runtime category, carrying the LLM's actual decision (the tool it chose, the clarifying question it asked, if any) and the turn's token spend, alongside the same allow/deny/error outcome every other governed call records.

Functional Value

This closes the gap that made server-mode task resumption impossible: a caller talking to a hosted agent gets a genuine back-and-forth instead of an all-or-nothing call, without the platform ever having to mechanically approximate "did the caller give me enough information" — the judgment an LLM is actually good at — and without giving the LLM any capability outside the exact governed tools an administrator explicitly curated for it.

PreviousConcentrator modeA2ANextPush notificationsA2A