AgentInput

Reference for the AgentInput object received by structured agent functions and Agent.call()

Overview

AgentInput is the input object your agent receives when using the Structured signature ((input_data: AgentInput) -> AgentResponse). It provides the conversation history, session context, and helper methods for accessing user messages.

When a test case has structured JSON input (e.g. {"user_message": "hello", "chat_type": "support"}), the SDK splits it: user_message becomes the message content, and the remaining fields (like chat_type) are placed in the first user message’s metadata.

Fields

messages · list[ConversationMessage] · required

The full conversation history up to this turn. Each ConversationMessage has:

• role (str): "user" or "assistant"
• content (str): The message text
• retrieval_context (Optional[str]): Retrieved context (for RAG agents)
• metadata (Optional[dict[str, Any]]): Additional fields. When the test case uses structured JSON input, non-message fields (e.g. chat_type, priority) appear here on the first user message.

session_id · str · required

The current session identifier. Use this to maintain state in stateful agents.

context_data · Optional[dict[str, Any]]

Structured context data from the test case. This comes from the test case’s context / context_data field, not from the input. Use it to pass supplemental information like customer tier, environment, or domain context.

metadata · Optional[dict[str, Any]]

Additional metadata for the current execution.

inference_result_id · Optional[str]

The inference result ID for this execution. Forward this to remote agents so they can attach traces to the correct session via set_context(inference_result_id=...). See Remote Agent Tracing.

Helper Methods

last_user_message_str() · Optional[str]

Returns the content of the last user message, or None if no user message exists. This is the simplest way to get the user’s message text.

last_user_message() · Optional[ConversationMessage]

Returns the full ConversationMessage object for the last user message (with role, content, retrieval_context, and metadata), or None if not found. Use this when you need access to the message’s metadata.

Basic Usage

def my_basic_agent(input_data: galtea.AgentInput) -> galtea.AgentResponse:
    # Get the last user message content
    user_message = input_data.last_user_message_str()

    # Access session and context
    session_id = input_data.session_id
    context = input_data.context_data  # e.g. {"customer_tier": "premium"}

    return galtea.AgentResponse(content=f"Response to: {user_message}")

Accessing Structured Input Fields

When your test case input is a JSON object (e.g. uploaded via CSV with {"user_message": "hello", "chat_type": "support"} in the input column), the SDK places user_message as the message content and remaining fields in messages[0].metadata:

def my_structured_agent(input_data: AgentInput) -> AgentResponse:
    # Get the last user message as a ConversationMessage object
    last_msg = input_data.last_user_message()
    if last_msg is None:
        return AgentResponse(content="No user message received.")

    # The message content (the user_message field from structured input)
    user_message = last_msg.content  # e.g. "hello"

    # Structured fields from the test case are in the first user message's metadata
    first_user_msg = input_data.messages[0] if input_data.messages else None
    if first_user_msg and first_user_msg.metadata:
        chat_type = first_user_msg.metadata.get("chat_type")  # e.g. "support"
        priority = first_user_msg.metadata.get("priority")  # e.g. "high"
    else:
        chat_type = None
        priority = None

    # Use structured fields to customize behavior
    if chat_type == "support":
        response = f"Support response (priority={priority}): {user_message}"
    else:
        response = f"General response: {user_message}"

    return AgentResponse(content=response)

Accessing Context Data

context_data is separate from the input. It comes from the test case’s context field and is useful for passing supplemental information that is not part of the user message:

def my_context_agent(input_data: AgentInput) -> AgentResponse:
    user_message = input_data.last_user_message_str()

    # context_data comes from the test case's context field
    if input_data.context_data:
        customer_tier = input_data.context_data.get("customer_tier", "standard")
    else:
        customer_tier = "standard"

    return AgentResponse(content=f"[{customer_tier}] Response to: {user_message}")

Structured Input on TestCase and InferenceResult

Outside of AgentInput, the TestCase and InferenceResult models provide two fields for accessing input:

• .input (str): The user_message value as a plain string
• .input_data (dict): The full structured input object with all fields

InferenceResult also provides a symmetric pair for the agent output:

• .actual_output (str | None): The scored output as a plain string. For voice turns this is the assistant_message transcript unwrapped from the content-parts envelope.
• .actual_output_data (dict | None): The full output envelope when present (e.g. {"assistant_message": "...", "content": [{"type": "audio", "uri": "...", "transcript": "..."}]}), otherwise None for plain-text output.

When submitting an actualOutput content-parts envelope, each audio part must include either a non-empty transcript or a non-empty uri. If you provide only a uri, the API transcribes the stored audio automatically and fills in the transcript. A client-supplied transcript or assistant_message always takes precedence over the API’s speech-to-text result. The strict transcript requirement applies only to the user turn (input) — the agent output side accepts audio-only parts.

# After running generate() or in a test loop, access the full structured input:
galtea_client = Galtea(api_key="YOUR_API_KEY")
test_case = galtea_client.test_cases.get(test_case_id=test_case_id)

# .input gives the user_message as a plain string
print(test_case.input)  # "hello"

# .input_data gives the full structured dict
print(test_case.input_data)  # {"user_message": "hello", "chat_type": "support"}

# Same pattern for inference results (input side):
inference_result = galtea_client.inference_results.get(inference_result_id=inference_result_id)
print(inference_result.input)  # "hello"
print(inference_result.input_data)  # {"user_message": "hello", "chat_type": "support"}

# Output side — symmetric pair:
print(inference_result.actual_output)  # "the answer is 42" (plain string for text; transcript for voice)
print(
    inference_result.actual_output_data
)  # None for plain text; {"assistant_message": "...", "content": [...]} for voice

How Structured Input Flows Through the System

1. Test case CSV: You provide JSON in the input column: {"user_message": "hello", "chat_type": "support"}
2. TestCase model: .input = "hello", .input_data = {"user_message": "hello", "chat_type": "support"}
3. Endpoint templates: Use {{ input.user_message }} or {{ input.chat_type }} to access individual fields, or {{ input }} for the full message
4. AgentInput (SDK): messages[0].content = "hello", messages[0].metadata = {"chat_type": "support"}
5. InferenceResult: .input = "hello", .input_data = {"user_message": "hello", "chat_type": "support"}

Related

Simulating Conversations

Multi-turn conversation simulation tutorial.

Generate Inference Result

Single-turn agent execution with automatic trace collection.

Templates & Mapping

Endpoint template syntax including {{ input.field_name }}.

Tracing Agent Operations

Capture internal operations and forward inference_result_id to remote agents.