Skip to main content
Core types used throughout the HUD SDK.

​
Trace

Returned by agent.run(). Contains the result of an agent execution. 
from hud.types import Trace
FieldTypeDescription
rewardfloatEvaluation score (0.0-1.0)
doneboolWhether execution completed
contentstr | NoneFinal response content
isErrorboolWhether an error occurred
infodict[str, Any]Additional metadata
taskTask | NoneThe executed task
tracelist[TraceStep]Execution trace steps
messageslist[Any]Final conversation state

​
AgentResponse

Returned by agent get_response() methods. Represents a single model response. 
from hud.types import AgentResponse
FieldTypeDescription
tool_callslist[MCPToolCall]Tools to execute
doneboolWhether agent should stop
contentstr | NoneResponse text
reasoningstr | NoneModel reasoning/thinking
infodict[str, Any]Provider-specific metadata
isErrorboolError flag

​
MCPToolCall

Represents a tool call to be executed. 
from hud.types import MCPToolCall
FieldTypeDescription
idstrUnique identifier (auto-generated if not provided)
namestrTool name
argumentsdict[str, Any]Tool arguments
Example: 
tool_call = MCPToolCall(
    name="playwright",
    arguments={"action": "click", "selector": "#submit"}
)

​
MCPToolResult

Result from executing a tool call. 
from hud.types import MCPToolResult
FieldTypeDescription
contentlist[ContentBlock]Result content blocks
structuredContentdict[str, Any] | NoneStructured result data
isErrorboolWhether the tool call failed

​
Task

Defines an agent task with prompt, environment config, and lifecycle tools. 
from hud.types import Task
FieldTypeDescription
promptstrInstruction for the agent
mcp_configdictEnvironment connection config
idstr | NoneUnique identifier (required for datasets)
system_promptstr | NoneCustom system prompt
setup_tooldict | list[dict] | NoneTool(s) to initialize state
evaluate_tooldict | list[dict] | NoneTool(s) to score performance
agent_configBaseAgentConfig | NoneTask-specific agent config
metadatadict | NoneAdditional task metadata
Example: 
task = Task(
    prompt="Navigate to example.com and click login",
    mcp_config={
        "hud": {
            "url": "https://mcp.hud.ai/v3/mcp",
            "headers": {
                "Authorization": "Bearer ${HUD_API_KEY}",
                "Mcp-Image": "hudpython/hud-remote-browser:latest"
            }
        }
    },
    setup_tool={"name": "playwright", "arguments": {"action": "navigate", "url": "https://example.com"}},
    evaluate_tool={"name": "evaluate", "arguments": {"name": "url_contains", "substring": "/login"}}
)

​
BaseAgentConfig

Standard agent configuration that tasks can override. 
from hud.types import BaseAgentConfig
FieldTypeDescriptionDefault
allowed_toolslist[str] | NoneTool patterns to exposeNone (all)
disallowed_toolslist[str] | NoneTool patterns to hideNone
system_promptstr | NoneCustom system promptNone
append_setup_outputboolInclude setup output in first turnTrue
initial_screenshotboolInclude screenshot in initial contextTrue
response_tool_namestr | NoneLifecycle tool for responsesNone

​
AgentType

Enum of supported agent types. 
from hud.types import AgentType
ValueAgent Class
AgentType.CLAUDEClaudeAgent
AgentType.OPENAIOpenAIAgent
AgentType.OPERATOROperatorAgent
AgentType.GEMINIGeminiAgent
AgentType.OPENAI_COMPATIBLEOpenAIChatAgent
Example: 
from hud.types import AgentType

agent_cls = AgentType.CLAUDE.cls  # Returns ClaudeAgent class
agent = agent_cls.create()

​
ContentBlock

MCP content block types (from mcp.types):
  • TextContent - Text content with text field
  • ImageContent - Image with data (base64) and mimeType
  • EmbeddedResource - Embedded resource reference

​
See Also