Agents quickstart

Build, run, and ship an aixplain agent from Python in a few minutes. This page is written to be copy-pasteable and correct on the first run — every snippet below was executed against the live platform, and the gotchas that most often trip up automated/coding workflows are called out in the Troubleshooting table.

Get a key from app.aixplain.com/team/settings?tab=api-keys. Browse assets on app.aixplain.com/marketplace.

---

Setup

Install the SDK, then create the client.

pip install --upgrade aixplain

from aixplain import Aixplain

aix = Aixplain(api_key="<AIXPLAIN_API_KEY>")

---

1. Create and run an agent

An agent needs a name, description, and instructions. .save() provisions it and returns its ID.

agent = aix.Agent(
    name="Quickstart Agent",
    description="Answers general questions.",
    instructions="You are a concise assistant. Answer in one sentence.",
).save()

print("Agent ID:", agent.id)

result = agent.run(query="What is the capital of Japan?")
print(result.data.output)

Show output

tip

Agents use the platform default LLM. To pin a specific model (recommended for reproducibility, and required when the default is unavailable), pass llm="<model_id>" to aix.Agent(...).

---

2. Add a tool (and scope it)

Attach a Marketplace tool so the agent can act. Always narrow allowed_actions before attaching.

tavily = aix.Tool.get("6931bdf462eb386b7158def3")  # Tavily Web Search (stable first-party ID)
tavily.allowed_actions = ["search"]                # scope to the minimum

web_agent = aix.Agent(
    name="Quickstart Web Agent",
    description="Answers using web search.",
    instructions="Use web search for current information. Answer in one sentence.",
    tools=[tavily],
).save()

result = web_agent.run(query="What is the aixplain Marketplace? Search the web.")
print([step["unit"]["name"] for step in result.data.steps])
print(result.data.output)

Show output

The steps trace is your ground truth for what the agent actually did. Assert the expected tool unit appears there rather than inferring tool use from the answer text.

---

3. Find assets to use

Don't hardcode or guess asset IDs — search first. The one-call, cross-type search returns agents, models, tools, and integrations, each under a results list.

import json

search = aix.Tool.get("6960f934f316da19e5f22494")  # aixplain Marketplace Search
result = search.run(action="search", data=json.dumps({"query": "pdf"}))

print({kind: list(block.keys()) for kind, block in result.data.items()})
print([(a["name"], a["id"]) for a in result.data["integration"]["results"][:2]])

Show output

warning

Each asset kind is {"results": [...], "stats": {...}}. Read result.data[kind]["results"]. Older examples that read items return nothing.

---

4. Cap the cost of a run

Set a budget on the agent. When a cap is hit, the run finalizes gracefully and reports it in governance — it does not raise.

from aixplain.v2 import Budget

agent.budget = Budget(max_cost=0.50, max_duration_seconds=120, max_iterations=10)
result = agent.run(query="Summarize today's AI news.")

print(result.data.governance)   # {'status': 'ALLOWED'} within budget, else 'BLOCKED_BY_BUDGET'

With a zero cap you can see the block path directly:

Show output

warning

agent.run(query=..., budget=Budget(...)) — a budget= kwarg on the run is silently ignored. Always set agent.budget. Treat the budget as a circuit breaker, not a billing ceiling, and read actual spend from result.data.execution_stats["credits"].

---

5. Get structured (JSON) output

Ask for JSON with output_format plus an expected_output schema/shape. Do not use runResponseGeneration — it is deprecated and ignored.

agent = aix.Agent(
    name="Extractor",
    description="Extracts fields from text.",
    instructions="Extract the requested fields.",
    output_format="json",
    expected_output='{"name": "string", "sentiment": "positive|neutral|negative"}',
).save()

result = agent.run(query="Review: The onboarding was smooth and the support team was great. — Dana")
print(result.data.output)   # a JSON string matching the expected shape

---

Deploy and monitor

After .save(), your agent is live and reachable by ID. Open it in Studio:

• Visual builder: https://app.aixplain.com/studio
• Analytics: https://app.aixplain.com/dashboard

Run asynchronously when you don't want to block:

async_result = agent.run_async(query="...")
result = agent.sync_poll(async_result.url)   # returns the same shape as run()
print(result.data.output)

---

Quick asset paths

aix.Tool.get(...) accepts an asset's supplier path as well as its raw ID — the path is stable and more readable. First-party assets have stable paths across DEV/TEST/PROD, so referencing them by path is safe. Workspace-bound tool instances and OAuth/Composio integrations do not; create those fresh from their integration each deploy.

Asset	Path
Tavily Web Search	tavily/tavily-web-search/tavily
Code Execution	microsoft/code-execution/microsoft
Firecrawl API	firecrawl/firecrawl-api/firecrawl
Docling Document Parser	aixplain/docling/aixplain
aixplain Marketplace Search	aixplain/aixplain-marketplace-search/aixplain
Shared Memory (integration)	aixplain/shared-memory/aixplain
Python Sandbox (integration)	aixplain/python-sandbox/aixplain

tavily = aix.Tool.get("tavily/tavily-web-search/tavily")   # path works just like an ID

To find anything else, use aix.Model.search(query=...) / aix.Tool.search(query=...) and read the .results.

---

Troubleshooting

Symptom	Cause	Fix
MODEL_UNAVAILABLE on run	Platform default LLM is down	Pin a model: aix.Agent(..., llm="<model_id>")
Search loop finds nothing	Reading items	Read result.data[kind]["results"]
Budget "didn't work"	budget= passed to run() (ignored)	Set agent.budget = Budget(...)
Agent over-privileged / weaker reasoning	Tool attached with all actions	tool.allowed_actions = [...] before attaching
A required tool never runs on a static task graph	Static tasks can skip attached tools	Use adaptive/planner execution and assert the tool unit in result.data.steps
Re-saving an edited agent broadened tool permissions	Agent.get() widens hydrated tool scopes	Before save(), re-apply each tool's intended allowed_actions; verify the raw v2/agents/<id> payload after

note

When you hit behavior that is clearly on aixplain's side (a documented parameter ignored, an action that always fails), reproduce it minimally and report it — don't paper over it with a workaround alone.

---

Cleanup

agent.delete()
web_agent.delete()