Aixplain Agent Builder

aiXplain Agent Builder

Design, deploy, run, and manage aiXplain agents — single agents, team agents, tools, and OAuth integrations.

Last updated: 2026-05-31 · Verified against aiXplain SDK: v0.2.44 (inspector API verified live)

Audience & Self-Containment

This skill is used on behalf of both non-developers and developers. They will not read the SDK source, API reference, or GitHub. Therefore:

• This skill is the single source of truth. Every code block here is verified against the SDK version above — use it as written. Do not tell the user to consult the SDK docs, GitHub, or source code.
• Do the technical work yourself. Write and run the code; the user should not have to. Never hand a non-developer a traceback — diagnose it, fix it, and report the outcome in plain language (what happened, what you did, what's next).
• Explain in plain terms for non-developers, but keep full code available for developers who want it. Lead with the result and the Studio link, not the implementation.
• If a snippet here ever fails against the installed SDK, the skill is wrong, not the user. Fix the skill in place, then follow the "Report aiXplain-Caused Issues" habit (see Debugging) — never redirect the user to external docs to work around it.

How It Works

This skill accepts the following commands:

• Build agent — plan, search tools, create tools, assemble and save the agent
• Deploy agent — save and share Studio links for visual editing and analytics
• Run agent — execute sync or async and return the output
• Debug agent — diagnose tool, action, OAuth, or runtime issues
• Export agent — generate a standalone Python script from a deployed agent

1. Setup

Always install/upgrade to the latest SDK before doing anything: pip install --upgrade aixplain.

This skill is verified against SDK v0.2.44. If the installed version differs, tell the user.

import os
from dotenv import load_dotenv
from aixplain import Aixplain

load_dotenv()  # loads AIXPLAIN_API_KEY from .env if present

api_key = os.getenv("AIXPLAIN_API_KEY")
if not api_key:
    raise ValueError("AIXPLAIN_API_KEY not set. Add it to your .env file or environment.")

aix = Aixplain(api_key=api_key)

Passing local files to agents or aiXplain assets: Use FileUploader to upload a file to aiXplain S3 and get a presigned URL. Pass that URL anywhere a URL input is accepted (tools, models, integrations). Resource.save() is internal and not usable standalone.

from aixplain.v2.upload_utils import FileUploader
uploader = FileUploader(api_key=api_key)
file_url = uploader.upload("/path/to/file.mp3", is_temp=True, return_download_link=True)

Downloadable links: If the agent needs to return files the user can click and download, always set return_download_link=True. Without it, upload() returns a raw s3:// path that is not browser-accessible.

MIME type patch for .html and .zip: The SDK's MimeTypeDetector does not include these extensions — both fall back to text/csv, causing browsers to save files with the wrong extension. Always patch before uploading when generating these file types:

from aixplain.v2.upload_utils import MimeTypeDetector
MimeTypeDetector.EXTENSION_MAPPING['.html'] = 'text/html'
MimeTypeDetector.EXTENSION_MAPPING['.zip']  = 'application/zip'

2. Plan

Before building, present a plan to the user covering: agent name, description, instructions, which tools/integrations to use, and whether it's a single or team agent. Wait for approval before proceeding.

Always search before creating or hardcoding a tool or integration. Tool, Model, and Integration all support .search(query=...).results. Never say "not available" without searching first.

results = aix.Tool.search(query="web search").results
# Names may be concatenated (e.g. "Googledrive"). Normalize before comparing.

If a needed capability has no marketplace tool or integration, announce you'll build it as a Python Sandbox function (see references/integration-playbooks.md § 4).

3. Create Tools

MANDATORY: Scope allowed_actions on every tool. Never attach a tool to an agent without first narrowing its actions to the minimum needed for the task. Tools loaded via Tool.get() come with all actions enabled by default — this is over-privileged and degrades agent reasoning. Inspect tool.actions to see the full set, then assign tool.allowed_actions = [...] (or pass allowed_actions=[...] in the constructor) before adding to the agent. If you genuinely need all actions, state that explicitly to the user and confirm.

tool = aix.Tool.get("<ID>")
print(tool.actions)              # discover available actions
tool.allowed_actions = ["search_models", "list_filters"]  # scope to task

Three paths, in order of preference:

# Path A: Marketplace tool by ID — REMEMBER to scope allowed_actions after .get()
tool = aix.Tool.get("698cda188bbb345db14ac13b")  # Code Execution
tool.allowed_actions = [...]  # required

# Path B: Non-OAuth integration (KB, SQLite)
# READ references/integration-playbooks.md for config payloads.
# Ask the user for any missing inputs — never invent placeholders.
# Always create fresh; do not reuse by name unless explicitly asked.
tool = aix.Tool(name="KB Search", description="Search product docs",
    integration="6904bcf672a6e36b68bb72fb", allowed_actions=["search", "get"]).save()

# Path C: OAuth integration (Gmail, Slack, Jira, Google Drive)
# READ references/integration-playbooks.md § 5 for full workflow.
# (1) integration = aix.Integration.get("<ID>")
# (2) integration.list_actions() → discover action names
# (3) Create tool with allowed_actions in constructor
# (4) User completes OAuth via redirect URL emitted at .save()
# (5) Attach in-memory tool object to agent and save

# Path D: Python Sandbox (last resort)
# READ references/integration-playbooks.md § 4 for config shape.

4. Build Agent

Agents use the platform default LLM — do not specify llm unless the user requests a specific model.

agent = aix.Agent(
    name="My Agent", description="...", instructions="...",
    tools=[tool], output_format="markdown",
    max_tokens=6000,  # set at creation, not per-run
).save()

If save() raises name_already_exists, ask the user: update existing or create with a new name.

5. Deploy & Run

After deploy, share these links with the user:

• Visual builder: https://studio.aixplain.com/build/<AGENT_ID>/schema
• Analytics: https://studio.aixplain.com/dashboard/analytics/?agent=<AGENT_ID>

Default: leave runResponseGeneration unset. Only pass runResponseGeneration=True when you specifically need structured/JSON output.

# Sync — default text output
result = agent.run(query="...")
print(result.data.output)

# Sync — structured/JSON output
result = agent.run(query="...", runResponseGeneration=True)

# Async — SDK handles polling; no manual HTTP needed
ar = agent.run_async(query="...")
result = agent.sync_poll(ar.url)   # blocks until SUCCESS/FAILED, returns the same result shape as run()
print(result.data.output)

6. Debugging

Inspect Intermediate Steps

result = agent.run(query="...")

# Step-by-step trace: thought, action, tool used, input/output, tokens
for step in result.data.steps:
    print(step['thought'], step['action'], step['unit']['name'])

# Aggregate costs and timing
stats = result.data.execution_stats
print(stats['credits'], stats['runtime'], stats['api_calls'])

Or view traces visually in Studio: https://studio.aixplain.com/build/<AGENT_ID>/schema

Report aiXplain-Caused Issues

When you hit a quirk or error that is aiXplain-caused — not a mistake in the user's code, query, or config — make it a habit to propose filing a GitHub issue at https://github.com/aixplain/aiXplain. Examples: an action advertised by an integration that always fails, an SDK method that misbehaves, a documented parameter the backend ignores, a connector requesting insufficient OAuth scopes.

Workflow:

1. Confirm the cause is on aiXplain's side (reproduce it; rule out user input, missing scopes the user controls, rate limits, etc.).
2. Propose the issue to the user with a draft title and body. Do not post without confirmation — the repo is public.
3. Redact personal data from the public issue: no API keys, real email addresses, tool/agent IDs, message counts, or any account-specific data. Keep repro steps generic.
4. On approval, post with gh issue create --repo aixplain/aiXplain and share the issue link.

Issue body should include: SDK version, integration/asset type, a minimal repro, the exact error, and expected vs. actual behavior.

Quick Asset IDs

Reference Files

• references/integration-playbooks.md — config payloads, file upload, authoring constraints, and OAuth workflow for all integration types
• references/agent-patterns.md — team agents, updating deployed agents, inspectors, export to Python, Code Execution vs Python Sandbox
• references/inspectors.md — inspector policies, action values, and post-change validation

External Links

• Docs: https://docs.aixplain.com
• Pricing: https://aixplain.com/pricing
• Studio: https://studio.aixplain.com

Source: aixplain/aiXplain — distributed by TomeVault.