Build an AI Research Agent in Python: Tools, Tests and MCP

Build a small AI research agent in Python, then test what happens when its planner proposes the wrong action. This tutorial includes a downloadable standard-library runtime, an offline demonstration, and an optional local Ollama connection. It focuses on read-only research tools, citation provenance, execution limits, and explicit failure states.

An AI agent uses a model to choose actions, call tools, observe results, and continue toward a goal. The model proposes decisions; the surrounding software controls execution. A research agent should be able to read evidence and produce a briefing without gaining the ability to publish it.

The implementation below makes that boundary inspectable. The later sections explain where MCP fits, when a workflow is simpler, and what to evaluate before extending the example. Its tools use direct function calls; this download does not implement an MCP client or server.

Updated October 21, 2026. The downloadable runtime has automated checks whose results and source hash are published below. Those are controlled software tests using scripted planner decisions, not a benchmark of live AI models. The optional Ollama path has a mocked HTTP test; no live model quality, latency, or cost results are claimed. For model fundamentals, start with my introduction to AI and large language models. For deployment candidates, see the open-source and open-weight AI model comparison.

Quick start: run the Python research agent

You need Python 3.11 or later. The offline demonstration uses only the standard library, requires no account, and makes no network requests. It searches three small authored fixture notes rather than crawling the web.

1. Download the complete Python research-agent example and save it as research-agent.py.
2. Run the deterministic demonstration:

python research-agent.py --demo --output brief.json

The JSON output contains the terminal status, answer, citations, and execution trace. The demo is useful for inspecting the runtime before introducing model variability. Its scripted planner follows a fixed sequence; it is not itself an AI model.

For model-driven decisions, run Ollama locally, make a tool-capable model available, and replace YOUR_INSTALLED_MODEL with its local name:

python research-agent.py --model YOUR_INSTALLED_MODEL --output brief.json

This mode calls the local Ollama chat endpoint. Hardware needs and tool-calling quality depend on your chosen model. Consult Ollama’s tool-calling documentation for supported request and response structure. The example supplies tool schemas and returns tool observations to the conversation; it does not download a model for you.

The default research question is deliberately narrow: when should an agent use MCP? Start with this fixed task, inspect the trace, then adapt the notes and question to your own application.

Why AI agents and MCP matter in 2026

AI product development increasingly involves software that can do work across several systems. Google’s 2026 guide to production-ready AI agents discusses evaluation, interoperability, and operational readiness. That emphasis is useful: the hard question is how a tool-using application behaves after the first successful demonstration.

The connection layer is changing too. The official MCP documentation now describes the 2026-07-28 protocol architecture, including stateless requests. Tutorials recorded against older versions can teach good concepts while showing outdated setup mechanics.

For a developer, this makes agents a timely topic with durable lessons. A new model may improve planning, but an application still needs to handle failed requests, ambiguous instructions, expired access, and conflicting sources. Good engineering should make those situations visible and recoverable.

Three questions provide a useful starting point:

• Does the task actually require the system to choose its next action?
• Can success be checked independently of the final answer?
• Can the work stay inside a clear scope, cost limit, and permission boundary?

If those answers are unclear, improve the task definition before choosing a framework.

AI agents vs. chatbots, workflows, and RAG

These terms describe different aspects of a system. A conversational interface can sit on top of an agent. Retrieval can supply evidence inside a fixed workflow. A multi-agent application may still use deterministic code for its most consequential decisions.

The table below compares common designs. On a phone, scroll the table horizontally to read every column.

Design	Who chooses the next step?	Useful example	Main engineering concern
Single model call	Application code invokes one request	Rewrite a paragraph	Output quality and validation
RAG application	Code retrieves evidence before generation	Answer a documentation question	Retrieval quality and source fidelity
Fixed workflow	Code defines the sequence and branches	Extract, validate, and route a form	Correct transitions and exception handling
AI agent	Model proposes actions within runtime rules	Investigate an unfamiliar repository failure	Tool reliability, permissions, and stopping
Multi-agent system	Several agents coordinate or receive subtasks	Independent investigations with a combined report	Coordination cost and shared state

Anthropic’s building effective agents distinguishes predefined workflows from systems where models direct their own tool use. Its practical advice is to start with a simple solution and add complexity when the task warrants it. The article’s architecture discussion remains useful, although it explicitly notes that tooling has changed since its original publication.

When a workflow is the better choice

Suppose a submitted invoice always needs the same operations: extract fields, check a purchase order, calculate a discrepancy, and send the result to a review queue. Most of that process benefits from explicit code. A model can help interpret the document without controlling the entire business process.

Now consider a developer asking why a specific test fails only in one environment. The required investigation may depend on information discovered along the way. A bounded agent can choose whether to inspect configuration, read a dependency change, or reproduce the failure.

The right boundary often combines both designs: adaptive investigation inside a fixed process for approval and execution.

Where RAG fits

Retrieval-augmented generation supplies relevant external material to a model. An agent can decide when to search again or inspect another source, but retrieval alone does not make an application agentic. A simple documentation assistant may perform very well with one search followed by one grounded answer.

Before adding a planning loop, measure whether users actually need it. If the same retrieval path answers most questions correctly, a larger orchestration layer may add latency without improving the outcome.

If you are deciding whether the next improvement belongs in retrieval or training, my RAG vs fine-tuning guide walks through that diagnosis with a support-assistant example and an evaluation worksheet.

How an AI agent works: the complete runtime loop

Think of the runtime as the machinery around the model. It carries a task forward, records what happened, and decides which proposed actions may execute.

An illustrative run follows this sequence:

1. Define the goal. Record the requested result, allowed sources, and completion criteria.
2. Assemble context. Supply relevant instructions, evidence, tool descriptions, and task state.
3. Request a decision. The model proposes an answer, a tool call, or a need for clarification.
4. Validate the proposal. Check arguments, access, limits, and whether approval is required.
5. Execute allowed work. The application calls a tool and records its result.
6. Check progress. Compare new evidence against the goal and update explicit state.
7. Stop or continue. Finish with evidence, request help, or take another bounded step.

The arrows in the cover diagram represent this feedback loop. A model proposing an action is different from the runtime executing it. That separation lets an application reject an invalid argument or pause a consequential action even when the model sounds confident.

Keep task state explicit

A conversation transcript is useful history, but it is a poor substitute for a structured task record. For a research assistant, store selected sources, unresolved questions, fetched revisions, and approval status separately. For a coding agent, track the intended change, affected files, checks run, and check results.

This also improves recovery. After a worker restarts, the system should know whether a draft was saved or whether an operation was merely proposed. An eloquent message claiming completion is insufficient evidence that an external system changed.

Design tools around clear work

A tool named do_everything leaves too much interpretation to the model. A focused tool such as search_published_articles can specify its inputs, filters, output fields, and errors. Distinguish read operations from operations that change state.

Anthropic’s tool-design guidance emphasizes clear interfaces and evaluating tool use. Apply that idea by returning useful evidence: document identifiers, source URLs, timestamps, and explicit result status. Avoid returning thousands of irrelevant records when the next decision only needs a short list.

What is MCP, and what does it actually provide?

The official MCP introduction describes an open standard for connecting AI applications to external systems. In a typical arrangement, the host application uses MCP clients to communicate with servers exposing capabilities.

The current architecture documents three server primitives:

• Tools: callable operations, such as searching an index or looking up an issue.
• Resources: contextual data that an application can retrieve.
• Prompts: reusable interaction templates.

MCP makes those interfaces more consistent. Your application still decides which servers to trust, which capabilities to expose to a model, and which actions a particular user may perform.

MCP is not an agent framework or a security policy

Connecting an MCP server does not automatically provide planning, durable memory, trustworthy content, or business authorization. It also does not ensure that two clients support every capability in the same way.

For example, an agent may discover a tool that creates a calendar event. The runtime still needs to check whose calendar is involved, whether the user approved the details, and whether a retry would create a duplicate event. A standardized interface helps the call reach the service; application policy determines whether it should happen.

Version compatibility matters

In the 2026-07-28 architecture, requests carry protocol version and relevant capability metadata, and servers expose discovery. Earlier tutorials may describe connection initialization and session assumptions differently. Match the protocol version supported by your client, server, and SDK rather than copying setup from a video into an unrelated release.

Keep a small compatibility test: discover the intended tool, call it with a known input, validate its result, and verify the behavior when access is denied. Run that test when upgrading either side of an integration.

MCP vs. A2A

The Agent2Agent protocol documentation distinguishes connections to tools through MCP from communication between independent agentic applications through A2A. A2A supports discovery, delegated work, and result exchange across agent systems.

Most first projects do not need both. Use a normal function for a small internal helper, consider MCP for reusable external capabilities, and consider A2A when separate agent applications need an interoperable task interface. Choose a protocol to solve an integration problem you can describe.

Python implementation: tools, evidence, and execution limits

The downloadable research-agent runtime separates a planner from its tool executor. You can inspect every allowed operation and replace the planner without changing those boundaries.

Its built-in collection contains three short, authored notes with links to MCP, LangGraph, and Ollama documentation. They are teaching fixtures, not live search results or downloaded copies of those pages. This keeps the demonstration repeatable and makes its limitations easy to see.

Step 1: keep the research tools read-only

The runtime exposes two operations:

Tool	Input	Result	Permission boundary
search_documents	A nonempty query string	Matching note identifiers and titles	Searches the built-in collection only
read_document	A known note identifier	Note text and its official source URL	Records the document as loaded evidence

Searching for a title does not count as reading its contents. The runtime maintains the set of documents actually loaded through read_document; final citations must come from that set. An unknown tool or malformed arguments produces an explicit failure state before execution.

The command-line --output option saves the final JSON locally. It is a user-selected destination, not an agent-controlled publishing tool. The planner has no function for posting a blog article, sending a message, running a shell command, or fetching an arbitrary URL.

Step 2: inspect the planner boundary

The offline demonstration supplies scripted decisions to the same executor used by the optional local-model adapter. That lets tests deliberately request an unauthorized action or cite a document that has not been read.

With --model, the Ollama adapter translates model tool calls into runtime proposals and returns observations in subsequent chat messages. The model’s proposed arguments still pass through the runtime’s validation. A model response that sounds plausible does not skip those checks.

The separation is useful during development: if a scripted call fails, inspect the runtime or tool. If controlled cases pass but a model repeatedly chooses the wrong source, inspect model behavior, the tool descriptions, and the prompt.

Step 3: distinguish citation provenance from factual correctness

A provenance check answers a narrow question: did the final citation come from a document this run actually read? It cannot prove that the answer accurately represents that document. A model can read the right source and still misinterpret it.

For a real application, add claim-level review, freshness checks, and a way to surface conflicting evidence. Keep the underlying source text alongside any summary. Never treat a successful provenance check as a general truth or hallucination detector.

Step 4: bound the work and report failure

The runtime caps planner steps and sets deadlines for waiting on a planner or tool. A repeating plan therefore terminates with a limit status rather than continuing indefinitely. Tool and model failures also return explicit states; inspect the trace before treating an answer as complete.

These timeouts bound how long the runtime waits. They do not forcibly cancel arbitrary Python code that is already running. This is appropriate for the example’s read-only fixtures; a production worker needs isolation and cancellation appropriate to its tools.

The example does not implement durable restart recovery, a multi-user authorization service, or safe retries of external writes. If you add those capabilities, define their behavior and tests before giving the planner access to them.

Reproduce the research-agent tests

Download the Python unittest suite into a tests folder beside research-agent.py. Keep this layout:

research-agent.py
tests/
  test_research_agent.py

Run the suite with:

python -m unittest discover -s tests -p test_research_agent.py -v

Recorded verification: 2026-10-21. Python 3.11.0; 14 tests run, 0 failures, 0 errors. Live model calls: 0.

The machine-readable verification record includes the source SHA-256 hash and the executed test names. Compare that hash with your downloaded script to identify the version being discussed. The results apply to this fixture-backed runtime and its mocked adapter tests; they do not predict a model’s research quality.

The tests exercise successful evidence collection, denied tools, malformed arguments, citation provenance, execution limits, and failure handling. The injection-related check deliberately supplies a prohibited proposal after instruction-like source content. It tests the executor’s allowlist boundary, not whether a real model resists every prompt injection.

This gives you a baseline to extend. Replace the fixture collection with an approved source service, add representative questions, and record which claims reviewers accept. Then test a chosen model on those tasks repeatedly. Keep controlled runtime tests and model-quality evaluations as separate reports.

Connect the same tools through MCP

Keep the runtime’s validation and evidence accounting when changing the connection layer. An MCP-backed adapter can expose equivalent search and read operations while the host continues to enforce allowed actions and completion criteria.

The Python download intentionally uses direct function calls so the control flow is visible without installing another package. To build an actual MCP integration, use a current official MCP SDK and verify the protocol version supported by both ends. Test discovery, allowed calls, error results, and denied access before replacing the local functions.

The MCP security guidance describes integration risks such as local server compromise and authorization errors. Moving a function behind MCP changes how it is reached; it does not make an unsafe operation safe or grant permission to run it.

Choosing an AI agent framework

Pick a framework based on the execution problem. A large feature list cannot tell you whether your team will understand failures or operate the result comfortably.

Approach	Consider it when	Check before choosing
Direct model calls with application code	A small loop and a few tools are sufficient	State persistence, retries, validation, and tracing you must supply
LangGraph	Explicit state transitions and resumable work matter	Persistence setup, interrupt behavior, and deployment operations
Google ADK	You want an agent-development framework with tooling and workflow options	Language support, model integration, evaluation, and runtime requirements
Managed agent service	Your team wants a hosted execution environment	Permission model, supported tools, observability, retention, and exit path

LangGraph’s overview emphasizes durable execution, streaming, human oversight, and stateful orchestration. Google ADK’s current documentation covers agent development, graph and multi-agent workflows, evaluation, and deployment options. Consult those docs for current APIs; this table compares architectural fit rather than claiming one framework wins every benchmark.

Before adopting anything, build the same small task twice if the choice is expensive to reverse. Compare code clarity, failure recovery, and evaluation effort. A framework that makes the happy path short can still leave substantial operational work.

Should you start with multiple agents?

Begin with one agent unless you can name a concrete benefit from separation. Independent evidence gathering, different access boundaries, or specialist task contracts can justify several workers. Merely naming roles such as researcher, critic, and manager does not establish that they improve quality.

Coordination adds messages, duplicated context, synchronization, and partial failure. If three workers repeat the same mistaken assumption, agreement is weak evidence. Evaluate the final result and compare it with the simpler baseline using the same task set and resource limits.

Context engineering, memory, and long-running work

Context engineering is the practical work of deciding what the model needs for its next decision. Include the goal, relevant policies, current state, and the evidence needed now. Avoid treating a larger context window as an invitation to append every tool response forever.

Anthropic’s context-engineering article discusses managing a limited context budget, while its long-running agent harness guidance examines continuity across sessions. Both point toward a system-level problem: progress must survive beyond one model interaction.

Separate three forms of information:

• Working context: material needed for the next decision.
• Task state: durable facts about the current job and its progress.
• Long-term memory: selected information retained for future tasks under an explicit policy.

For the research example, keep fetched page text in an evidence store and retrieve relevant excerpts as needed. Preserve source identifiers when summarizing. Otherwise, a compacted note can turn an uncertain claim into an apparently established fact.

Long-term memory also needs deletion, access boundaries, and freshness rules. A preference the user once expressed may be stale; a previous permission may apply only to a specific action. Store those distinctions instead of converting everything into a permanent instruction.

How to evaluate AI agents before deployment

An agent evaluation should test outcomes and behavior under realistic conditions. A persuasive final message does not prove that a requested file exists, a service was updated, or the evidence supports a conclusion.

Anthropic’s guide to agent evaluations distinguishes tasks, repeated trials, graders, traces, and environment outcomes. It also describes code-based, model-based, and human grading. Use those distinctions to separate objective checks from judgments that need calibration.

For the research assistant, a starter evaluation matrix could look like this:

Test case	Expected outcome	Evidence to inspect
Ordinary comparison request	Complete briefing with supported claims	Draft, source records, and citations
Official pages conflict	Conflict reported without inventing a resolution	Both sources and uncertainty note
One source times out	Retry within limits or report missing evidence	Tool result and retry count
Retrieved page requests an unrelated action	Continue within the authorized scope	Proposed calls and policy decisions
Budget is exhausted	Save partial progress with explicit status	State record and final report
Worker restarts after a save	Resume without losing or duplicating work	Draft revision and task state

This is a proposed test design. Choose cases from your own workload and add failures discovered in real use.

Measure reliability across repeated runs

Use held-out tasks that were not used to tune the prompt. Repeat important cases because model behavior can vary. Report both the quality of outcomes and how consistently the system meets required constraints.

Track task completion, unsupported claims, unauthorized actions, tool errors, elapsed time, and total cost. Keep the model revision, prompts, tool versions, and environment settings with the results. A later run is difficult to interpret if several of those changed without a record.

Do not rely exclusively on another model as the judge. Use code to validate objective conditions, human review for important judgment calls, and calibrated model grading where it helps scale the process. Redact sensitive content before exporting traces.

Cost and latency: measure the whole task

An agent may invoke a model repeatedly, retrieve documents, execute tools, and request review. A low per-token price does not establish a low cost per successful task.

Use this accounting model:

Cost per successful task =
  total model, tool, infrastructure, and review cost
  divided by the number of tasks meeting acceptance criteria

For an illustrative calculation, suppose 100 attempted tasks cost $12 in combined model and tool charges, and 80 meet the acceptance criteria. That is $0.15 per successful task before infrastructure and human review. These numbers are hypothetical, not provider pricing or measured results.

Latency deserves the same discipline. Ten sequential tool calls cannot benefit from parallelism in the way ten independent searches can. Track time spent waiting for models, external services, approval, and retries. Report typical and slow-tail behavior rather than only the fastest demonstration.

Useful optimizations follow diagnosed causes: reduce irrelevant context, bound tool output size, cache stable information, parallelize independent reads, or route easy subtasks to a smaller model. Re-run evaluations after each change. A cheaper system that needs substantially more correction may cost more overall.

Deployment checklist for a reliable AI agent

Before broad access, establish a small pilot with a clear owner and a way to stop new work. Review the following against the actual application:

1. Task contract: users understand what the agent can complete and how it reports partial work.
2. Access control: tools enforce the authenticated user’s permissions and tenant boundaries.
3. Execution limits: timeouts, step limits, cost controls, and cancellation work in failure cases.
4. Write controls: consequential actions use the intended approval flow and protection against duplicates.
5. Recovery: state persists at meaningful checkpoints, and retries have defined behavior.
6. Evidence: completion can be checked in the resulting system or artifact.
7. Evaluation: representative tasks and important failure cases pass a documented release threshold.
8. Observability: operators can inspect tool failures and policy decisions without exposing secrets.
9. Data lifecycle: logs, artifacts, and memory have retention and deletion rules.
10. Rollback: model, prompt, and tool changes can be reversed when quality degrades.

These are engineering review points rather than a certification. A prototype that reads public documentation has different operational needs from a system that can update customer records. Expand its authority only when the added capability has a defined purpose and has been evaluated.

Books, videos, and official learning resources

Use the resources below to progress from concepts to implementation. Books provide deeper foundations; the linked documentation is the reference for current APIs and protocol details.

Books

Select Read More for a book summary, topics, recommended background, and an Author tab with biographical information. Buy opens the publisher’s page. Purchase, library, and subscription access vary.

Videos you can watch here

Select a play button to watch within this site. Start with the agent-design talks, then use the MCP introduction and workshop to explore tool integration. These talks were recorded against earlier tooling; use the current MCP documentation above when implementing protocol details.

Documentation and further reading

• MCP introduction: understand the protocol’s role before installing integrations.
• MCP architecture: check the current request model, discovery, and available primitives.
• MCP security best practices: review integration threats and server trust boundaries.
• LangGraph documentation: explore stateful orchestration and durable execution.
• Google ADK documentation: explore agent development, workflows, evaluation, and deployment.
• A2A protocol documentation: learn how independently built agent applications exchange work.
• Agent evaluation guide: plan repeatable tasks, graders, and outcome checks.

For a first project, choose one narrow task, a small toolset, and an outcome you can verify. Save the evidence from unsuccessful attempts as carefully as successful ones: it tells you whether to improve the model, the tools, or the surrounding workflow.

Frequently asked questions about AI agents

Can I run the research-agent example without a paid API?

Is the offline demonstration a real AI model benchmark?

Does this Python research agent require MCP or a vector database?

How does the agent check its citations?

What stops the agent from taking unsafe actions or running forever?