Problem: With the aidp CLI (v5.1.1), you can script the data side of an agent use case: catalog, schema, tables, volume and notebook. The agent side can only be built by clicking in the Workbench UI. That covers knowledge bases and ingestion, the agent flow (guardrails, model, SQL and RAG tools), tool tests and AI Registry. So agents can't be version-controlled, code-reviewed, promoted from dev to prod, or rebuilt the same way twice. The API support is already partly there. The canvas saves through an agentFlows endpoint and tool tests run through tools/actions/test, but neither is in the CLI, and agent create takes an undocumented diagram body.
Proposal: Add a declarative aidp apply -f agent.yaml (plus aidp export agent <name>) that describes the whole use case in one file:
knowledgeBase:
name: supply_chain_knowledge_base
sources: [supply_chain_catalog.gold_schema.supply_chain_volume]
agent:
name: Shipment_Routing_Agent
compute: workshop_ai_compute
guardrails: { pii: mask, contentModeration: block, promptInjection: block }
model: { region: us-chicago-1, name: google.gemini-2.5-flash }
instructions: ./instructions.md
tools:
- sql: { cluster: workshop_compute, query: ./query.sql, params: { shipment_id: ALL } }
- rag: { knowledgeBase: supply_chain_knowledge_base, topK: 3 }
deploy: { register: true }
Why it matters: One command turns the 8-step, roughly 45-minute guided build into a repeatable, reviewable deployment. It enables Git and CI/CD workflows, and it lets AI coding assistants build and fix agents end to end. Export also gives teams a way to back up and share agents built in the UI.
