aiXplain Agent Builder#

Use this skill to plan, inspect, and build aiXplain agents with conservative defaults, read-only discovery first, and explicit approval gates for higher-risk actions.

Default Operating Mode#

Start in read-only planning mode.

Until the user explicitly approves a higher-risk step, do not:

• install or upgrade packages
• request sensitive values in chat when existing environment configuration should be used
• upload local files to remote storage
• create authenticated integration tools
• enable write actions on integrations
• create runtime-execution tools or custom script-backed tools
• bypass standard SDK or platform flows with direct export calls

If the user wants execution or deployment, confirm that the required environment is already configured. Do not auto-fix the environment.

Supported Commands#

• Plan agent: define the agent goal, tool strategy, and approval gates
• Inspect marketplace: search existing tools, models, or integrations before proposing custom work
• Build approved agent: create an agent only after the user approves the plan
• Debug existing agent: inspect configuration, traces, and tool choices without widening permissions

Workflow#

1. Plan First#

Before building anything, present a short plan covering:

• agent name
• description
• instructions
• expected inputs and outputs
• proposed tools or integrations
• whether each tool is read-only or write-capable
• which steps require approval

Wait for approval before creating or updating an agent.

2. Search Before Hardcoding#

Always search for existing marketplace assets before proposing a new tool or integration.

python

import os
from aixplain import Aixplain

aix = Aixplain(api_key=os.getenv("AIXPLAIN_API_KEY"))

tool_results = aix.Tool.search(query="web search").results
integration_results = aix.Integration.search(query="google drive").results
model_results = aix.Model.search(query="gpt").results

Do not say a capability is unavailable until you have searched for it.

3. Prefer Existing Read-Only Assets#

Use this order of preference:

1. Existing marketplace tool
2. Existing integration with a non-empty least-privilege read-only action set
3. Custom or write-capable setup only after explicit approval

Treat these as higher-risk and require approval before proposing them:

• authenticated integrations
• remote file uploads
• database write actions
• runtime code tools
• custom script-backed tools

See references/safety-gates.md.

4. Build Only After Approval#

When the user approves the plan, build the agent with the smallest necessary surface area.

python

import os
from aixplain import Aixplain

aix = Aixplain(api_key=os.getenv("AIXPLAIN_API_KEY"))
search_tool = aix.Tool.get("<PUBLIC_TOOL_ID>")

agent = aix.Agent(
    name="My Agent",
    description="Summarizes and answers with linked sources.",
    instructions="Use only attached tools. If a request needs missing access, say so clearly.",
    tools=[search_tool],
    output_format="markdown",
    max_tokens=4000,
).save()

Do not specify a custom llm unless the user explicitly asks for one.

4.1 Integration File Handling#

Do not upload local files by default when configuring integrations such as:

• aiR Knowledge Base
• SQLite and other DB-style integrations
• Python Sandbox

Preferred behavior:

• pass the local file path directly when the integration accepts file-backed config during connect or build
• use file upload only when calling .run() and the runtime input itself must be a file asset

Practical rule:

• setup time: prefer direct local file paths
• runtime: upload only if the specific .run() input requires a remote file reference

If a backend rejects the direct file path, report the backend-specific validation clearly instead of treating upload as the default first step.

4.2 OAuth Integration Behavior#

For OAuth-based integrations, a newly created tool may be created successfully but remain unusable until the connection flow is completed.

Treat this as the normal flow:

• create the tool
• capture and return redirect_url
• tell the user the tool is not runnable yet
• wait for the user to complete the connection flow
• only then run the tool

Treat the presence of redirect_url as the expected pending-auth state.

Typical pattern:

python

tool = integration.connect(name="My OAuth Tool")

if getattr(tool, "redirect_url", None):
    print(tool.redirect_url)
    # User must complete OAuth before the tool is runnable.

Before the connection flow is completed, report the tool as pending and provide the redirect_url.

5. Deployment and Debugging#

After a successful save, share only the standard Studio links:

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

For debugging, prefer SDK-visible agent configuration, run output, and Studio traces before proposing tool changes.

For detailed execution tracing during SDK runs, prefer:

python

result = agent.run(
    query="...",
    progress_verbosity=3,
)

Observed behavior in this environment:

• progress_verbosity=3 works with the installed aiXplain v2 agent path
• it returns full step traces, including model thoughts, tool calls, tool inputs, and tool outputs
• depending on SDK or shell buffering, the trace may appear in the final returned payload rather than as truly incremental live stdout

Use this for debugging or verification runs when you need the exact search, tool, and output trace.

References#

• references/safety-gates.md - approval rules for risky actions
• references/read-only-patterns.md - safe search and build examples