How-to

How to create a new Buffaly agent

Create a named runtime profile with its own master prompt, action/entity roots, provider defaults, UI behavior, and validation path.

Use this advanced workflow only when you need a new named agent experience, not just one new action, workflow, service, or tool.

Quick answer

A Buffaly agent is a named runtime profile loaded from active project Agents/*.agent.json. The profile points at a prompt file, applies session defaults, composes the system prompt, and registers tools from the configured action root.

Decide why the agent needs a separate profile.
Create a new master prompt file.
Add Agents/<agent-name>.agent.json.
Choose root action and entity prototypes.
Choose a context prompt only if the agent needs that overlay.
Pick provider/model defaults only where the catalog supports them.
Create a test session and validate prompt behavior, discovery, model selection, and artifacts.

What a Buffaly agent is

A Buffaly agent is a configured session persona and capability boundary. It is not just a display name and not just a prompt.

Profile field	User/operator meaning
AgentName	Stable name used to load the profile.
DisplayName	UI-friendly label.
PromptFile	Project-relative file that becomes the master prompt.
PromptContext	Optional context-prompt name used as an overlay.
RootActionPrototypeName	Root for callable actions and tools available to this agent.
RootEntityPrototypeName	Root for ontology/entity context included in the agent prompt.
Provider / DefaultModelName	Provider/model defaults where runtime and catalog support them.
UiPage, IsReadOnly, IsHidden, CanChangeModel	UI page and operator behavior flags.

What the master prompt controls

The master prompt defines the agent role, operating rules, safety expectations, output style, validation expectations, and when to ask questions. It does not install tools, add services, create credentials, or grant access to every ontology object.

Source resolves PromptFile relative to the project root, reads it into MasterPrompt, and then session initialization uses that prompt unless a session-level override already exists.

Ask Buffaly to create it

The safest path is to ask Buffaly to make the profile and prompt changes with verified validation.

Create a new Buffaly agent profile called release-critic. It should be a read-only review agent for release readiness. Inspect existing Agents/*.agent.json profiles and prompt files first. Create a new master prompt, create the matching profile JSON, use the smallest appropriate action/entity roots, validate the profile loads, verify tool/action discovery is scoped correctly, and commit only intentional files.

Manual workflow

Find the active project root and inspect existing Agents/*.agent.json profiles.
Create the master prompt under the project prompt area.
Create Agents/<agent-name>.agent.json with explicit fields.
Use stable AgentName and UI-friendly DisplayName.
Keep PromptFile project-relative and verify the file exists.
Use PromptContext as a name only; source resolves ContextPrompts/<PromptContext>.prompt.md.
Choose RootActionPrototypeName and RootEntityPrototypeName to match the capability boundary.
Verify provider/model defaults against the provider catalog.
Match existing UI flags for UiPage, IsReadOnly, IsHidden, and CanChangeModel.
Create or load a test session and commit only intentional files.

Connect skills, services, tools, context, and providers

Skills and tools

Tools are registered from the session's RootActionPrototypeName. Use a narrow root for a narrow tool surface.

Ontology/entity context

RootEntityPrototypeName controls which entity anchors appear in prompt context.

Context prompts

A context prompt is an overlay, not the master prompt. Do not put path separators in PromptContext.

Services and providers

Services need registration/projection paths. Provider and model defaults must match the running provider catalog.

Validate the new agent

Profile resolves by exact AgentName.
PromptFile exists and contains the intended master prompt.
A session can be created or loaded with the new agent.
Master prompt and optional context prompt affect behavior.
Action discovery exposes only intended root capabilities.
Entity context reflects the intended root boundary.
Provider/model exists in the provider catalog.
Plan, Scratch, timeline, and task artifacts write under the configured sessions root.
UiPage opens the expected page.
The agent follows role boundaries and does not expose secrets.

Troubleshooting

Profile not found

Check the active project Agents directory, .agent.json extension, and exact AgentName.

Prompt file missing

Keep PromptFile project-relative and point at an existing file.

Context prompt omitted

PromptContext is a name only; missing files omit the overlay.

Tools or entities missing

Check RootActionPrototypeName, RootEntityPrototypeName, ontology placement, and semantic annotations.

Model selection fails

Check the provider catalog and DefaultModelName.

Behaves like default agent

Confirm the session uses the new AgentName and no session MasterPrompt override is preserving old text.

Choosing extension boundaries Master prompts Ontology and ProtoScript Providers and authentication Sessions and long-running work