Bundle capabilities with plugins

A Plugin bundles instructions, skills, tools, and hooks under one name. Pass plugins when building an inline agent. The SDK expands them into the agent's existing configuration before any session starts.

Attach a bundle

import type { Plugin } from 'cosmo-ai';

const guidance = {
  name: 'guidance',
  instructions: 'Explain one step at a time.',
  skills: [{
    name: 'first-project',
    description: 'Help someone create their first project.',
    body: 'Ask what they want to build before suggesting a project name.',
  }],
} satisfies Plugin;

const agent = client.agent({
  instructions: 'Keep explanations brief.',
  plugins: [guidance],
});

from cosmo_ai import Plugin
from cosmo_ai.skills import Skill

guidance = Plugin(
    name="guidance",
    instructions="Explain one step at a time.",
    skills=[Skill(
        name="first-project",
        description="Help someone create their first project.",
        body="Ask what they want to build before suggesting a project name.",
    )],
)

agent = client.agent(
    instructions="Keep explanations brief.",
    plugins=[guidance],
)

import CosmoRealtime

let guidance = Plugin(
    name: "guidance",
    instructions: "Explain one step at a time.",
    skills: [Skill(
        name: "first-project",
        description: "Help someone create their first project.",
        body: "Ask what they want to build before suggesting a project name."
    )]
)

let agent = try client.agent(
    instructions: "Keep explanations brief.",
    plugins: [guidance]
)

Add tools and hooks to the same bundle using the ordinary tool constructors and hook factories. Bundle skills as parsed Skill values. Distribute the bundle through an ordinary language package or a local module.

Combine bundles

Pass plugins in the order their contributions should run. The SDK appends directly supplied agent contributions after every plugin:

• Nonempty instruction strings join with a blank line. This is text composition, not a guaranteed model instruction-priority policy.
• Skills, tools, and hooks retain declaration order. Multiple hooks may match the same event and keep the existing hook behavior.
• Duplicate plugin names, cross-bundle skill names, client-tool names, or server-tool kinds throw PluginError during agent construction. Its code is duplicate_plugin_name, duplicate_skill_name, or duplicate_tool_name. Messages identify the conflicting contributions. Direct skill inputs still undergo ordinary SkillError validation first.

Read the effective contributions from the built agent's instructions, skills, tools, and hooks. Plugin names do not namespace or rename their contents. An empty plugin list preserves ordinary agent construction.

Manage callback resources

Plugins are configuration bundles. They have no setup, teardown, installation, or discovery lifecycle. A bundle's callbacks follow the same rules as directly supplied callbacks; captured mutable state is not cloned for each session. Own resources in your application and use existing hooks where appropriate.

Plugins attach to inline agents through agent. Catalog agents run their stored persona and do not accept plugins.

Next steps

• Skills for loading detailed procedures on demand.
• Hooks for callback ordering and execution behavior.