Bot/Agent Integration Design (Claw)

This skill provides guidelines and patterns for integrating web applications (SaaS/internal tools/products) with external bots and agent systems (e.g., OpenAI tool-calling, LangChain, OpenClaw). The goal is to allow agents to securely connect, read, and write data without turning the application itself into a bot.

Phase 1: Host Application Analysis

Adapt the integration to the project's existing domain model.

Analyze the Application: Review schema.prisma, models/, OpenAPI specs, or route definitions to understand the core resources (e.g., orders, products, leads).
Select Exposure Targets: Decide which specific entities the agent actually needs access to for the task at hand.

Core Architectural Concepts

When building agent integrations based on your discovery, implement these foundational concepts:

1. Multi-Tenant Context

All read/write operations MUST be scoped to a specific tenant/workspace:

Rule: Always require tenant_id, org_id, or workspace_id in requests (via header, path, or body).

2. Domain-Specific Resource Model

Design endpoints that match the discovered entities exactly. Agents should write data directly to where it belongs:

Do NOT use a generic /items endpoint unless the application itself is a generic CMS.
Do: Use specific, pluralized endpoints based on the domain (e.g., /v1/invoices, /v1/leads, /v1/candidates).

Authentication and Authorization

Authentication Methods

MVP Validation: Use API Keys passed via the Authorization: Bearer <API_KEY> header.
Production Standard: Use OAuth2 (Authorization Code + PKCE) for integrations with third-party agent providers.

Scope / Permission Model (CRITICAL)

You MUST enforce a granular scope model based on the discovered resources using the {action}:{resource} pattern. Do not give agents root access.

Standard Scopes (Generic Examples):

read:{resource}: Read access to a specific resource (e.g., read:invoices).
write:{resource}: Access to create/update resources (e.g., write:leads).
admin:audit: Access to read audit logs.

High-Risk Scopes:

Rule: Isolate riskier operations behind specific scopes, default off.
write:{resource}:delete: Permission to delete items (e.g., write:invoices:delete).
write:{resource}:bulk: Permission for bulk modifications.

Standard HTTP Guidelines

Enforce these standards on all agent-facing endpoints:

Base Path: /v1 (e.g., https://<domain>/v1)
Content-Type: application/json
Rate Limiting: Implement rate limits (e.g., 60 req/min per key/token).
Idempotency: Require an Idempotency-Key header (UUID) for all POST (create) endpoints.
Agent Traceability: Suggest headers like X-Agent-Name (e.g., openclaw, langchain) and X-Trace-Id for log correlation.

Standard API Endpoints

When setting up the API, implement these minimal required endpoints dynamically based on Phase 1 discovery.

1. Health and Meta

GET /v1/health: Returns { "status": "ok", "version": "0.1.0" }.
GET /v1/openapi.json: Serve the OpenAPI spec so agents can auto-generate tools.

2. Exposed Resources (CRUD)

For every entity you decided to expose in Phase 1 (e.g., invoices):

List: GET /v1/{resource}?tenant_id=...&status=open (Scope: read:{resource})
Read: GET /v1/{resource}/{id} (Scope: read:{resource})
Create: POST /v1/{resource} (Scope: write:{resource}, require Idempotency-Key)
Update: PATCH /v1/{resource}/{id} (Scope: write:{resource})
Delete: DELETE /v1/{resource}/{id} (Requires specialized scope write:{resource}:delete)

3. Search (Crucial for Agents)

Endpoint: GET /v1/search?tenant_id=...&q=...&types={resource1},{resource2}
MVP: SQL Full-Text Search (PostgreSQL tsvector, SQLite FTS5).
V2 — Semantic Search: Use embedding models (e.g., text-embedding-3-small from OpenAI, or nomic-embed-text locally) to generate vectors, stored in a vector DB:
- Managed: Pinecone, Weaviate, Qdrant Cloud
- Self-hosted / Postgres-native: pgvector extension (lowest ops overhead for most projects)
- Endpoint: POST /v1/semantic-search { text, types, limit, threshold }
- When to use V2: When keyword search fails for paraphrased queries or conceptually similar content.

See references/oauth2-flow.md for auth setup and assets/tools-manifest-template.json for a ready-to-use manifest.

4. Links (Relationships)

If the domain model is highly relational (e.g., an invoice belongs to a customer):

Endpoint: POST /v1/links
Scope: write:links
Payload: tenant_id, from_id, to_id, relation (e.g., belongs_to).

5. Audit Logging

Endpoint: GET /v1/audit
Scope: admin:audit
Keep a detailed log of actor (agent_name), action (e.g., create_invoice), target, and trace_id.

Standard Error Formatting

Always return errors in this consistent format for predictability:

{
  "error": {
    "code": "insufficient_scope",
    "message": "write:invoices scope required",
    "details": { "required": ["write:invoices"] }
  }
}

Common codes: unauthorized, insufficient_scope, not_found, validation_error, rate_limited, conflict, internal_error.

Agent Manifest (tools.json)

When requested to build a tool manifest for an agent framework, use the ready-to-use template at:

assets/tools-manifest-template.json

The template includes definitions for search_[RESOURCE_NAME]s, create_[RESOURCE_NAME], update_[RESOURCE_NAME], and create_link. Replace <your-domain> with the actual API base URL.

Key manifest conventions:

Use "type": "bearer" for auth
Always include tenant_id as a required field in every tool's input_schema
Keep description fields agent-friendly — they guide LLM tool selection

Internal Data Tracking

Every record/capture created by an agent MUST trace back to its origin. Add these fields to database schemas:

source: Should indicate agent (vs human).
agent_name: Identifying name of the bot.
trace_id: For request correlation.
metadata: Flexible JSON column for arbitrary agent state/data.

References

references/EXAMPLES.md — domain-specific resource and tool-manifest designs for agent integrations. Read it when the expected output format or level of detail is unclear.

🔗 Next Steps & Handoffs

Ecosystem: @ecosystem-orchestration — Agent Orchestration.

Workflows:

Agent Connectivity Flow (orch-agent-connectivity, step 1 of 3): next → @auth-flow-designer (optional).

Handoff contract: pass results to the next skill through an inline Handoff block in your reply with the fields skill, workflow, created_at, inputs, summary, and next (the handoff contract of @ecosystem-orchestration). If a next skill is not installed, continue with its step from the ecosystem map, or install it with npx skills add fatih-developer/fth-skills --skill <name> after the user agrees.