Migration notes

These notes describe the APIs in the current SDK checkout. Pin the Go module and frontend package versions used by your application. Persisted history and durable execution histories may need separate compatibility handling.

​

Public API changes

​

Skill clients and selection

Import pkg/agents/skills. Folder and embedded sources are now NewDirSource and NewFSSource; inline bundles use NewBundleSource, and an application-managed store namespace uses NewStoreSource. Globals are always enabled and cannot be overridden by user content. Duplicate global names fail catalog construction. User skills are enabled by default; agents.SkillSelection has only Disable. Remove old Enable lists and per-entry required/blocked/optional policies. HTTP clients send forwardedProps.skills: {"disable":[...]}. The client methods take namespace explicitly: ListSkills(ctx, namespace, runContext) and ReadSkill(ctx, namespace, runContext, name, file). The agent picker API adds a selection argument. A run-context key named Namespace is not a storage scope. Existing bundle stores still provide complete-bundle persistence, management APIs, and listing caches. See Skills and Skill storage.

​

MCP stores and credentials

Define servers with mcpclient.ServerConfig in a memory, file, or custom store. Use WithMCPServerConfig for developer-owned inline definitions. Client configuration uses WithCredentials and WithSchemaCache; transport, filters, approval rules, metadata, and OAuth application settings belong in each server definition. Global records have an empty namespace and stay enabled. User records are namespace-scoped and enabled unless disabled by Input.MCP. Per-run tool filters narrow the configured filters. Dynamic configuration and browser OAuth management are supported; old documentation describing them as future features no longer applies. Custom MCP clients implement ListTools(ctx, namespace, runContext, ...selection) and CallTool(ctx, descriptor, call). Update workflow Dependencies.MCPServers to map[string]agents.MCPClient.

​

Cache contracts

MCP SchemaCache and skills KeyValueStore independently define Get(ctx, key) ([]byte, bool, error), Set(ctx, key, value, ttl) error, and Delete(ctx, key) error. Concrete memory and Redis implementations live in pkg/cache. There is no cache-wide Clear contract. Configure MCP cache TTL/scope on server definitions and skill cache TTL on the store.

​

Delegation and paused background tasks

AgentConfig.Description describes a delegation target. SubAgents supplies a catalog through subagents.NewClient, and the model calls call_sub_agent in sync or async mode. Existing fixed-target integrations can use tools.NewAgentTool or tools.NewAsyncAgentTool. Async children that need approval stay pending. Clients read the child’s agentName, agentThreadId, and interrupts from the parent’s run.backgroundTasks and resume the child thread. BackgroundResult.Waiting keeps the task open rather than delivering a final result. A sync call_sub_agent does not relay approval through its parent; synchronous NewAgentTool does.

​

Persistence and identifiers

Custom ConversationPersistenceAdapter.SaveMessages now accepts parentThreadID string and hidden bool after groupID. Preserve group, parent, and hidden attributes through continuations, forks, and incremental saves. Same-run saves append message increments and update non-nil metadata, including metadata-only writes. history.Message.CreatedAt stores bundle time. Older rows can omit it. AG-UI includes metadata.createdAt and sender attribution when hydrating history. Thread listings hide internal threads by default; use include_hidden=true and the appropriate group when listing children. Keep namespace, thread, session, run, and stream identities distinct. Session sharing permits attachment access without sharing a child’s transcript. A stream is an observation channel and may be reused across turns; it is not a workflow execution identity.

​

Sandbox state and attachments

Sandbox acquisition uses the provider reference persisted in run state. Pass a profile name to the tools, preserve their state updates, and supply workdir explicitly; shell cd affects one invocation. Concurrent runs sharing a sandbox session are unsupported. Owned attachments use file_id: "attachment://...". With attachment middleware, images inline by default, while files are references unless InlineAttachments is true. Use ToolResponseMiddleware before attachment middleware to bound and optionally store large tool output.

​

Durable deployments

Skill, MCP, history, and background-task payloads have changed. Deploy compatible workers for existing Temporal/Restate histories, or drain/version old executions before changing activity signatures and workflow behavior. Conversation data migrations and runtime replay compatibility are separate concerns. Construct agents with WithRuntime(runtime) before calling Serve; constructors do not launch workers. The runtime exposes its broker, while stores and other caller-owned resources remain yours to close after execution stops.