Running Agents

The run method is used to execute queries once an agent has been created. Input is processed by the agent, and a structured response is returned.

Agent Input

Multiple methods for passing input are supported by the run method, depending on whether session history needs to be maintained, additional content needs to be appended, structured variables need to be provided, or file references need to be included. Input can be passed as a simple string, a list of contextual data, a dictionary of key-value pairs, or a combination of these. The query parameter is the only required field.

1. Query Only (No History Used)

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

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

2. Query + Session ID (For Multi-turn Conversations)

To maintain conversational history across multiple interactions, session_id should be included.

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

note

The agent must first be run without a session ID to generate one. The returned session ID can then be used in subsequent calls.

3. Query + Content (For Dynamic Input)

Additional information can be included with the query using content. This allows context, variables, or supplementary data to be provided for the agent.

Adding Context

A 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"]
)

Handling Files

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

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

Using 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"}
)

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"
    ]
)

4. Encapsulated Dictionary

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?"]
    }
)

Agent Response

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 Using

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
Single-turn queries	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 → Great for adding background context
• Dictionaries → Useful for replacing placeholders dynamically
• Mixing both → Ideal for structured and adaptive responses

Naming Variables

Keep variable names short yet meaningful (e.g., user, city, company) Avoid spaces in variable names (use user_name instead of user name)