FastApp Agent Project Bootstrap

This document defines the first structured LLM/MCP-ready agent surface for FastApp.

Goal

Expose one agent that can:

• Read public FastApp documentation.
• Inspect existing apps.
• Create or update a generic app through Nuxt APIs.
• Operate records inside a generic app through /api/v1/data/:app/:object.

Why This Layer Exists

The existing fastapp-agent route is useful as a prompt-driven playground, but it is not a stable integration contract for external orchestration. A project-level agent surface needs:

• A fixed agent identity.
• A typed tool catalog.
• Machine-readable input schemas.
• A deterministic execution endpoint.
• Public discovery routes that LLM and MCP wrappers can consume.

First Agent

Agent id: fastapp-generic-app-operator

Responsibilities:

• Retrieve public docs before acting.
• Inspect apps before mutating them.
• Create or patch apps through /api/app.
• List, create, patch, and delete records through /api/v1/data.
• Apply granular schema mutations for modules, objects, properties, relations, actions, and pages.
• Manage permissions and memberships through structured RBAC tools.

Routes

Public discovery:

• /fastapp/public-docs/llms.txt
• /fastapp/public-docs/manifest.json
• /fastapp/public-docs/agents.json

Execution:

• GET /api/agent/catalog
• POST /api/agent/execute
• GET /api/mcp
• POST /api/mcp

MCP Transport

POST /api/mcp exposes a JSON-RPC transport over the same agent registry and executor.
It does not define a second tool contract; tools/list reads server/utils/agents/registry.ts
and tools/call forwards execution to /api/agent/execute.

Supported methods:

• initialize
• tools/list (listTools alias)
• tools/call (callTool alias)

Example tools/call payload:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "agentId": "fastapp-generic-app-operator",
    "name": "create_record",
    "arguments": {
      "app": "crm",
      "object": "lead",
      "data": { "name": "Ada" }
    },
    "dryRun": true
  }
}

Write behavior is inherited from /api/agent/execute: writes default to dry-run previews,
RBAC is enforced by the underlying Nuxt routes, and execution/audit logs are emitted by the
agent executor plus the MCP adapter.

Tool Model

Each tool definition contains:

• name
• title
• description
• readOnly
• api binding to an existing Nuxt route
• inputSchema
• optional examples

The executor validates input against the declared schema before forwarding the call to the underlying Nuxt API.

Tool Families

• Discovery: public docs and app catalog lookup.
• App lifecycle: create, patch, delete full apps.
• App schema: upsert and delete modules, objects, properties, relations, actions, and pages.
• Data: list, create, patch, and delete generic object records.
• Data intelligence: aggregate, profile, and suggest filters for any object using the same generic data route and RBAC constraints.
• RBAC: list roles, permissions, and memberships; create/update/delete permissions; assign/update/remove memberships.

Current limitation:

• Role creation is still blocked by the existing backend policy in /api/v1/data/:app/role.

Dry Run Support

POST /api/agent/execute accepts dryRun: true.

In dry-run mode the executor does not mutate state. It returns the exact internal request shape that would be sent to the Nuxt API. This is useful for:

• tool debugging
• MCP wrappers
• approval workflows
• prompt iteration

Current Orchestration Status

Implemented in the unified /api/fastapp-agent route:

• Server-side multi-step tool loop over the shared agent catalog.
• Server-managed prompt assembly with a small frontend instruction hint.
• Compiled generic app context for object/property/relation/action ranking.
• Conditional planner and verifier calls to reduce token usage on simple requests.
• Write-policy handling that converts backend mutations to dry-run previews unless explicit confirmation is present.
• Generic record field matching through aliases, normalized names, property metadata, and semantic schema scoring.
• Frontend ui_apply_filters action that syncs tool queries to generic table/list filters and sort.
• Generic data intelligence tools: aggregate_records, profile_object_data, and suggest_filters.
• Dynamic CRUD view capability context so the agent can see generic filter/sort/search/write support, active fields, metric fields, date fields, relation fields, and current query state.
• Resilient agent routing: stale browser agent_id values fall back to fastapp-generic-app-operator, and the frontend Copilot scopes saved execution agents to the app that produced them.
• App-scoped data routes in the playground legacy path instead of hardcoded object-only endpoints.

Suggested Next Steps

1. Add persistent per-user/per-app agent memory for compressed summaries, preferences, and previous decisions.
2. Add structured frontend result cards for aggregate/profile/list tool outputs instead of relying on assistant prose parsing.
3. Add a dedicated frontend approval UI for dry-run write previews.
4. Keep MCP clients aligned with /api/agent/catalog and /api/agent/execute as tools evolve.
5. Continue migrating remaining legacy playground delta/data action flows to structured tool previews.
6. Add pgvector-backed schema/document retrieval when compiled context ranking is not enough.