Running agents

Once you've created an agent, the run method is used to send input and receive a structured response. It supports a variety of input types—ranging from simple text prompts to multi-turn conversations, contextual documents, dynamic variables, and file references. The response includes not only the generated output, but also metadata like session info, intermediate steps, execution stats, and credits used. Whether you're prototyping or scaling to production, this guide walks you through how to interact with your agents effectively.

Providing input to agents

The run method accepts different input types depending on the use case. Here's how to pass context, variables, files, or maintain session state. The 'query' parameter represents the user’s input. It can be combined with optional context, session history, or structured variables using the content, session_id, and history fields.

For simple input

A static string is sent as query without maintaining session history.

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

For multi-turn conversations

To maintain conversational history across interactions, include a session_id. This allows the agent to retain memory and context across turns. Session data is stored for 15 days and expires automatically unless reused.

Start by running the agent without a session ID to generate one. You can then pass that session_id in future calls to continue the conversation seamlessly.

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

Alternatively, use history to manually pass prior messages, following the OpenAI message format.

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

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

response.data.output

# Expected: "Your name is Alex."

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

For dynamic context

A content list can be used to append supplementary data to the query, such as reference documents. The items in the list are appended to the query and sent to the LLM for processing.

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

# Example: Step-by-step reasoning (Chain of Thought)
response = agent.run(
    query="Solve this math problem",
    content=["Show your work", "Break it down step by step"]
)

For handling files and path

For queries involving files, such as audio or images, content should contain file paths or public URLs.

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

note

File format support depends on the capabilities of the underlying LLM and tools used by the agent. Not all models support all file types. Always test with your specific agent configuration.

For inserting variables

For structured key-value inputs (e.g., replacing placeholders in prompts), a dictionary should be used. This is useful for template-based prompt engineering.

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

Example: Combining context and variables Variables can be mixed with contextual information.

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

For complex input

If all inputs (query, session history, and content) need to be passed as a single dictionary, this approach should be used.

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

Understanding agent responses

When the agent is run using the run method, an instance of AgentResponse is returned. This object contains structured data, including input, output, session details, and execution metadata.

Example Usage

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

Show output

Key attributes in AgentResponse

• status - Indicates whether the execution was successful (SUCCESS) or failed.
• data.input - The original query input, including chat history and output format.
• data.output - The final response generated by the agent, including translations if applicable.
• data.session_id - Unique identifier for the agent's session.
• data.intermediate_steps - A breakdown of steps the agent took, including how it processed the request.
• data.execution_stats - Metadata on runtime, API calls, credits consumed, and assets used.
• completed - Boolean flag indicating whether the agent execution was successfully completed.
• used_credits - Amount of credits consumed during the request.
• run_time - Total execution time of the agent in seconds.

Best practices for running agents

Here are some tips to ensure you're getting the most out of the run method:

Choosing the right input method

The table below outlines the appropriate input method based on different use cases.

Scenario	Recommended Input Method
Queries without session	Use a string input (query="...")
Maintaining session context	Include a session_id
Providing external data, or files (audio, images, etc.)	Use content=[]
Injecting variables dynamically	Use content={}
Combining structured variables and context	Use content=[{}, "..."]
Encapsulating all parameters	Use the dictionary method (data={})

Optimizing content

• Lists – Best for adding contextual background or multi-part prompts
• Dictionaries – Use for structured inputs or prompt variables
• Mixing both – Enables rich, contextual, and dynamic inputs

Naming variables

Use short, clear keys like user, product, or goal. Avoid spaces—use user_name instead of user name.

Next

You are ready now to combine your single-task agents to make more complex systems. Learn how to build team agents →