AgentKit Studio
Concepts

Resources and bindings

The five bindable resource kinds, their exclusivity rules, credential references, and degradation.

A resource binding attaches external capability to one revision. There are only five kinds: model, MCP, Skill, knowledge base, and memory. Credential values never enter a binding — they stay on the Host.

This page covers each kind's shape, which combinations are exclusive, how credentials must be written, and what the product does when a bound resource is unavailable.

A revision at the centre connected down to five bindings — model profiles, MCP bindings, skill spaces, knowledge base and memory; all five resolve credentials through the Host credential service, and plaintext flows only from the Host to the model gateway, MCP server and AgentEngine, never back to the browserA revision at the centre connected down to five bindings — model profiles, MCP bindings, skill spaces, knowledge base and memory; all five resolve credentials through the Host credential service, and plaintext flows only from the Host to the model gateway, MCP server and AgentEngine, never back to the browser (dark)点击放大 · 滚轮缩放 · 拖拽平移

How to read this: bindings are frozen with the revision, so swapping a resource means a new revision. The credential path is one-way — the Host resolves the reference and calls the provider itself, leaving only the reference in the revision. The browser, form back-fill and transcript never see the plaintext.

Why a binding layer exists

The resource library owns only the resource catalog's lifecycle: discovery, import, probe, view, delete, and status refresh. Adding or changing which resource an agent uses must happen on the agent creation or editing page — two different actions, and conflating them leads to a wrong conclusion: that deleting a row in the library unbinds it.

Bindings live on the revision, so:

Your actionResult
Refresh status in the resource libraryAffects catalog display only; no agent changes
Swap an MCP server on the agent editing pageProduces a new revision; the old revision keeps its binding
Delete a cloud resource in the libraryThe cloud resource is cleaned up; existing bindings become unavailable

The five kinds

kindUI labelSourceHow many per agentBinding field
modelModelLocal model profiles plus the model gatewayMany, one of them defaultModel profile
mcpMCPLocal MCP catalog plus the cloud catalogManymcp_servers[]
skillSkillInstalled Skills plus cloud Skill SpacesManyskill_space / skill_spaces[]
knowledge-baseKnowledge baseCloud control planeOneknowledge_base
memory-instanceMemoryCloud control planeOnememory

The model kind is special: it merges locally configured model profiles with the model gateway catalog. Local profiles report status as configured or credential-missing; gateway entries report available. A profile missing credentials still appears in the list, marked rather than silently hidden.

Hard rules of the managed resource contract

Managed-side resource references use agentengine.resources/v1, which accepts exactly five fields: knowledge_base, memory, skill_space, skill_spaces, mcp_servers. One extra field invalidates the whole object (MANAGED_RESOURCE_INVALID).

RuleConstraint
Exclusivityskill_space and skill_spaces cannot both appear
List limitsskill_spaces and mcp_servers allow at most 16 entries each
Reference IDMatches ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$
RegionMatches ^[a-z0-9][a-z0-9-]{0,63}$
Direct MCP endpointHTTP(S) only, at most 2048 characters, no embedded username/password and no query string
Direct MCP transporthttp or sse only
Duplicate IDsNot allowed within one list

Credential references: the only correct syntax

Write credentials as env:// plus a name. Never write plaintext. Plaintext is not an unsafe habit; it is rejected:

LocationRuleViolation code
Local MCP header nameOnly x-request-source, x-skill-version, x-*-client, x-*-surface, accept, content-typeMCP_HEADER_REQUIRES_REFERENCE
Local MCP header valueMust not contain a ${...} placeholderMCP_HEADER_REQUIRES_REFERENCE
Local MCP environment variable nameNames containing TOKEN/SECRET/PASSWORD/API_KEY must use a referenceMCP_ENV_REQUIRES_REFERENCE
Local MCP reference valueMust match env:// plus a legal nameMCP_ENV_REF_INVALID
Managed env_refs variable nameMatches ^MCP_[A-Z0-9_]{1,124}$ and contains one of KEY/TOKEN/SECRET/PASSWORDMANAGED_RESOURCE_INVALID

The managed side additionally blocks a header list: host, connection, content-length, transfer-encoding, accept, content-type, mcp-protocol-version, mcp-session-id, plus three prototype-pollution names. That list guards against request smuggling and protocol confusion, not style.

Why credentials stay on the Host

An MCP catalog record stores connection metadata and the last probe contract only; credential values belong to the DSH credential service. Writing a credential into a binding writes it into a file that ships with the build artifact.

Platform resources: three separate lists

Knowledge bases, memory instances, and Skill Spaces go through the platform resource channel and can only be selected from the cloud catalog, never typed by hand. Their binding configuration differs:

kindWhat the agent gainsKey configuration
knowledge-baseRead-only retrievalmode: tool, topK: 5, maxChars: 16000
memory-instanceCross-session recall and write-backWrite mode defaults to explicit_only
skill-spaceDiscovery and loading of cloud SkillsselectionMode: discovery, includePublic: false, executionMode: outer-agent

Selection projects selectable metadata only (name, region, disabled flag, status). Backend credentials and internal configuration are never returned to the browser.

Degradation and strict mode

An unavailable binding is not an exception; it is an expected state. The default is to keep the conversation usable and drop only the unavailable binding:

ItemDefault behaviorStrict mode behavior
A binding fails its probe when starting a sessionUsable immediately; that binding is removed and the rest continueFail closed; refuse to start
The promptStays byte-identical; one network blip never rewrites itSame as default
Background re-probeAt 30 seconds, 2 minutes, and 10 minutes after degradationNone (failure is terminal)
RecoveryAny strict probe that succeeds restores the full binding setNot applicable

The re-probe delays are offsets from the moment of degradation, not a fixed period. Three failures leave the preset degraded until the next explicit session start.

One exception: an unresolvable model route cannot start degraded. A degraded run fails immediately (RUNTIME_MODEL_UNAVAILABLE), so only a caller that explicitly opts into running with unavailable resources reaches that point. The degradation code itself is RESOURCE_UNAVAILABLE.

Resource check events

Every real resource call appends one studio/resource-check event to the session. It is content-free evidence: kind, resource ID, action, duration, and outcome — no return value, no arguments, no credentials.

FieldValues
kindskill, skill-space, knowledge-base, memory-instance
actionload, search, recall, write
statussucceeded, failed
OptionaldurationMs, hitCount, definitionCount, accepted, code

This event is the only evidence that a resource was actually called. "Ready" in the catalog does not mean the agent invoked it successfully.

Catalog pagination rules

The resource catalog has hard limits because it merges local and cloud sources:

RuleValue
Page size1–200, default 100
Source filterall / local / cloud; anything else raises INVALID_RESOURCE_SOURCE
CursorBound to the filter values; a changed filter invalidates the old cursor (INVALID_RESOURCE_CURSOR)
DeduplicationBy resourceId, local wins
OverviewAt most 200 entries per kind, then RESOURCE_OVERVIEW_TRUNCATED
Oversized cloud catalogMore than 1000 pages raises RESOURCE_CATALOG_TOO_LARGE
What you needWhich page
The full fields and enumerations of the five kindsRuntime and entity contract
MCP_* and RESOURCE_* error codesErrors
Resource-related environment variablesEnvironment
The full degradation and retry policyDegradation and retry

On this page