Quickstart

Create an agent that searches the web, run it, check what it did, then make it return JSON.

• Python 3.9 or later.
• An API key from the aixplain app.

Install the SDK

pip install aixplain

Create and run an agent

Paste your API key in place of YOUR_API_KEY and run the script.

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

agent = aix.Agent(
    name="Research agent",
    description="Answers questions with cited web findings.",
    instructions="Use web search when needed and keep answers concise.",
    tools=[aix.Tool.get("tavily/tavily-web-search/tavily")],
).save()

result = agent.run("What are the top 3 trending AI papers this week?")
print(result.data.output)

Show output

.save() deploys the agent to your workspace and returns it with an ID. The agent uses the default LLM, and aix.Tool.get() loads the web search tool by its asset path.

tip

Outside a quick test, read the key from the AIXPLAIN_API_KEY environment variable and keep it out of source control. See API keys.

Check what the agent did

Every result records the models and tools the agent called, what the run cost and how long it took.

print(agent.id)
print([step["unit"]["name"] for step in result.data.steps])
print(result.status, result.used_credits, round(result.run_time, 1))

Show output

used_credits is the cost of the run in credits (1 credit = 1 USD). Use the agent ID to call the agent from the REST API or any other language.

Return JSON

Set output_format="json" and describe the shape in expected_output. A Pydantic model, a dict or a string all work.

from pydantic import BaseModel

class Review(BaseModel):
    name: str
    sentiment: str

extractor = aix.Agent(
    name="Review extractor",
    description="Extracts fields from customer reviews.",
    instructions="Extract the reviewer's name and the review sentiment.",
    output_format="json",
    expected_output=Review,
).save()

result = extractor.run("Review: Onboarding was smooth and support was great. Dana")
print(result.data.output)

Show output

result.data.output is a JSON string. Parse it with json.loads() or Review.model_validate_json().

Troubleshooting

Symptom	Cause	Fix
err.name_already_exists on save()	An agent with that name already exists in your workspace	Rename the agent, or delete the old one first
APIError: Forbidden resource	The API key is missing, mistyped or revoked	Copy the key again from the aixplain app
The answer does not use the web	The agent decided the tool was not needed	Check result.data.steps, and say when to search in instructions

Clean up

Saved agents stay in your workspace until you delete them.

agent.delete()
extractor.delete()

Next steps

• Agents: add tools, pin the model and set run parameters.
• Tools: give your agent code execution, databases and connected apps.
• Sessions and memory: keep context across turns.
• Deployment: run your agent in the cloud or on-prem.