agents.research.person.agent

Person research agent for comprehensive person information gathering.

This module implements a sophisticated person research agent that combines web search, structured extraction, and iterative refinement to gather comprehensive information about individuals. The agent is particularly useful for research tasks requiring detailed personal profiles, biographical information, or professional backgrounds.

The agent workflow includes: 1. Query generation based on the target person and desired information schema 2. Web search execution using multiple search engines (Tavily integration) 3. Information extraction and note-taking from search results 4. Structured data extraction according to user-defined schemas 5. Reflection and completeness assessment 6. Iterative refinement until information quality meets requirements

Key Features: - Configurable extraction schemas for different research needs - Multi-source web search with relevance ranking - Iterative research process with reflection and self-correction - Structured output generation with validation - Source attribution and credibility assessment - Rate limiting and API quota management

Usage:
from haive.agents.research.person import PersonResearchAgent, PersonResearchAgentConfig

# Configure the agent
config = PersonResearchAgentConfig(
name="person_researcher",
target_person="Dr. Jane Smith",
extraction_schema={
"name": "Full name",
"profession": "Current profession or role",
"education": "Educational background",
"achievements": "Notable achievements or awards"
}
)

# Create and run the agent
agent = PersonResearchAgent(config)
result = await agent.ainvoke({
"person": "Dr. Jane Smith, AI researcher",
"research_depth": "comprehensive"
})

print(result.extracted_info)

The agent integrates with external services (Tavily) for web search and requires appropriate API keys to function fully. It includes comprehensive error handling and graceful degradation when external services are unavailable.

Classes

PersonResearchAgent

Advanced person research agent with iterative information gathering capabilities.

Module Contents

class agents.research.person.agent.PersonResearchAgent(config)

Bases: haive.core.engine.agent.agent.Agent[haive.agents.research.person.config.PersonResearchAgentConfig]

Advanced person research agent with iterative information gathering capabilities.

This agent implements a sophisticated research workflow that systematically gathers, processes, and structures information about individuals using web search, content extraction, and iterative refinement techniques.

The agent follows a multi-stage research process: 1. Query Generation: Creates targeted search queries based on the person

and desired information schema

  1. Web Search: Executes searches using the Tavily API for high-quality results

  2. Content Extraction: Processes search results and extracts relevant notes

  3. Structured Extraction: Converts notes into structured data following user-defined schemas

  4. Reflection: Evaluates information completeness and quality

  5. Iteration: Repeats the process with refined queries until satisfactory results are achieved or maximum iterations are reached

The agent is designed to be highly configurable and can adapt to different research requirements by modifying the extraction schema, search parameters, and quality thresholds.

tavily_client

Optional Tavily API client for web searches.

state_schema

Pydantic model defining the agent’s internal state.

input_schema

Pydantic model defining expected input format.

output_schema

Pydantic model defining output format.

Example

>>> config = PersonResearchAgentConfig(
...     name="researcher",
...     extraction_schema={"name": "Full name", "role": "Current position"}
... )
>>> agent = PersonResearchAgent(config)
>>> result = await agent.ainvoke({"person": "John Doe"})

Initialize the person research agent with configuration and external services.

Sets up the agent with the provided configuration, initializes the Tavily web search client if available, and prepares the agent for research operations.

Parameters:

config (haive.agents.research.person.config.PersonResearchAgentConfig) – Configuration object containing agent settings, API keys, extraction schemas, and operational parameters.

Raises:

  • ValueError – If required configuration parameters are missing.

  • ConnectionError – If external service initialization fails.

Note

The Tavily client is optional - the agent will log a warning and continue with limited functionality if the API key is not available.

gather_notes_extract_schema(state)

Gather notes from the web search and extract the schema fields.

Parameters:

state (haive.agents.research.person.state.PersonResearchState) – Current state

Returns:

Dict with info field

Return type:

dict[str, Any]

generate_queries(state, config)

Generate search queries based on the user input and extraction schema.

Parameters:

  • state (haive.agents.research.person.state.PersonResearchState) – Current state

  • config (langchain_core.runnables.RunnableConfig) – Runnable configuration

Returns:

Dict with search_queries field

Return type:

dict[str, Any]

reflection(state)

Reflect on the extracted information and generate search queries to find missing information.

Parameters:

state (haive.agents.research.person.state.PersonResearchState) – Current state

Returns:

Dict with is_satisfactory field and optionally search_queries

Return type:

dict[str, Any]

async research_person(state, config)

Execute a multi-step web search and information extraction process.

Parameters:

  • state (haive.agents.research.person.state.PersonResearchState) – Current state

  • config (langchain_core.runnables.RunnableConfig) – Runnable configuration

Returns:

Dict with completed_notes field

Return type:

dict[str, Any]

route_from_reflection(state, config)

Route the graph based on the reflection output.

Parameters:

  • state (haive.agents.research.person.state.PersonResearchState) – Current state

  • config (langchain_core.runnables.RunnableConfig) – Runnable configuration

Returns:

Next node to route to

Return type:

Literal[langgraph.graph.END, ‘research_person’]

setup_workflow()

Set up the workflow graph for this agent.

Return type:

None