An Agent template is a JSON or YAML file that bundles an Agent’s identity, system prompt, tool activations, and per-operation auto-approve defaults. Templates are the canonical way to share Agents across environments and to ship curated “starter” Agents in plugins.

What travels in a template:

• Agent identity: name, description, system prompt, max steps, allow followup, retry config.
• Tool activations: per-tool enabled flag.
• Per-operation auto_approve flag (mapped from the agent’s agent_tool_operation_overrides row).
• Agent-specific, non-secret tool settings (e.g. the active skill allowlist) — only when the operator opts in via ?include_settings=1 on the export request. Secrets and inherited global/user values are never included.

Discovery

Templates are discovered from three sources, scanned in priority order:

1. The project-level <base>/agent-templates/ directory (if it exists).
2. The framework’s bundled <spora-core>/agent-templates/ directory (currently core-assistant.json).
3. Every directory returned by any loaded plugin’s agentTemplatePaths() hook.

Operators can ship templates with a plugin by overriding the hook:

public function agentTemplatePaths(): array
{
    return [__DIR__ . '/../agent-templates'];
}

The scanner walks each directory depth-0, parses .json / .yaml / .yml files, and validates each via AgentTemplateValidator. Parse or validation failures surface as warnings on the AgentTemplate — they are never silently dropped.

HTTP surface

Method	Path	Purpose
GET	/api/v1/agent-templates	List built-in + plugin templates
GET	/api/v1/agent-templates/{id}	Get one template (full payload + warnings)
POST	/api/v1/agent-templates/validate	Dry-run validation of a raw payload
POST	/api/v1/agent-templates/import	Create an Agent from a payload
GET	/api/v1/agents/{id}/export	Export an Agent as a template JSON

The export endpoint returns inline_warning on the default (no-settings) path and inline_info on the opt-in path. The opt-in path’s inline_info banner lists which tools contributed settings and reminds the operator that passwords and inherited global/user values are still NOT included.

Importer semantics

AgentTemplateImporter applies a template in a single transaction:

1. Insert the Agent row mirroring the template’s agent block.
2. For each tool entry:
   • Tool class not registered (plugin missing) → emit TOOL_PLUGIN_MISSING warning + skip.
   • Tool registered but missing global config → still insert the row + emit TOOL_NEEDS_CONFIGURATION.
   • Tool disabled → no row inserted.
3. For each operation on each tool: upsert agent_tool_operation_overrides (auto_approve:true → default_requires_approval:0). Preserve three-state null semantics.
4. Set agents.recipe_id = $template->id for traceability.

Plugins are never auto-installed. A slug in required_plugins that is not loaded produces a PLUGIN_MISSING warning but does not abort the import.

Round-trip example

1. Operator configures an Agent in the UI, toggles auto_approve: false on a few save operations.
2. Clicks Export on the agent toolbar → downloads {template-id}.json.
3. Shares the file. Recipient clicks Import template on their dashboard, picks the file.
4. The validator reports no warnings (all plugins installed) or lists missing-plugin warnings.
5. Recipient clicks Import anyway; the Agent is created with the same activation + auto-approve configuration.

Schema

The full JSON Schema is published at:

• https://docs.spora-ai.com/schemas/agent-template.schema.json (served from docs/.vuepress/public/schemas/; mirrored at build time from spora-core/agent-template.schema.json)

See Agent template schema reference for the field table and examples.

Edit this page on GitHub

Contributors: Fabian Graßl

Previous pageArchitecture

Next pageAgent loop & async