From acd34cd352ca092390fe6ef38b607c905e22d22f Mon Sep 17 00:00:00 2001 From: Nur Date: Tue, 7 Apr 2026 23:43:59 -0700 Subject: [PATCH 1/9] skills: add aiXplain Agent Builder skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a top-level skills/ folder modeled after anthropics/skills, containing the aiXplain Agent Builder skill — a portable skill for building, running, debugging, and deploying aiXplain agents from any skill-compatible AI coding agent (Claude Code, Cursor, etc.). - skills/README.md: overview of the skills collection - skills/aixplain-agent-builder/: SKILL.md, README, and reference playbooks Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 134 ++++++++ skills/aixplain-agent-builder/README.md | 41 +++ skills/aixplain-agent-builder/SKILL.md | 287 ++++++++++++++++++ .../references/asset-ids.md | 86 ++++++ .../references/inspector-analytics.md | 165 ++++++++++ .../references/integration-playbooks.md | 239 +++++++++++++++ 6 files changed, 952 insertions(+) create mode 100644 skills/README.md create mode 100644 skills/aixplain-agent-builder/README.md create mode 100644 skills/aixplain-agent-builder/SKILL.md create mode 100644 skills/aixplain-agent-builder/references/asset-ids.md create mode 100644 skills/aixplain-agent-builder/references/inspector-analytics.md create mode 100644 skills/aixplain-agent-builder/references/integration-playbooks.md diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 00000000..ceb5df9c --- /dev/null +++ b/skills/README.md @@ -0,0 +1,134 @@ +# aiXplain Skills + +A collection of portable skills you can drop into any skill-compatible AI coding agent (Claude Code, Cursor, etc.) to work with aiXplain. + +## Available skills + +| Skill | Description | +| --- | --- | +| [`aixplain-agent-builder/`](./aixplain-agent-builder) | Build, run, debug, and deploy aiXplain agents using plain English | + +--- + +## aiXplain Agent Builder Skill + +Build, run, debug, and deploy aiXplain agents using plain English — no IDE, no boilerplate, no guesswork. + +Drop this skill into any skill-compatible AI coding agent and start describing what you want. The agent handles the architecture, writes the code, deploys to aiXplain, runs a smoke test, and hands you a working agent ID. + +> **SDK version:** `aixplain==0.2.44` + +### Who it's for + +| Persona | What they get | +| --- | --- | +| **Non-technical builders** | Zero-code agent creation — just describe what you want | +| **Developers** | Production-ready Python, SDK patterns, OAuth wiring, error handling | +| **Power users** | Export any deployed agent back to Python, reverse-engineer team architectures, add inspectors and governance | +| **AI teams** | Safe API key handling, pre-build approval gates, no silent duplicates | + +### Zero-setup requirements + +1. Get an aiXplain API key. +2. Download or clone the [`aixplain-agent-builder/`](./aixplain-agent-builder) folder. +3. Drag it into your AI coding agent's chat window (Claude Code, Cursor, etc.) or point it to the folder path. +4. Say: **"Add this as a skill"** +5. Open the deployed agent in [aiXplain Studio](https://studio.aixplain.com) to inspect traces and runtime behavior. + +That's it. No pip installs, no config files, no environment setup — the skill auto-discovers your API key and walks you through anything it can't find. + +### What you can build + +**Build** + +Describe the agent in plain English. The skill drafts the plan, tools, output format, and guardrails before it builds. + +```text +"Build an agent that searches the web, finds competitor pricing, and emails me a summary" +"Create a support triage agent connected to our knowledge base and Jira" +"Make a real estate evaluator that looks up location data and computes cap rate" +``` + +**Run / Debug** + +Give it an agent ID or name. The skill runs it, inspects the steps, and diagnoses failures. + +```text +"Run agent 69ce064f44eef3c9e3850d95 with this query: Austin TX, 450k asking price" +"Debug why the agent isn't using the knowledge base" +"Inspect the execution steps from the last run" +``` + +**Deploy** + +Once approved, the skill creates or updates the agent, connects the right tools, runs a smoke test, and leaves you with a working asset. + +```text +"Deploy this customer support agent to aiXplain and test it with a ticket triage prompt" +"Build this real-estate evaluator and deploy it to my workspace" +"Create the team agent, connect the tools, and validate the first run" +``` + +### What the skill does for you + +- Shows a pre-build plan before creating anything +- Finds API keys from `~/.env`, repo `.env`, or environment variables +- Reuses existing agents instead of creating duplicates +- Surfaces OAuth connection links when integrations need them +- Runs a smoke test and checks for grounded output + +```text +~/.env → repo .env → environment variables → asks you +``` + +Keys are set as environment variables, never hardcoded into generated files. + +### Best practices baked in + +- Uses a strong instruction format: `ROLE`, `CONSTRAINTS`, and `OUTPUT RULES` +- Keeps tool descriptions short and action-oriented for better selection +- Picks practical iteration limits for lookup vs. deep research tasks +- Scopes tool actions to the minimum required set +- Chooses speed vs. quality settings based on the use case + +```text +runResponseGeneration=False + output_format="text" -> ~30-40% faster +runResponseGeneration=True + output_format="markdown" -> richest output +``` + +### Sample queries to try + +- **Web research agent** — *"Build an agent that searches the web and summarizes findings into a markdown report"* +- **Support triage** — *"Create a support agent that searches our KB, checks ticket history in Jira, and classifies by severity"* +- **Data analyst** — *"Build an agent that runs Python on uploaded CSVs and produces charts"* +- **Email assistant** — *"Make an agent that reads my Gmail, groups by topic, and drafts replies"* +- **Deploy** — *"Build this agent, deploy it to my workspace, and validate the first run"* +- **Debug** — *"Why did agent 69abc… return a hallucinated answer instead of using the KB?"* +- **Knowledge base** — *"Create an agent connected to our product docs KB that answers support questions"* + +### Integrations supported + +The skill has access to 600+ integrations including: + +- **Productivity:** Gmail, Google Drive, Google Sheets, Notion, Confluence +- **Dev & project:** GitHub, Jira, Linear +- **CRM & sales:** HubSpot, Salesforce +- **Communication:** Slack +- **Data:** PostgreSQL, SQLite, aiR Knowledge Base +- **Compute:** Python Sandbox, Code Execution +- **Web:** Tavily, Firecrawl, Google Search, Google Places +- **Universal:** MCP Server and similar extensible connectors + +### File structure + +```text +aixplain-agent-builder/ +├── SKILL.md # Core skill — loaded automatically +├── README.md # Quick overview of the skill +└── references/ + ├── asset-ids.md # Curated model, tool, and integration IDs + ├── integration-playbooks.md # Connection patterns per integration + └── inspector-analytics.md # Governance policies and inspector patterns +``` + +Reference files are loaded on demand — only when the task requires them. This keeps context lean and responses fast. diff --git a/skills/aixplain-agent-builder/README.md b/skills/aixplain-agent-builder/README.md new file mode 100644 index 00000000..1cecb1b9 --- /dev/null +++ b/skills/aixplain-agent-builder/README.md @@ -0,0 +1,41 @@ +# aiXplain Agent Builder Skill + +A Claude skill for building, deploying, running, debugging, and managing aiXplain v2 agents via the Python SDK and REST API. Verified against **aiXplain SDK v0.2.44**. + +## What it covers + +- Single and team agents with tools, integrations, and inspectors +- Sync and async agent runs (SDK + language-agnostic REST/cURL) +- In-place updates to deployed agents (instructions, tools, LLM, output format) +- Non-OAuth integrations: Knowledge Base, PostgreSQL, SQLite, Python Sandbox, MCP Server +- OAuth integrations: Gmail, Slack, Jira, Google Drive (REST-first workaround for broken SDK path) +- Inspector policies (ABORT / ADAPTIVE / RERUN) and analytics +- Exporting an existing agent to a reproducible Python script + +## Files + +| File | Purpose | +|---|---| +| `SKILL.md` | Main entry point — load this first | +| `references/integration-playbooks.md` | **Required read** before wiring any non-OAuth integration. Exact `config={...}` shapes, file uploads, authoring constraints | +| `references/asset-ids.md` | Full model / integration / tool ID tables | +| `references/inspector-analytics.md` | Inspector policy matrix and analytics schema | + +## Prerequisites + +- `pip install --upgrade aixplain` +- `AIXPLAIN_API_KEY` (or `TEAM_API_KEY`) set in env + +## Core principles + +1. **Search before creating.** `Agent`, `Tool`, `Model`, and `Integration` all share `.search(query=...).results`. Run it before falling back to hardcoded IDs or declaring an asset missing. +2. **Mutate, don't recreate.** Deployed agents are mutable — load, edit, `save()`. Never recreate to change behavior. +3. **Ask for missing inputs.** For non-OAuth integrations (KB, DB, Python, MCP), always create fresh connected tools and ask the user for missing files / credentials rather than inventing placeholders. +4. **Consult the playbook.** `references/integration-playbooks.md` is the source of truth for `config` payloads and per-integration gotchas. `SKILL.md` only shows the KB shape. + +## Known gotchas + +- `Agent.search()` is eventually-consistent — fall back to `GET /sdk/agents` on `name_already_exists`. +- MCP Server and SQLite validate at **save-time**, not run-time. +- OAuth tools are at `/sdk/models/`, not `/sdk/tools/`, and the SDK Tool pipeline is broken for them — use REST. +- Python Sandbox: `bool` params are broken (JSON lowercase `true` → `NameError`); tuple returns round-trip as string reprs. Use `int` (0/1) and `dict`/`list` respectively. diff --git a/skills/aixplain-agent-builder/SKILL.md b/skills/aixplain-agent-builder/SKILL.md new file mode 100644 index 00000000..90b0d22d --- /dev/null +++ b/skills/aixplain-agent-builder/SKILL.md @@ -0,0 +1,287 @@ +--- +name: aixplain-agent-builder +description: Build, deploy, run, debug, export, and manage aiXplain v2 agents via the Python SDK and REST API. +metadata: {"requires": {"env": ["AIXPLAIN_API_KEY"], "bins": ["python3", "pip"]}} +--- + +# aiXplain Agent Builder + +Build, deploy, run, debug, export, and manage aiXplain v2 agents. Handles single agents, team agents, inspectors, tools, and OAuth integrations. + +## Capabilities + +- Create and update single and team agents with tools, integrations, and inspectors +- Run agents synchronously or with async polling +- Export existing agents to reproducible Python scripts +- Wire OAuth integrations (Gmail, Slack, Jira, Google Drive) via REST +- Connect non-OAuth integrations (Knowledge Base, PostgreSQL, SQLite, Python Sandbox, MCP) +- Add inspector policies (ABORT, ADAPTIVE, RERUN) with validation matrix + +## Setup + +**Always install/upgrade to the latest aiXplain SDK before doing anything**: `pip install --upgrade aixplain`. This skill is verified against **aiXplain SDK v0.2.44**. At the start of every session, check the installed version and: + +- If older than 0.2.44 → run `pip install --upgrade aixplain` and tell the user it has been upgraded. +- If newer than 0.2.44 → tell the user explicitly: *"This skill was authored against aiXplain v0.2.44 but you are running v. Some behaviors (especially OAuth tool action discovery and search indexing) may have changed."* Then proceed cautiously and verify each step. + +```python +import importlib.metadata +SKILL_VERIFIED_VERSION = "0.2.44" +installed = importlib.metadata.version("aixplain") +if installed != SKILL_VERIFIED_VERSION: + print(f"NOTE: aiXplain {installed} installed; this skill is verified against {SKILL_VERIFIED_VERSION}.") +``` + +Also requires an aiXplain API key set as `AIXPLAIN_API_KEY` (or `TEAM_API_KEY`). + +```python +import os +from pathlib import Path +from dotenv import load_dotenv +from aixplain import Aixplain + +for env_path in [Path.home() / ".env", Path(".env")]: + if env_path.exists(): + load_dotenv(env_path) + break + +api_key = os.getenv("TEAM_API_KEY") or os.getenv("AIXPLAIN_API_KEY") +os.environ["TEAM_API_KEY"] = api_key +os.environ["AIXPLAIN_API_KEY"] = api_key +aix = Aixplain(api_key=api_key) +``` + +## Search First (Core Principle) + +**Always search before you create, hardcode, or claim something is missing.** `Agent`, `Tool`, `Model`, and `Integration` all expose the same `.search()` syntax. Use it before falling back to the Quick Asset IDs table or announcing that an asset is unavailable. + +```python +# Unified syntax — works for Agent, Tool, Model, Integration +results = aix.Agent.search(query="My Agent").results +results = aix.Tool.search(query="web search").results +results = aix.Model.search(query="gpt-5").results +results = aix.Integration.search(query="google drive").results + +# Filter client-side. Names may be concatenated (e.g. "Googledrive", "Googlesheets"). +# Normalize whitespace before comparing. +def _norm(s): return "".join(s.lower().split()) +match = next((r for r in results if _norm(r.name) == "googledrive"), None) +print(match.id, match.name) +``` + +When the user asks for an integration/tool/model that isn't in the Quick Asset IDs table, **run the matching `.search()` first**. Only report "not found" after the search returns no match. + +## Build Agent + +Apply the search-first principle: + +```python +name = "My Agent" +match = next((r for r in aix.Agent.search(query=name).results if r.name == name), None) +if match: + agent = aix.Agent.get(match.id) + agent.instructions = "Updated instructions." + agent.save() +else: + agent = aix.Agent( + name=name, description="...", instructions="...", + tools=[tool], output_format="markdown", + ).save() +``` + +## Run Agent + +```python +# Sync +result = agent.run(query="...", executionParams={"maxTokens": 6000}, runResponseGeneration=True) +print(result.data.output) + +# Async polling +import requests, time +ar = agent.run_async(query="...") +for _ in range(30): + time.sleep(10) + raw = requests.get(ar.url, headers={"x-api-key": api_key}).json() + if raw.get("status", "").upper() in ("SUCCESS", "FAILED"): + print(raw["data"]["output"]); break +``` + +### REST / cURL (on-demand, language-agnostic) + +Once an agent is deployed it can be invoked over plain HTTP — no SDK required. `sessionId` is optional; pass the same value across calls to get multi-turn memory. + +```bash +curl -X POST 'https://platform-api.aixplain.com/sdk/agents//run' \ + -H 'x-api-key: ' \ + -H 'Content-Type: application/json' \ + -d '{ + "query": "", + "sessionId": "" + }' + +# Response: +# { "requestId": "...", "sessionId": "...", +# "data": "https://platform-api.aixplain.com/sdk/agents//result" } +# +# Then GET the `data` URL with the same x-api-key header to poll for the result. +``` + +## Update a Deployed Agent (in place) + +**Deployed agents are mutable.** Never recreate to change behavior — load the existing agent, mutate, and `save()`. The agent ID, history, and any external references stay intact. + +You can update on the live agent: + +- `agent.instructions` — system prompt +- `agent.description` — public-facing summary +- `agent.tools` — add, remove, or replace tools (the agent itself is not detached/recreated) +- `agent.output_format` — `"markdown"` / `"text"` / `"json"` +- `agent.llm_id` — swap the underlying LLM (see Quick Asset IDs for model IDs) + +You can also update **attached tools without detaching them** from the agent — e.g. change a tool's `description`, add a new file to a Knowledge Base tool, or change `allowed_actions`. Mutate the tool object and call `tool.save()`; the agent will pick up the change on its next run. + +```python +agent = aix.Agent.get("") +agent.instructions = "New system prompt..." +agent.output_format = "json" +agent.llm_id = "698c87701239a117fd66b468" # Claude Opus 4.6 +agent.save() + +# Update an attached tool in place (no detach/reattach): +kb_tool = next(t for t in agent.tools if t.name == "Product KB") +kb_tool.description = "Updated KB scope: includes 2026 docs." +kb_tool.save() +``` + +## After Deploy: Share Visual Links + +Whenever you deploy or update an agent, share these Studio links with the user so they can edit, trace, and monitor it visually: + +- **Visual builder / trace viewer:** `https://studio.aixplain.com/build//schema` +- **Analytics dashboard:** `https://studio.aixplain.com/dashboard/analytics/?agent=` + +## External References + +- **Docs:** https://docs.aixplain.com +- **Pricing:** https://aixplain.com/pricing +- **Studio (visual builder + analytics):** https://studio.aixplain.com + +## Create Tools + +```python +# Path A: Integration-backed (KB, SQLite, Python Sandbox, MCP) +# IMPORTANT: Only the Knowledge Base connects with just `integration` + `allowed_actions`. +# SQLite, Python Sandbox, and MCP each require a `config={...}` payload (uploaded +# .db URL, code+function_name, mcp URL, etc.). BEFORE building any non-OAuth tool, +# READ references/integration-playbooks.md — it documents the exact `config` shape, +# authoring constraints (Python Sandbox), and file-upload steps (SQLite) per +# integration. Do not guess the shape. If a required input is missing (KB source +# file, SQLite .db path, Python script body, MCP URL + API token), ASK THE USER — +# do not invent placeholders. Always create a fresh connected tool; do not reuse +# by name unless the user explicitly asks you to. +tool = aix.Tool(name="KB Search", description="Search product docs", + integration="6904bcf672a6e36b68bb72fb", allowed_actions=["search", "get"]).save() + +# Path B: Marketplace tool by ID +tool = aix.Tool.get("698cda188bbb345db14ac13b") + +# Path C: OAuth (Gmail, Slack, Jira, Google Drive) +# Step 1 — create the OAuth tool via the Models execute endpoint. +import requests +MODELS_RUN_URL = "https://models.aixplain.com/api/v2/execute" +H = {"x-api-key": api_key, "Content-Type": "application/json"} +resp = requests.post(f"{MODELS_RUN_URL}/{INTEGRATION_ID}", headers=H, + json={"name": "GDrive Writer", "description": "Write files to Drive."}).json() +tool_id = resp["data"]["id"] +redirect_url = resp["data"].get("redirectURL") # CRITICAL: user must visit this + +# Step 2 — STOP and have the user complete OAuth at redirect_url before continuing. +# Until OAuth is authorized, tool.actions will be empty and any agent run that +# touches the tool will hang/timeout. +print(f"Authorize: {redirect_url}") + +# Step 3 — after OAuth, load the tool via the SDK and set allowed_actions. +oauth_tool = aix.Tool.get(tool_id) # SDK handles OAuth tools fine +assert len(list(oauth_tool.actions)) > 0, "OAuth not yet completed" +oauth_tool.allowed_actions = ["GOOGLEDRIVE_CREATE_FILE"] # pick from .actions + +# Step 4 — pass the SDK Tool object directly to the agent's tools=[]. +# No manual dict shaping needed; the SDK serializes via tool.as_tool(). +``` + +## Team Agent + +```python +sub1 = aix.Agent(name="Researcher", instructions="Search and summarize.", tools=[search_tool]).save() +sub2 = aix.Agent(name="Writer", instructions="Write the final report.").save() +team = aix.Agent(name="Team Lead", instructions="Route to specialists.", subagents=[sub1, sub2]).save() +``` + +## Add Inspector + +```python +from aixplain.modules.team_agent import InspectorTarget +from aixplain.modules.team_agent.inspector import Inspector, InspectorPolicy, InspectorAuto + +inspector = Inspector( + name="Content Gate", + auto=InspectorAuto.ALIGNMENT, + model_params={"prompt": "Validate output meets policy. Fail if non-compliant."}, + policy=InspectorPolicy.ABORT, +) +team.inspectors = [inspector] +team.inspector_targets = [InspectorTarget.OUTPUT] +team.save() +``` + +## Export Agent to Python + +1. `GET https://platform-api.aixplain.com/sdk/agents/{ID}` with `x-api-key` +2. Recurse `agents[].assetId` for subagents +3. Map API fields to SDK constructor args +4. Generate standalone `.py` with env-based key loading + +## Constraints + +- Always search before creating, hardcoding, or declaring an asset missing — `Agent`, `Tool`, `Model`, and `Integration` all support `.search(query=...).results`. Never silently duplicate, and never announce "not in skill" without running the relevant search first +- When an agent already exists and the user asks for changes, **mutate the existing instance and call `agent.save()`** — never recreate. Recreating loses the ID, breaks any references, and risks `err.name_already_exists` +- `Agent.search()` is eventually-consistent and can miss recently-created agents. If lookup-by-name fails but `save()` later raises `name_already_exists`, fall back to `GET /sdk/agents` and match by exact name +- Set both `TEAM_API_KEY` and `AIXPLAIN_API_KEY` env vars +- OAuth tool **creation** requires REST (POST to `/api/v2/execute/{integration_id}`); the create response includes a `redirectURL` the user MUST visit to authorize before the tool has any actions +- OAuth tools can be **loaded** via `aix.Tool.get(tool_id)` and passed directly into `agent.tools=[...]` — the SDK serializes them via `as_tool()`. No manual dict/REST payload shaping is required +- An OAuth tool with empty `.actions` means OAuth is not yet completed; agent runs touching the tool will hang and time out. Always assert `len(list(tool.actions)) > 0` after fetch +- **Save vs Run validation asymmetry**: agents can be **saved/deployed** with unconnected integrations or with tools/integrations that have no `allowed_actions` selected — but they **cannot be run** unless every attached integration/tool has at least one action selected. Always set `allowed_actions` before invoking `agent.run()`. **Exception**: some integrations validate at save-time, not run-time — notably **MCP Server** (calls the remote server to verify the URL/token) and **SQLite** (rejects non-`.db` file types). A bad MCP URL or wrong file extension will fail `tool.save()` immediately, not defer to runtime +- The SDK's `tool.list_actions()` can return `[]` even when actions exist (stale `actions_available` flag). To verify auth + discover actions reliably, POST `{"action": "LIST_ACTIONS", "data": {}}` to `/api/v2/execute/{tool_id}` +- OAuth tools live at `/sdk/models/` not `/sdk/tools/` (relevant only if hitting the REST API directly) +- `runResponseGeneration=False` requires `output_format="text"` +- Tool descriptions < 200 chars, instructions < 1000 chars +- `.search()` returns `.results` not `.items` — filter client-side for exact match +- Prefer single agents over team agents (orchestrator dispatch has known failures) +- After adding inspectors, validate with 3 prompts: allowed, denied, ambiguous + +## Quick Asset IDs + +| Asset | Name | ID | +|---|---|---| +| Model | GPT-5.4 | `69b7e5f1b2fe44704ab0e7d0` | +| Model | GPT-4.1 Nano | `67fd9e2bef0365783d06e2f0` | +| Model | Claude Opus 4.6 | `698c87701239a117fd66b468` | +| Tool | Tavily Web Search | `6931bdf462eb386b7158def3` | +| Tool | Code Execution | `698cda188bbb345db14ac13b` | +| Integration | aiR Knowledge Base | `6904bcf672a6e36b68bb72fb` | +| Integration | PostgreSQL | `693ac6e8217c7b13b480970f` | +| Integration | SQLite | `689e06ed3ce71f58d73cc999` | +| Integration | Python Sandbox | `688779d8bfb8e46c273982ca` | +| Integration | MCP Server | `686eb9cd26480723d0634d3e` | +| Integration | Gmail | `6864328d1223092cb4294d30` | +| Integration | Slack | `686432941223092cb4294d3f` | +| Integration | Google Drive | `6864329b1223092cb4294d4e` | +| Integration | Google Sheets | `686432931223092cb4294d3c` | +| Integration | Google Docs | `6864329c1223092cb4294d51` | +| Integration | Google Calendar | `686432901223092cb4294d36` | + +## Reference Files + +- `references/asset-ids.md` — full model/integration/tool ID tables +- `references/integration-playbooks.md` — **REQUIRED READ** before wiring any non-OAuth integration (KB / SQLite / Python Sandbox / MCP). Contains the exact `config={...}` payloads, file-upload helpers, authoring constraints, and per-integration allowed_actions defaults. SKILL.md's "Create Tools" example only covers the KB shape — everything else needs this file +- `references/inspector-analytics.md` — inspector policies and analytics schema diff --git a/skills/aixplain-agent-builder/references/asset-ids.md b/skills/aixplain-agent-builder/references/asset-ids.md new file mode 100644 index 00000000..60c21ba2 --- /dev/null +++ b/skills/aixplain-agent-builder/references/asset-ids.md @@ -0,0 +1,86 @@ +# Curated IDs + +Model, tool, and integration ID lookup tables for fast deployment. +Linked from the main skill — use for asset discovery. + +--- + +## Top 10 Models (updated 2026-04-01) + +| Rank | Model | ID | Context | +|------|-------|----|---------| +| 1 | GPT-5.4 | `69b7e5f1b2fe44704ab0e7d0` | 1M | +| 2 | GPT-4.1 Nano | `67fd9e2bef0365783d06e2f0` | 1M | +| 3 | Claude Opus 4.6 | `698c87701239a117fd66b468` | 200K | +| 4 | Gemini 3.1 Pro | `6999aedf6103733bc067e0b2` | 1M | +| 5 | GPT-5 Nano | `6895d70ed50c89537c1cf238` | 1M | +| 6 | Qwen3 32B | `6810d0f4a289e15e3e5dd143` | 128K | +| 7 | GPT-4o | `6646261c6eb563165658bbb1` | 128K | +| 8 | Claude 3.5 Sonnet v2 | `671be4c46eb563a2736ded61` | 200K | +| 9 | Gemini 2.0 Flash | `6759db476eb56303857a07c1` | 1M | +| 10 | Llama 3.1 70B | `671932146eb5638ce20300a1` | 128K | + +--- + +## Top 10 Connectors (Integrations) + +| Rank | Integration | ID | +|------|-------------|----| +| 1 | Slack | `686432941223092cb4294d3f` | +| 2 | Gmail | `6864328d1223092cb4294d30` | +| 3 | GitHub | `6864328f1223092cb4294d33` | +| 4 | Notion | `686432921223092cb4294d39` | +| 5 | Google Sheets | `686432931223092cb4294d3c` | +| 6 | Google Drive | `6864329b1223092cb4294d4e` | +| 7 | Jira | `686432a31223092cb4294d60` | +| 8 | HubSpot | `6864329e1223092cb4294d54` | +| 9 | Confluence | `686432cf1223092cb4294ddb` | +| 10 | Salesforce | `686432bb1223092cb4294da2` | + +--- + +## Core Integrations (Pinned) + +| Integration | ID | +|-------------|----| +| PostgreSQL | `693ac6e8217c7b13b480970f` | +| aiR Knowledge Base | `6904bcf672a6e36b68bb72fb` | +| SQLite Database | `689e06ed3ce71f58d73cc999` | +| Python Sandbox | `688779d8bfb8e46c273982ca` | +| MCP Server | `686eb9cd26480723d0634d3e` | + +--- + +## Core Tools (Pinned) + +| Tool | ID | +|------|----| +| Google Search API | `692f18557b2cc45d29150cb0` | +| Firecrawl API | `69442021f2e6cb73e286ff0f` | +| Tavily Web Search | `6931bdf462eb386b7158def3` | +| Docling Document Parser | `6944350ff2e6cb73e286ff20` | + +--- + +## Utilities + +| Utility | ID / Instance | +|---------|--------------| +| Code Execution | `698cda188bbb345db14ac13b` | +| Scrape Website Tool | `crew-ai/scrape-website-tool/crew-ai` | +| Text File Reader | `aixplain/text-file-reader/aixplain` | +| Places API | `google/places-api/google` | +| Current Weather Data | `openweathermap/current-weather-data/openweathermap` | +| YouTube Data API v3 | `google/youtube-data-api-v3/google` | +| Wikimedia API | `wikimedia/wikimedia-api/wikimedia` | + +--- + +## SQLite Integration Notes + +- Integration ID: `689e06ed3ce71f58d73cc999` +- Valid actions: `query`, `commit`, `schema` +- Action input shape: each action expects a required `query` text input +- Connection: pass a `.db` file URL as `{"url": ""}` +- File requirement: SQLite connect rejects non-`.db` file types +- Read-only scope: `allowed_actions=["query", "schema"]` (omit `commit`) diff --git a/skills/aixplain-agent-builder/references/inspector-analytics.md b/skills/aixplain-agent-builder/references/inspector-analytics.md new file mode 100644 index 00000000..16d94dfa --- /dev/null +++ b/skills/aixplain-agent-builder/references/inspector-analytics.md @@ -0,0 +1,165 @@ +# Inspector Analytics Contract + +Inspector policy patterns, analytics schema, and validation requirements. +Linked from the main skill — consult when adding inspectors. + +--- + +## Inspector Policy Pattern (v2-compatible) + +```python +from aixplain import Aixplain +from aixplain.modules.team_agent import InspectorTarget +from aixplain.modules.team_agent.inspector import Inspector, InspectorPolicy, InspectorAuto + +aix = Aixplain(api_key="YOUR_TEAM_API_KEY") +team = aix.TeamAgent.get("TEAM_AGENT_ID") + +input_rbac_inspector = Inspector( + name="RBAC Input Gate", + auto=InspectorAuto.ALIGNMENT, + model_params={ + "prompt": ( + "Validate input has requester role and allowed scope. " + "If missing role/scope or requesting restricted PII, fail the check." + ) + }, + policy=InspectorPolicy.ABORT, +) + +team.inspectors = [input_rbac_inspector] +team.inspector_targets = [InspectorTarget.INPUT] +team.save() +``` + +### Canonical Imports + +- `from aixplain import Aixplain` +- `from aixplain.modules.team_agent.inspector import Inspector, InspectorPolicy, InspectorAuto` +- `from aixplain.modules.team_agent import InspectorTarget` + +### Policy Guidelines + +- Prefer `InspectorPolicy.ABORT` for hard policy violations. +- Prefer `InspectorPolicy.ADAPTIVE` for recoverable quality issues. +- Configure `RERUN` inspectors with explicit `max_retries` and `on_exhaust` behavior. +- For existing deployments: fetch `TeamAgent`, modify `inspectors`/`inspector_targets`, call `.save()`. + +--- + +## Status Semantics + +Keep aiXplain run status as-is: `IN_PROGRESS | SUCCESS | FAILED`. +Do not overload `FAILED` for policy blocks. + +### Governance Status Enum (App-Level) + +| Status | Meaning | +|--------|---------| +| `ALLOWED` | Inspector passed, normal execution | +| `BLOCKED_BY_INSPECTOR` | Inspector aborted the run | +| `REQUIRES_HUMAN_REVIEW` | Inspector flagged for manual review | +| `INSUFFICIENT_AUTH_CONTEXT` | Missing role/scope context | +| `RESTRICTED_SCOPE` | Request exceeds allowed scope | + +### Inspector Action Values + +SDK values: `continue | rerun | abort`. + +If product UI uses `CONT|RERUN|ABORT|EDIT`, map explicitly: +- `CONT` -> `continue` +- `RERUN` -> `rerun` +- `ABORT` -> `abort` +- `EDIT` -> app-derived extension (not native inspector action) + +--- + +## Per-Run Inspector Event Fields + +Minimum fields to capture per inspector evaluation: + +| Field | Description | +|-------|-------------| +| `run_id` | Parent run identifier | +| `inspector_event_id` | Unique event ID | +| `inspector_name` | Inspector name | +| `target` | `INPUT | STEPS | OUTPUT` | +| `decision` | `continue | rerun | abort` | +| `reason_code` | Machine-readable reason | +| `severity` | `LOW | MEDIUM | HIGH | CRITICAL` | +| `final_effect` | `none | rerouted | blocked` | +| `timestamp_start_utc` | Evaluation start | +| `timestamp_end_utc` | Evaluation end | +| `latency_ms` | Evaluation duration | +| `retries_used` | Number of retries consumed | +| `governance_status` | App-level governance status | +| `access_policy` | Nullable policy object | +| `approval_status` | `DRAFT | PENDING_REVIEW | APPROVED | REJECTED` (nullable) | +| `run_total_latency_ms` | Total run duration | +| `token_or_credit_usage` | Nullable; fallback to run-level | + +--- + +## Required Mapping Rules + +| Decision | Governance Status | Final Effect | +|----------|-------------------|--------------| +| `abort` | `BLOCKED_BY_INSPECTOR` | `blocked` | +| `rerun` (successful retry) | — | `rerouted` | +| `continue` (no intervention) | — | `none` | + +Policy block can still return run `SUCCESS` with safe refusal output — treat as governance block, not runtime failure. + +--- + +## Post-Change Validation Matrix (Mandatory) + +After adding/updating inspectors, run exactly 3 prompts: + +| Test | Expected Behavior | +|------|-------------------| +| **Allowed prompt** | Continue path, compliant normal answer | +| **Denied prompt** | Blocked/denial, no restricted data/action | +| **Ambiguous prompt** | Conservative handling (deny or ask clarification) | + +For each case capture: +- `prompt` +- `expected_action` +- `observed_run_status` +- `observed_governance_status` +- `observed_output_summary` +- `pass_fail` + +--- + +## Per-Inspector KPI Cards + +When an agent is selected, show these metrics per inspector: + +| Metric | Description | +|--------|-------------| +| `inspector_id` | Unique ID | +| `inspector_name` | Display name | +| `inspector_desc` | Description | +| `target` | Input/Steps/Output | +| `policy/action_mode` | Policy type | +| `severity_model` | Severity classification | +| `evaluation_count` | Inspector evaluations (not agent runs) | +| `pass_rate_pct` | Pass rate (explicit formula required) | +| `block_rate_pct` | Abort outcomes rate | +| `rerun_rate_pct` | Rerun rate | +| `edit_rate_pct` | Edit rate (if applicable) | +| `avg_reruns_per_evaluation` | Average retries | +| `retry_exhausted_count` | Exhausted retry count | +| `avg_latency_ms` | Average evaluation latency | +| `p95_latency_ms` | 95th percentile latency | +| `avg_credits_per_evaluation` | Credit cost per evaluation | +| `last_config_change_at` | Last modification timestamp | +| `last_config_change_by` | Last modifier | +| `config_version` | Configuration version | +| `drift_7d_vs_30d_pass_delta` | 7-day vs 30-day pass rate drift | +| `drift_7d_vs_30d_block_delta` | 7-day vs 30-day block rate drift | + +### Trend Chart (Daily) + +Track per inspector: `pass_count`, `block_count`, `rerun_count`, `override_count`. diff --git a/skills/aixplain-agent-builder/references/integration-playbooks.md b/skills/aixplain-agent-builder/references/integration-playbooks.md new file mode 100644 index 00000000..effecf5b --- /dev/null +++ b/skills/aixplain-agent-builder/references/integration-playbooks.md @@ -0,0 +1,239 @@ +# Integration Playbooks + +Connection patterns per integration type. +Linked from the main skill — consult when wiring tools. + +Canonical v2 entry point: +- Use `from aixplain import Aixplain`. +- Use `aix.Tool`, `aix.Integration` directly from the v2 client surface. + +Use `integration.list_actions()` and `integration.list_inputs(action_name)` before connecting in SDK flows. Always scope actions to a non-empty least-privilege set. + +--- + +## 1. aiR Knowledge Base (`6904bcf672a6e36b68bb72fb`) + +Connect with uploaded files (`.pdf`, `.docx`, `.txt`, `.md`, `.html`, `.csv`) or start empty and write with `upsert`. + +**Typical actions:** `search`, `get`, `count`, `metadata`, optional `upsert`. +**Best practice:** Keep retrieval-first scope (`search`, `get`, `metadata`) unless runtime writing is explicitly required. + +```python +index_tool = aix.Tool( + name="My Knowledge Base", + description="Semantic search over uploaded documents", + integration="6904bcf672a6e36b68bb72fb", +).save() + +# Populate +records = [ + {"id": "doc1", "text": "Python is a programming language", "metadata": {"category": "tech"}}, + {"id": "doc2", "text": "Machine learning uses algorithms", "metadata": {"category": "ai"}}, +] +index_tool.run(action="upsert", data={"records": records}) + +# Query +index_tool.run(action="search", data={"query": "programming", "filters": []}) +index_tool.run(action="count", data={}) +``` + +Semantic search works immediately after `upsert`; `count` returns indexed document total. + +--- + +## 2. PostgreSQL (`693ac6e8217c7b13b480970f`) + +Connect with database URL: `postgresql://username:password@host:port/database`. + +- Prefer read-only DB users for analysis assistants. +- Scope query actions first; enable write actions only when explicitly required. + +--- + +## 3. SQLite Database (`689e06ed3ce71f58d73cc999`) + +Connect using `.db` file URL via `config={"url": ""}`. + +- Valid actions: `query`, `schema`, `commit`. +- Default safe scope: `["query", "schema"]`. +- SQLite connect rejects non-`.db` file types. + +```python +from aixplain.v2.upload_utils import FileUploader + +integration = aix.Integration.get("689e06ed3ce71f58d73cc999") +uploader = FileUploader(api_key=TEAM_API_KEY, backend_url=aix.backend_url) +db_url = uploader.upload("/absolute/path/to/data.db", is_temp=True, return_download_link=True) + +sqlite_tool = aix.Tool( + name="SQLite Reader", + description="Read-only DB access", + integration=integration, + config={"url": db_url}, + allowed_actions=["query", "schema"], +).save() +``` + +--- + +## 4. Python Sandbox (`688779d8bfb8e46c273982ca`) + +Connect with `.py` file or inline source code and set `function_name` for the exposed function. + +### Authoring Constraints + +Empirically verified against aiXplain SDK v0.2.44 on 2026-04-07. The previously documented 8-rule list has been largely relaxed server-side. Only the following constraints are still active: + +1. **`function_name` must match a function defined in `code`.** If you include multiple functions in one code block, only the one whose name equals `function_name` is registered as the tool. +2. **`bool` parameters are broken** — the runtime serializer emits JSON `true`/`false` (lowercase) which then fails inside Python with `NameError: name 'true' is not defined`. Use `int` (0/1) as a workaround until the serializer is fixed. +3. **Tuple / multi-value returns are lossy** — a `return a, b` will round-trip as the string `"(a, b)"`, not structured data. If you need structured output, return a `dict` or `list`. + +The following **old** rules are **no longer enforced** (verified by creating and running tools that violate each one): + +| Old rule | Status | +|---|---| +| Single-line `def` signature | ❌ No longer enforced — multi-line signatures work | +| Parameter names ≥ 3 characters | ❌ No longer enforced — `a`, `b` work | +| No default parameter values | ❌ No longer enforced — defaults work | +| Type hints required | ❌ No longer enforced — untyped params work | +| Inputs restricted to `str`/`int`/`list`/`dict` | ❌ Relaxed — `float` works (may be int-coerced in serializer). `bool` is the only exception, see rule 2 above | +| At least one input parameter | ❌ No longer enforced — zero-arg functions work | +| All imports inside function body | ❌ No longer enforced — top-level `import` works | +| File must have `.py` extension | N/A for inline `config={"code": ...}` — only relevant when uploading a `.py` file | + +### v2 Notes + +- Integration action/input specs are discovered after connection (`list_actions`/`list_inputs`). +- Custom utility code (`aix.Utility`) has separate parser rules and requires `def main(...)`; do not confuse with Python Sandbox integration tools. + +```python +script_content = """def sum_then_square(first_number: int, second_number: int): + total = first_number + second_number + return total * total +""" +tool = aix.Tool( + name="Sum and Square", + description="Sums two numbers and squares the result.", + integration="688779d8bfb8e46c273982ca", + config={"code": script_content, "function_name": "sum_then_square"}, +).save() + +result = tool.run(action="sum_then_square", data={"first_number": 2, "second_number": 3}) +``` + +--- + +## 5. MCP Server (`686eb9cd26480723d0634d3e`) + +Connect with authenticated MCP server URL (often includes token). + +After connect, inspect full action list and disable destructive actions by default. Keep scoped action set minimal. + +### Studio Flow + +1. Integrations -> MCP Server -> Connect +2. Enter integration name + MCP URL +3. Connect and inspect `Actions` +4. Enable only required actions +5. Save agent + +### SDK Flow + +```python +mcp_tool = aix.Tool( + integration="aixplain/mcp-server", + name="Remote MCP Tool", + description="Remote MCP integration tool", + config={"url": ""}, + allowed_actions=["fetch"], +).save() + +# Optional direct test +mcp_tool.run(action="fetch", data={"url": "https://www.aixplain.com"}) + +# Attach to agent +agent = aix.Agent( + name="MCP Agent", + description="Fetches URL content via MCP.", + instructions="Use the MCP fetch tool to retrieve webpage content.", + output_format="markdown", + tools=[mcp_tool.as_tool()], +).save() +``` + +### Apify-Specific URL Pattern + +- Token-based auth: `https://actors-mcp-server.apify.actor/mcp?token=` +- Endpoint must include `/mcp` for aiXplain MCP connect path. +- Available actions include: `fetch-actor-details`, `search-actors`, `call-actor`, `search-apify-docs`, `fetch-apify-docs`, `apify-slash-rag-web-browser`, `get-actor-output`. + +### Troubleshooting + +- Error `There is nothing at route POST /...` -> wrong MCP endpoint path (missing `/mcp` or incompatible route). +- Tool not invoked -> make instructions explicit about when to use MCP and which action to prefer. +- Too many parameters/actions -> scope `allowed_actions` to a narrow vetted set. + +--- + +## 6. OAuth Integrations (Gmail, Slack, Jira, Google Drive) + +**CRITICAL:** The entire SDK Tool/Integration pipeline is broken for OAuth integrations. +`Integration.get()`, `Tool.get()`, and `Tool.search()` all crash with `AttributeError: 'str' object has no attribute 'items'` due to `dataclasses_json` deserialization failures. **Use REST throughout.** + +### REST-First Pattern (the only reliable path) + +```python +import requests + +BACKEND_URL = "https://platform-api.aixplain.com" +MODELS_RUN_URL = "https://models.aixplain.com/api/v2/execute" +H = {"x-api-key": API_KEY, "Content-Type": "application/json"} + +# ── Step 1: Create OAuth tool via integration run endpoint ── +INTEGRATION_ID = "6864328d1223092cb4294d30" # Gmail +resp = requests.post(f"{MODELS_RUN_URL}/{INTEGRATION_ID}", headers=H, + json={"name": "My Gmail Tool", "description": "Read and draft emails"}) +data = resp.json() + +if data.get("status") == "FAILED" and "already exists" in data.get("supplierError", ""): + # Name collision — search via REST or use timestamped name + search = requests.get(f"{BACKEND_URL}/sdk/models", + headers=H, params={"query": "My Gmail Tool", "pageSize": 50, "function": "utilities"}) + items = search.json().get("items", []) + tool_id = next((i["id"] for i in items if i["name"] == "My Gmail Tool"), None) +else: + tool_id = data["data"]["id"] + redirect_url = data["data"].get("redirectURL") + if redirect_url: + print(f"⚠️ OAuth required — user must visit: {redirect_url}") + +# ── Step 2: Fetch tool metadata via REST ── +# IMPORTANT: OAuth tools live under /sdk/models/, NOT /sdk/tools/ +model_data = requests.get(f"{BACKEND_URL}/sdk/models/{tool_id}", headers=H).json() + +# ── Step 3: Build agent-compatible payload ── +tool_payload = { + "id": tool_id, + "assetId": tool_id, + "name": model_data["name"], + "description": model_data.get("description", ""), + "supplier": model_data.get("supplier", {}).get("code", "aixplain"), + "parameters": model_data.get("params", []), + "function": model_data.get("function", {}).get("id", "utilities"), + "type": "tool", # MUST be "tool" — "model" fails API validation + "version": model_data.get("version", {}).get("id"), + "actions": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"], # scoped actions +} +``` + +### Key Gotchas + +1. **`type` must be `"tool"`** — `Model.as_tool()` returns `"model"` which fails validation for OAuth tools. +2. **REST endpoint is `/sdk/models/`** — `/sdk/tools/{id}` returns 404 for OAuth tools. +3. **Name collisions return no ID** — you must search or use timestamped names. +4. **OAuth redirect URL** — returned at creation time only. Capture and present to user. +5. **Agent update via REST** — if SDK `agent.save()` drops tool scopes, use `PUT /sdk/agents/{id}` directly. + +### Pre-Connected Tools (from dashboard) + +If a tool was already connected via the platform dashboard, skip creation and go straight to Step 2 (fetch metadata by known tool ID) and Step 3 (build payload). From 61b6ba0f71b1a15c8d646f4dd2453fce73d5e234 Mon Sep 17 00:00:00 2001 From: Nur Date: Tue, 7 Apr 2026 23:48:54 -0700 Subject: [PATCH 2/9] skills: rewrite setup section as Quick start flow Replaces the generic "Zero-setup requirements" list with a narrative that walks through the ask -> plan -> approve -> deploy flow, links to the Studio visual builder and analytics dashboard, and calls out Python Sandbox as the automatic fallback when a capability isn't in the marketplace. Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/skills/README.md b/skills/README.md index ceb5df9c..e53f1575 100644 --- a/skills/README.md +++ b/skills/README.md @@ -27,15 +27,20 @@ Drop this skill into any skill-compatible AI coding agent and start describing w | **Power users** | Export any deployed agent back to Python, reverse-engineer team architectures, add inspectors and governance | | **AI teams** | Safe API key handling, pre-build approval gates, no silent duplicates | -### Zero-setup requirements +### Quick start 1. Get an aiXplain API key. -2. Download or clone the [`aixplain-agent-builder/`](./aixplain-agent-builder) folder. -3. Drag it into your AI coding agent's chat window (Claude Code, Cursor, etc.) or point it to the folder path. -4. Say: **"Add this as a skill"** -5. Open the deployed agent in [aiXplain Studio](https://studio.aixplain.com) to inspect traces and runtime behavior. +2. Download or clone the [`aixplain-agent-builder/`](./aixplain-agent-builder) folder and add it to your AI coding agent (Claude Code, Cursor, etc.) as a skill. +3. Ask it to build something — for example: *"Build an agent that monitors competitor pricing and emails me a weekly summary."* +4. The skill searches the aiXplain marketplace for the right models, tools, and integrations, then hands you a **pre-build plan**: proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. +5. **Approve the plan** (or tweak it) — the skill then creates the agent, wires up the tools, runs a smoke test, and gives you back a deployed agent ID. +6. Open the agent in [aiXplain Studio](https://studio.aixplain.com) using the two links the skill returns: + - **Visual builder** (`studio.aixplain.com/build//schema`) — inspect or edit the agent graph, tools, instructions, and run traces. + - **Analytics dashboard** (`studio.aixplain.com/dashboard/analytics/?agent=`) — monitor runs, latency, token usage, and errors over time. -That's it. No pip installs, no config files, no environment setup — the skill auto-discovers your API key and walks you through anything it can't find. +> **Note:** If a required tool or integration isn't in the marketplace, the skill falls back to **Python Sandbox** — it writes a Python function for the missing capability, deploys it as a sandboxed tool, and attaches it to the agent automatically. No manual glue code required. + +No pip installs, no config files, no environment setup — the skill auto-discovers your API key and walks you through anything it can't find. ### What you can build From 45662845fa9c942c5a0f5db9d6e60d86270ef25d Mon Sep 17 00:00:00 2001 From: Nur Date: Tue, 7 Apr 2026 23:50:08 -0700 Subject: [PATCH 3/9] skills: link API key page and mention single-key PAYG model Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/README.md b/skills/README.md index e53f1575..f21e0be2 100644 --- a/skills/README.md +++ b/skills/README.md @@ -29,7 +29,7 @@ Drop this skill into any skill-compatible AI coding agent and start describing w ### Quick start -1. Get an aiXplain API key. +1. [Get an aiXplain API key](https://studio.aixplain.com/settings/keys) — one pay-as-you-go, pre-paid key unlocks every model, tool, and integration on the aiXplain marketplace. No per-provider billing, no separate vendor accounts. 2. Download or clone the [`aixplain-agent-builder/`](./aixplain-agent-builder) folder and add it to your AI coding agent (Claude Code, Cursor, etc.) as a skill. 3. Ask it to build something — for example: *"Build an agent that monitors competitor pricing and emails me a weekly summary."* 4. The skill searches the aiXplain marketplace for the right models, tools, and integrations, then hands you a **pre-build plan**: proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. From f1ff9bcf15c2fa358a4cc123d86f025db7773525 Mon Sep 17 00:00:00 2001 From: Nur Date: Tue, 7 Apr 2026 23:51:26 -0700 Subject: [PATCH 4/9] =?UTF-8?q?skills:=20tighten=20step=206=20=E2=80=94=20?= =?UTF-8?q?skill=20returns=20Studio=20links=20directly?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/README.md b/skills/README.md index f21e0be2..fd67028b 100644 --- a/skills/README.md +++ b/skills/README.md @@ -34,8 +34,8 @@ Drop this skill into any skill-compatible AI coding agent and start describing w 3. Ask it to build something — for example: *"Build an agent that monitors competitor pricing and emails me a weekly summary."* 4. The skill searches the aiXplain marketplace for the right models, tools, and integrations, then hands you a **pre-build plan**: proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. 5. **Approve the plan** (or tweak it) — the skill then creates the agent, wires up the tools, runs a smoke test, and gives you back a deployed agent ID. -6. Open the agent in [aiXplain Studio](https://studio.aixplain.com) using the two links the skill returns: - - **Visual builder** (`studio.aixplain.com/build//schema`) — inspect or edit the agent graph, tools, instructions, and run traces. +6. The skill returns two aiXplain Studio links for the deployed agent: + - **Visual builder & traces** (`studio.aixplain.com/build//schema`) — edit the agent graph, tools, and instructions, and inspect step-by-step run traces. - **Analytics dashboard** (`studio.aixplain.com/dashboard/analytics/?agent=`) — monitor runs, latency, token usage, and errors over time. > **Note:** If a required tool or integration isn't in the marketplace, the skill falls back to **Python Sandbox** — it writes a Python function for the missing capability, deploys it as a sandboxed tool, and attaches it to the agent automatically. No manual glue code required. From ed671d1f7be8c7d0b4979b4f4b98b3a40dd0e7b2 Mon Sep 17 00:00:00 2001 From: Nur Date: Wed, 8 Apr 2026 03:02:51 -0700 Subject: [PATCH 5/9] =?UTF-8?q?docs(skills):=20tighten=20README=20?= =?UTF-8?q?=E2=80=94=20compact=20quick=20start,=20who-it's-for=20one-liner?= =?UTF-8?q?,=20what-you-can-build=20table?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Collapse "Who it's for" to a single sentence with bolded archetypes - Compact "Quick start" to 5 steps; move longer explanation into "How it works under the hood" - Merge "What the skill does for you" into the same section - Convert "What you can build" into a Mode / Say / Does table - Drop example that assumes scheduling (weekly email); use on-demand phrasing Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 85 ++++++++++++++---------------------------------- 1 file changed, 25 insertions(+), 60 deletions(-) diff --git a/skills/README.md b/skills/README.md index fd67028b..3d73132a 100644 --- a/skills/README.md +++ b/skills/README.md @@ -20,73 +20,38 @@ Drop this skill into any skill-compatible AI coding agent and start describing w ### Who it's for -| Persona | What they get | -| --- | --- | -| **Non-technical builders** | Zero-code agent creation — just describe what you want | -| **Developers** | Production-ready Python, SDK patterns, OAuth wiring, error handling | -| **Power users** | Export any deployed agent back to Python, reverse-engineer team architectures, add inspectors and governance | -| **AI teams** | Safe API key handling, pre-build approval gates, no silent duplicates | +Built for **non-technical builders**, **developers**, **power users**, and **AI teams** who want working agents without boilerplate. ### Quick start -1. [Get an aiXplain API key](https://studio.aixplain.com/settings/keys) — one pay-as-you-go, pre-paid key unlocks every model, tool, and integration on the aiXplain marketplace. No per-provider billing, no separate vendor accounts. -2. Download or clone the [`aixplain-agent-builder/`](./aixplain-agent-builder) folder and add it to your AI coding agent (Claude Code, Cursor, etc.) as a skill. -3. Ask it to build something — for example: *"Build an agent that monitors competitor pricing and emails me a weekly summary."* -4. The skill searches the aiXplain marketplace for the right models, tools, and integrations, then hands you a **pre-build plan**: proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. -5. **Approve the plan** (or tweak it) — the skill then creates the agent, wires up the tools, runs a smoke test, and gives you back a deployed agent ID. -6. The skill returns two aiXplain Studio links for the deployed agent: - - **Visual builder & traces** (`studio.aixplain.com/build//schema`) — edit the agent graph, tools, and instructions, and inspect step-by-step run traces. - - **Analytics dashboard** (`studio.aixplain.com/dashboard/analytics/?agent=`) — monitor runs, latency, token usage, and errors over time. - -> **Note:** If a required tool or integration isn't in the marketplace, the skill falls back to **Python Sandbox** — it writes a Python function for the missing capability, deploys it as a sandboxed tool, and attaches it to the agent automatically. No manual glue code required. - -No pip installs, no config files, no environment setup — the skill auto-discovers your API key and walks you through anything it can't find. - -### What you can build - -**Build** - -Describe the agent in plain English. The skill drafts the plan, tools, output format, and guardrails before it builds. - -```text -"Build an agent that searches the web, finds competitor pricing, and emails me a summary" -"Create a support triage agent connected to our knowledge base and Jira" -"Make a real estate evaluator that looks up location data and computes cap rate" -``` - -**Run / Debug** +1. Grab an [aiXplain API key](https://studio.aixplain.com/settings/keys). +2. Clone [`aixplain-agent-builder/`](./aixplain-agent-builder) into your AI coding agent (Claude Code, Cursor, etc.). +3. Describe the agent — e.g. *"Build an agent that searches the web for competitor pricing and drafts a summary report."* +4. Review the pre-build plan → **approve**. +5. Get back a deployed agent ID and two Studio links: [visual builder & traces](https://studio.aixplain.com/build/) and [analytics dashboard](https://studio.aixplain.com/dashboard/analytics/). -Give it an agent ID or name. The skill runs it, inspects the steps, and diagnoses failures. +That's it — no pip installs, no config files, no environment setup. -```text -"Run agent 69ce064f44eef3c9e3850d95 with this query: Austin TX, 450k asking price" -"Debug why the agent isn't using the knowledge base" -"Inspect the execution steps from the last run" -``` - -**Deploy** +#### How it works under the hood -Once approved, the skill creates or updates the agent, connects the right tools, runs a smoke test, and leaves you with a working asset. - -```text -"Deploy this customer support agent to aiXplain and test it with a ticket triage prompt" -"Build this real-estate evaluator and deploy it to my workspace" -"Create the team agent, connect the tools, and validate the first run" -``` +- **One key, every provider.** The aiXplain API key is pay-as-you-go and pre-paid — a single key unlocks every model, tool, and integration on the marketplace. No per-provider billing, no separate vendor accounts. +- **Plan before build.** The skill searches the marketplace for the right models, tools, and integrations, then shows a pre-build plan: proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. Nothing is created until you approve. +- **Deploy + smoke test.** On approval it creates the agent, wires the tools, runs a smoke test, and hands back a working agent ID — reusing existing agents instead of creating silent duplicates. +- **Two Studio links, always.** `studio.aixplain.com/build//schema` to edit the graph, tools, instructions, and inspect step-by-step traces; `studio.aixplain.com/dashboard/analytics/?agent=` to monitor runs, latency, token usage, and errors over time. +- **Missing integration? No problem.** If a required tool isn't in the marketplace, the skill falls back to **Python Sandbox** — it writes a Python function for the missing capability, deploys it as a sandboxed tool, and attaches it to the agent automatically. +- **Safe key handling.** Keys are auto-discovered from `~/.env` → repo `.env` → environment variables, and always set as env vars — never hardcoded into generated files. -### What the skill does for you - -- Shows a pre-build plan before creating anything -- Finds API keys from `~/.env`, repo `.env`, or environment variables -- Reuses existing agents instead of creating duplicates -- Surfaces OAuth connection links when integrations need them -- Runs a smoke test and checks for grounded output - -```text -~/.env → repo .env → environment variables → asks you -``` +### What you can build -Keys are set as environment variables, never hardcoded into generated files. +| Mode | What you say | What the skill does | +| --- | --- | --- | +| **Build** | *"Build an agent that searches the web and summarizes competitor pricing into a markdown report"* | Drafts the plan, tools, output format, and guardrails before creating anything | +| **Build** | *"Create a support triage agent connected to our knowledge base and Jira"* | Finds the right integrations, proposes the architecture, waits for approval | +| **Build** | *"Make a real-estate evaluator that looks up location data and computes cap rate"* | Picks models + tools, writes any missing logic as a Python Sandbox function | +| **Run / Debug** | *"Run agent 69ce064f44eef3c9e3850d95 with query: Austin TX, 450k asking price"* | Executes, inspects the step trace, and explains the result | +| **Run / Debug** | *"Debug why the agent isn't using the knowledge base"* | Inspects recent runs, diagnoses tool selection, suggests fixes | +| **Deploy** | *"Deploy this customer support agent and test it with a ticket triage prompt"* | Creates/updates the agent, connects tools, runs a smoke test | +| **Export** | *"Export agent 69abc… back to Python"* | Reverse-engineers a deployed agent into runnable SDK code | ### Best practices baked in @@ -106,7 +71,7 @@ runResponseGeneration=True + output_format="markdown" -> richest output - **Web research agent** — *"Build an agent that searches the web and summarizes findings into a markdown report"* - **Support triage** — *"Create a support agent that searches our KB, checks ticket history in Jira, and classifies by severity"* - **Data analyst** — *"Build an agent that runs Python on uploaded CSVs and produces charts"* -- **Email assistant** — *"Make an agent that reads my Gmail, groups by topic, and drafts replies"* +- **Email assistant** — *"Make an agent that reads my Gmail inbox on demand, groups by topic, and drafts replies"* - **Deploy** — *"Build this agent, deploy it to my workspace, and validate the first run"* - **Debug** — *"Why did agent 69abc… return a hallucinated answer instead of using the KB?"* - **Knowledge base** — *"Create an agent connected to our product docs KB that answers support questions"* From 7d91c7bbf3bf4229ca63a9d9305883f494d3deae Mon Sep 17 00:00:00 2001 From: Nur Date: Wed, 8 Apr 2026 03:11:56 -0700 Subject: [PATCH 6/9] docs(skills): add "Why aiXplain Agent Builder" section, drop best-practices list - Add 8-item value prop list above "Who it's for" - Remove standalone "Best practices baked in" section (covered by item 6) Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/skills/README.md b/skills/README.md index 3d73132a..715d3950 100644 --- a/skills/README.md +++ b/skills/README.md @@ -18,6 +18,17 @@ Drop this skill into any skill-compatible AI coding agent and start describing w > **SDK version:** `aixplain==0.2.44` +### Why aiXplain Agent Builder + +1. **Natural language, no code.** Describe it → plan → approve → build → test. +2. **Deploy instantly, free.** No infra bill — pay only for runtime usage. +3. **Agents live on a platform.** Edit, trace, monitor, and version in aiXplain Studio. +4. **One marketplace, one key.** Models, tools, integrations, and MCPs behind a single API key. +5. **Never blocked by missing tools.** Falls back to Python Sandbox and wires it in automatically. +6. **Best practices baked in.** Strong instructions, scoped actions, smart iteration limits, speed/quality tuning. +7. **Safe key handling.** Auto-discovered from env, never hardcoded into generated files. +8. **Portable skill.** Runs in any skill-compatible agent — Claude Code, Cursor, and more. + ### Who it's for Built for **non-technical builders**, **developers**, **power users**, and **AI teams** who want working agents without boilerplate. @@ -53,19 +64,6 @@ That's it — no pip installs, no config files, no environment setup. | **Deploy** | *"Deploy this customer support agent and test it with a ticket triage prompt"* | Creates/updates the agent, connects tools, runs a smoke test | | **Export** | *"Export agent 69abc… back to Python"* | Reverse-engineers a deployed agent into runnable SDK code | -### Best practices baked in - -- Uses a strong instruction format: `ROLE`, `CONSTRAINTS`, and `OUTPUT RULES` -- Keeps tool descriptions short and action-oriented for better selection -- Picks practical iteration limits for lookup vs. deep research tasks -- Scopes tool actions to the minimum required set -- Chooses speed vs. quality settings based on the use case - -```text -runResponseGeneration=False + output_format="text" -> ~30-40% faster -runResponseGeneration=True + output_format="markdown" -> richest output -``` - ### Sample queries to try - **Web research agent** — *"Build an agent that searches the web and summarizes findings into a markdown report"* From 88bdf3beba463016e11c9904e3f2eb1dc1e812da Mon Sep 17 00:00:00 2001 From: Nur Date: Wed, 8 Apr 2026 03:13:25 -0700 Subject: [PATCH 7/9] =?UTF-8?q?docs(skills):=20dedupe=20README=20=E2=80=94?= =?UTF-8?q?=20trim=20"How=20it=20works",=20merge=20sample=20queries=20into?= =?UTF-8?q?=20"What=20you=20can=20build"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove bullets in "How it works" that duplicate the Why list; keep only unique details (plan contents, reuse, Studio links, key discovery order) - Merge "Sample queries to try" into the "What you can build" table as additional Build rows Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/skills/README.md b/skills/README.md index 715d3950..c0ccc5e9 100644 --- a/skills/README.md +++ b/skills/README.md @@ -45,35 +45,24 @@ That's it — no pip installs, no config files, no environment setup. #### How it works under the hood -- **One key, every provider.** The aiXplain API key is pay-as-you-go and pre-paid — a single key unlocks every model, tool, and integration on the marketplace. No per-provider billing, no separate vendor accounts. -- **Plan before build.** The skill searches the marketplace for the right models, tools, and integrations, then shows a pre-build plan: proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. Nothing is created until you approve. -- **Deploy + smoke test.** On approval it creates the agent, wires the tools, runs a smoke test, and hands back a working agent ID — reusing existing agents instead of creating silent duplicates. -- **Two Studio links, always.** `studio.aixplain.com/build//schema` to edit the graph, tools, instructions, and inspect step-by-step traces; `studio.aixplain.com/dashboard/analytics/?agent=` to monitor runs, latency, token usage, and errors over time. -- **Missing integration? No problem.** If a required tool isn't in the marketplace, the skill falls back to **Python Sandbox** — it writes a Python function for the missing capability, deploys it as a sandboxed tool, and attaches it to the agent automatically. -- **Safe key handling.** Keys are auto-discovered from `~/.env` → repo `.env` → environment variables, and always set as env vars — never hardcoded into generated files. +- **Plan contents.** The pre-build plan shows the proposed architecture, tools to connect, output format, and any OAuth links you'll need to authorize. +- **Reuses existing agents.** Matches by name and updates in place instead of creating silent duplicates. +- **Two Studio links, always.** `studio.aixplain.com/build//schema` for the visual editor and step traces; `studio.aixplain.com/dashboard/analytics/?agent=` for runs, latency, tokens, and errors. +- **Key discovery order.** `~/.env` → repo `.env` → environment variables → prompts you. ### What you can build | Mode | What you say | What the skill does | | --- | --- | --- | -| **Build** | *"Build an agent that searches the web and summarizes competitor pricing into a markdown report"* | Drafts the plan, tools, output format, and guardrails before creating anything | -| **Build** | *"Create a support triage agent connected to our knowledge base and Jira"* | Finds the right integrations, proposes the architecture, waits for approval | -| **Build** | *"Make a real-estate evaluator that looks up location data and computes cap rate"* | Picks models + tools, writes any missing logic as a Python Sandbox function | -| **Run / Debug** | *"Run agent 69ce064f44eef3c9e3850d95 with query: Austin TX, 450k asking price"* | Executes, inspects the step trace, and explains the result | -| **Run / Debug** | *"Debug why the agent isn't using the knowledge base"* | Inspects recent runs, diagnoses tool selection, suggests fixes | -| **Deploy** | *"Deploy this customer support agent and test it with a ticket triage prompt"* | Creates/updates the agent, connects tools, runs a smoke test | +| **Build — Web research** | *"Build an agent that searches the web and summarizes competitor pricing into a markdown report"* | Drafts a plan with the right tools, output format, and guardrails | +| **Build — Support triage** | *"Create a support agent that searches our KB, checks Jira ticket history, and classifies by severity"* | Finds the integrations, proposes the architecture, waits for approval | +| **Build — Data analyst** | *"Build an agent that runs Python on uploaded CSVs and produces charts"* | Picks models + tools, writes missing logic as a Python Sandbox function | +| **Build — Email assistant** | *"Make an agent that reads my Gmail inbox on demand, groups by topic, and drafts replies"* | Wires OAuth, scopes Gmail actions, runs a smoke test | +| **Build — Real estate** | *"Make a real-estate evaluator that looks up location data and computes cap rate"* | Combines marketplace tools with custom Python for the math | +| **Run** | *"Run agent 69ce064f44eef3c9e3850d95 with: Austin TX, 450k asking price"* | Executes, inspects the step trace, and explains the result | +| **Debug** | *"Why isn't the agent using the knowledge base?"* | Inspects recent runs, diagnoses tool selection, suggests fixes | | **Export** | *"Export agent 69abc… back to Python"* | Reverse-engineers a deployed agent into runnable SDK code | -### Sample queries to try - -- **Web research agent** — *"Build an agent that searches the web and summarizes findings into a markdown report"* -- **Support triage** — *"Create a support agent that searches our KB, checks ticket history in Jira, and classifies by severity"* -- **Data analyst** — *"Build an agent that runs Python on uploaded CSVs and produces charts"* -- **Email assistant** — *"Make an agent that reads my Gmail inbox on demand, groups by topic, and drafts replies"* -- **Deploy** — *"Build this agent, deploy it to my workspace, and validate the first run"* -- **Debug** — *"Why did agent 69abc… return a hallucinated answer instead of using the KB?"* -- **Knowledge base** — *"Create an agent connected to our product docs KB that answers support questions"* - ### Integrations supported The skill has access to 600+ integrations including: From 231b4c09720a0660d48d1f9997affe1ac5f6a771 Mon Sep 17 00:00:00 2001 From: Nur Date: Wed, 8 Apr 2026 03:47:49 -0700 Subject: [PATCH 8/9] docs(skills): convert "What you can build" table to a list Co-Authored-By: Claude Opus 4.6 --- skills/README.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/skills/README.md b/skills/README.md index c0ccc5e9..f897e610 100644 --- a/skills/README.md +++ b/skills/README.md @@ -52,16 +52,14 @@ That's it — no pip installs, no config files, no environment setup. ### What you can build -| Mode | What you say | What the skill does | -| --- | --- | --- | -| **Build — Web research** | *"Build an agent that searches the web and summarizes competitor pricing into a markdown report"* | Drafts a plan with the right tools, output format, and guardrails | -| **Build — Support triage** | *"Create a support agent that searches our KB, checks Jira ticket history, and classifies by severity"* | Finds the integrations, proposes the architecture, waits for approval | -| **Build — Data analyst** | *"Build an agent that runs Python on uploaded CSVs and produces charts"* | Picks models + tools, writes missing logic as a Python Sandbox function | -| **Build — Email assistant** | *"Make an agent that reads my Gmail inbox on demand, groups by topic, and drafts replies"* | Wires OAuth, scopes Gmail actions, runs a smoke test | -| **Build — Real estate** | *"Make a real-estate evaluator that looks up location data and computes cap rate"* | Combines marketplace tools with custom Python for the math | -| **Run** | *"Run agent 69ce064f44eef3c9e3850d95 with: Austin TX, 450k asking price"* | Executes, inspects the step trace, and explains the result | -| **Debug** | *"Why isn't the agent using the knowledge base?"* | Inspects recent runs, diagnoses tool selection, suggests fixes | -| **Export** | *"Export agent 69abc… back to Python"* | Reverse-engineers a deployed agent into runnable SDK code | +- **Build — Web research.** *"Build an agent that searches the web and summarizes competitor pricing into a markdown report"* → drafts a plan with the right tools, output format, and guardrails. +- **Build — Support triage.** *"Create a support agent that searches our KB, checks Jira ticket history, and classifies by severity"* → finds the integrations, proposes the architecture, waits for approval. +- **Build — Data analyst.** *"Build an agent that runs Python on uploaded CSVs and produces charts"* → picks models + tools, writes missing logic as a Python Sandbox function. +- **Build — Email assistant.** *"Make an agent that reads my Gmail inbox on demand, groups by topic, and drafts replies"* → wires OAuth, scopes Gmail actions, runs a smoke test. +- **Build — Real estate.** *"Make a real-estate evaluator that looks up location data and computes cap rate"* → combines marketplace tools with custom Python for the math. +- **Run.** *"Run agent 69ce064f44eef3c9e3850d95 with: Austin TX, 450k asking price"* → executes, inspects the step trace, and explains the result. +- **Debug.** *"Why isn't the agent using the knowledge base?"* → inspects recent runs, diagnoses tool selection, suggests fixes. +- **Export.** *"Export agent 69abc… back to Python"* → reverse-engineers a deployed agent into runnable SDK code. ### Integrations supported From 97a7ce9ae45750f6df2af9a2e6457e0fc26aeddb Mon Sep 17 00:00:00 2001 From: Nur Date: Wed, 8 Apr 2026 03:50:45 -0700 Subject: [PATCH 9/9] docs(skill): add explicit Python Sandbox fallback policy When a capability is not available as a marketplace tool/integration, the skill must announce in the plan that it will build a Python Sandbox function instead of stopping with "not found". Co-Authored-By: Claude Opus 4.6 --- skills/aixplain-agent-builder/SKILL.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/skills/aixplain-agent-builder/SKILL.md b/skills/aixplain-agent-builder/SKILL.md index 90b0d22d..49a6e86d 100644 --- a/skills/aixplain-agent-builder/SKILL.md +++ b/skills/aixplain-agent-builder/SKILL.md @@ -71,6 +71,19 @@ print(match.id, match.name) When the user asks for an integration/tool/model that isn't in the Quick Asset IDs table, **run the matching `.search()` first**. Only report "not found" after the search returns no match. +## Fallback: Python Sandbox for missing tools + +**Never tell the user "this tool is not available" and stop.** If `.search()` returns no marketplace tool or integration for a needed capability, fall back to **Python Sandbox**: implement the missing capability as a Python function and wire it as a tool. + +Required behavior: + +1. **Announce it in the plan.** Before building, tell the user explicitly: *"`` is not available as a marketplace tool/integration. I will build it as a Python Sandbox function and wire it into the agent as part of the plan."* +2. **Wait for plan approval** as usual. +3. **Build the Python Sandbox tool** following `references/integration-playbooks.md` → Python Sandbox (exact `config={...}` shape, authoring constraints, type rules). +4. **Only ask the user when external inputs are required** — API keys, credentials, file paths, schemas. Do not invent placeholders. + +The only acceptable "cannot build" case is when the capability fundamentally requires an external credentialed service the user has not provided (and even then, ask first). + ## Build Agent Apply the search-first principle: