AI Agents Plugin

The AI Agents plugin provides autonomous agents that can interact with your FastCMS data. Agents use the LLM's tool-calling capability to list collections, query records, create data, and search — all driven by natural language instructions.

Requires: AI Core plugin

Installation

cp -r ai_agents/ plugins/ai_agents/
cp -r ai_core/ plugins/ai_core/

How It Works

You send a task description to the /run endpoint
The agent sends the task to the LLM along with available tools
The LLM decides which tool to call (e.g., list_collections, query_records)
The agent executes the tool and sends the result back to the LLM
The LLM either calls another tool or returns a final answer
This loop continues until the task is complete (max 10 iterations)

API Endpoints

All endpoints are mounted at /api/v1/plugins/ai/agents/.

POST /ai/agents/run

Run an agent to complete a task.

curl -X POST http://localhost:8000/api/v1/plugins/ai/agents/run \
  -H "Content-Type: application/json" \
  -d '{
    "task": "List all collections and tell me how many records each one has",
    "allow_writes": false
  }'

Response:

{
  "answer": "There are 3 collections:\n- articles: 42 records\n- users: 15 records\n- comments: 128 records",
  "steps": [
    {
      "type": "tool_call",
      "content": "Calling list_collections",
      "tool_name": "list_collections",
      "tool_args": {}
    },
    {
      "type": "tool_result",
      "content": "{\"collections\": [...]}",
      "tool_name": "list_collections",
      "tool_args": {}
    },
    {
      "type": "tool_call",
      "content": "Calling query_records",
      "tool_name": "query_records",
      "tool_args": {"collection": "articles", "limit": 1}
    },
    {
      "type": "answer",
      "content": "There are 3 collections...",
      "tool_name": "",
      "tool_args": {}
    }
  ],
  "model": "gpt-4o-mini"
}

POST /ai/agents/run/stream

Stream agent execution as Server-Sent Events. Each step is emitted as it happens:

curl -N http://localhost:8000/api/v1/plugins/ai/agents/run/stream \
  -H "Content-Type: application/json" \
  -d '{"task": "Find the latest 5 articles"}'

GET /ai/agents/tools

List all available tools.

{
  "tools": [
    {"name": "list_collections", "description": "List all available collections...", "write": false},
    {"name": "query_records", "description": "Query records from a collection...", "write": false},
    {"name": "get_record", "description": "Get a single record by ID...", "write": false},
    {"name": "create_record", "description": "Create a new record...", "write": true},
    {"name": "update_record", "description": "Update an existing record...", "write": true},
    {"name": "search_records", "description": "Full-text search...", "write": false},
    {"name": "semantic_search", "description": "AI-powered semantic search...", "write": false}
  ]
}

Available Tools

Tool	Description	Write?
`list_collections`	List all collections with their schemas	No
`query_records`	Query records with filtering and pagination	No
`get_record`	Get a single record by ID	No
`create_record`	Create a new record	Yes
`update_record`	Update an existing record	Yes
`search_records`	Full-text search (FTS5)	No
`semantic_search`	Semantic search via AI Vectors plugin	No

Safety

By default, write tools (create_record, update_record) are disabled. To enable them:

{
  "task": "Create an article titled 'Hello World'",
  "allow_writes": true
}

You can also restrict which tools are available:

{
  "task": "Search for articles about AI",
  "tools": ["list_collections", "query_records", "search_records"]
}

Example: Data Analysis Agent

import httpx

response = httpx.post(
    "http://localhost:8000/api/v1/plugins/ai/agents/run",
    json={
        "task": "Analyze the articles collection. What topics are most common? Show the top 5 most recent articles.",
        "model": "gpt-4o"
    }
)
result = response.json()
print(result["answer"])

# See the agent's reasoning
for step in result["steps"]:
    print(f"[{step['type']}] {step['content'][:100]}")

Example: Content Creation Agent

response = httpx.post(
    "http://localhost:8000/api/v1/plugins/ai/agents/run",
    json={
        "task": "Look at existing articles and create a new one about Python best practices in a similar style.",
        "allow_writes": true
    }
)

Iteration Limit

Agents stop after 10 tool-calling iterations to prevent infinite loops. If the task requires more steps, break it into smaller sub-tasks.

Dependencies

Required: AI Core plugin
Optional: AI Vectors plugin (for semantic_search tool)

AI Agents Plugin

On this page