Running Agents

Agents are executed using the .run() method. This method initiates the agent’s reasoning loop, optionally uses tools, and returns a structured or natural language response. Input can range from simple text queries to multi-turn conversations, contextual documents, variables, or file references.

The response includes the generated output, along with metadata such as session information, intermediate reasoning steps, execution statistics, and credit usage. This guide explains how to use the run() method effectively for different types of input and how to interpret the agent’s response.

---

Providing input to agents

The run() method accepts a variety of inputs depending on the task. You can combine a plain query with context, memory, or variables using the content, session_id, and history fields.

Simple input

Pass a static string as the query:

response = agent.run(query="What is the capital of France?")

---

Multi-turn conversations

Use a session_id to maintain memory between calls. The session lasts 15 days unless reused.

session = response.data.session_id
response = agent.run(query="What is the capital of France?", session_id=session)

Alternatively, use history to provide prior messages directly:

history = [
  { "role": "user", "content": "My name is Alex." },
  { "role": "assistant", "content": "Hi Alex! How can I help you?" }
]

response = agent.run(query="What’s my name?", history=history)

If both session_id and history are provided, history takes precedence and overrides the session context.

---

Contextual input

Use content to pass additional information the agent can use to answer:

response = agent.run(
    query="Summarize this article.",
    content=["First page...", "Second page..."]
)

You can also pass reasoning hints:

response = agent.run(
    query="Solve this math problem",
    content=["Show your work", "Break it down step by step"]
)

---

Files and paths

To process audio, images, or other files, pass paths or public URLs in content:

response = agent.run(
    query="Translate this audio file to English:",
    content=["DiscoveraiXplain.mp3", "https://aixplain.com/studio/"]
)

File type support depends on the tools and models your agent is using. Test with your specific configuration.

---

Structured variables

To provide named values (e.g., for prompt templates), pass a dictionary in content:

response = agent.run(
    query="Generate a personalized greeting for {{name}} at {{time_of_day}}.",
    content={"name": "Alice", "time_of_day": "morning"}
)

You can also combine variables with unstructured context:

response = agent.run(
    query="What should {{user}} focus on?",
    content=[
        {"user": "Alice"},
        "Previous performance review: Excellent coding skills",
        "Areas for growth: Project management"
    ]
)

---

Unified input

To pass everything in a single dictionary, use the data argument:

response = agent.run(
    data={
        "query": "Translate this text.",
        "session_id": session,
        "content": ["Hola, ¿cómo estás?"]
    }
)

---

Understanding agent responses

Calling run() returns an AgentResponse object with structured fields:

response = agent.run("What's an agent? Respond in English and French")
print(response)

Example output:

AgentResponse(
  status=SUCCESS,
  data=AgentResponseData(
    input={...},
    output="An agent is... / En français : Un agent est...",
    session_id="...",
    intermediate_steps=[...],
    execution_stats={...}
  ),
  completed=True,
  used_credits=...,
  run_time=...
)

Key response fields

• output: Final agent answer
• session_id: ID used for multi-turn conversations
• intermediate_steps: Log of tool calls and LLM decisions
• execution_stats: Runtime, API calls, credit cost, and tools used
• completed: Whether the execution finished successfully
• used_credits: Credit cost for the run
• run_time: Total execution time in seconds

See tracing and debugging guide →

---

Best practices

• Use clear and consistent variable names (e.g., user_name, not user name)
• Avoid unnecessary nesting in content
• Limit content size for performance-sensitive tasks
• Track session_id to preserve context in chat-like interactions

Choose the right input method

Scenario	Recommended input method
One-off queries	query="..."
Multi-turn conversation	Use session_id
Supplying documents or files	Use content=[...]
Dynamic variables	Use content={...}
Mixed context and variables	Use content=[{}, "..."]
Full control	Use data={...}

Optimize content

• Use lists to provide multi-part background or reference material
• Use dictionaries for structured variables (e.g., {"user": "John"})
• Mix both in a single list to combine structure and unstructured context