phenobarbital/ai-parrot/agent-builder

Agent Builder

Two paths to a new agent — pick the simpler one whenever it satisfies the request.

Path A — Simple agent (no custom code)

Use list_agent_base_classes to see the available base classes (BasicBot, Chatbot, Agent, WebAgent, WebSearchAgent, ...) and their configurable constructor parameters. Then call create_yaml_agent with:

• name — a slug (^[a-z0-9_-]+$).
• bot_class — the base class name.
• llm — optional "provider:model" override.
• description — what the agent does.
• category — a grouping folder under AGENTS_DIR/agents/ (default

"general").

This writes a lossless YAML definition and registers the agent immediately — no draft/activate step needed.

Path B — Code-generated agent (custom tools/behavior)

When the user needs custom Python logic (a bespoke tool, custom prompt building, non-trivial control flow), write a full agent module and call save_agent_draft(name, source). Rules for the generated source:

1. Subclass one of the catalog base classes (`from parrot.bots.agent

import Agent, etc.) — check list_agent_base_classes` for the exact import path.

1. Decorate the class with @register_agent("<name>") (`from

parrot.registry import register_agent`) so activation actually registers it.

1. Keep imports to the standard library, parrot.*, and already-listed

tools (list_available_tools) — the draft validator statically rejects unknown/unsafe imports (AST allowlist) before it is ever imported.

1. A draft is NEVER live code. Explain to the user that they (or an

admin) must call POST /astudio/drafts/{name}/activate — you cannot activate a draft yourself.

Always show the user the full generated source and the validation report returned by save_agent_draft before suggesting they activate it.