docs/agent-design.md

Agent Design: ResearchLink AI

Agent Responsibilities

Agent	Input	Output	Uses LLM?
IntakeAgent	raw dict	IngestionInput	No
SourceResolverAgent	IngestionInput	ResolvedSources	No
PDFExtractionAgent	ResolvedSources	PaperExtraction	No
MetadataAgent	IngestionInput + PaperExtraction	PaperMetadata	Yes
CitationVerificationAgent	PaperExtraction + bibtex	CitationReport	No
GitHubRepoAnalyzerAgent	github_url	RepoAnalysis	No
PaperDigestAgent	PaperMetadata + PaperExtraction	dict[str, str]	Yes
LiteratureReviewAgent	PaperMetadata + PaperExtraction	dict[str, str]	Yes
ConceptMapAgent	PaperMetadata + PaperExtraction	dict[str, str]	Yes
ImplementationLinkAgent	PaperMetadata + RepoAnalysis	dict[str, str]	Yes
ReproducibilityAgent	PaperMetadata + RepoAnalysis + Extraction	dict[str, str]	Yes
LimitationsAgent	PaperMetadata + PaperExtraction	dict[str, str]	Yes
TeachingPathAgent	PaperMetadata + PaperExtraction	dict[str, str]	Yes
LabsGeneratorAgent	PaperMetadata + PaperExtraction	dict[str, str]	Yes
ReviewerAgent	PaperMetadata + CitationReport + content	dict[str, str]	Yes
ExportAgent	All above	GenerationReport	No

Base Agent

All agents inherit from BaseAgent which provides:

• _call_llm(system, user) — standardised Anthropic API call
• log(message) — verbose-gated console logging
• warn(message) — always-visible warnings
• Settings injection via get_settings()

Failure Handling

Every agent catches exceptions internally and returns partial results with notes. The pipeline continues even if individual agents fail. All failures are collected in the GenerationReport.

LLM System Prompts

Each content-generating agent has a focused system prompt that:

1. States the agent's role
2. Mandates the label system ([paper-claim], [needs-verification], etc.)
3. Forbids inventing citations
4. Specifies output format