Showing posts with label Active Concepts. Show all posts

Saturday, November 14, 2026

AI Engineering Active Concepts #013 — RAG: How AI Answers Questions Using Your Documents

AIYING | AI ENGINEERING ACTIVE CONCEPTS #013

Retrieval-Augmented Generation (RAG): How AI Answers Questions Using Your Documents

Instead of expecting AI to know everything, give it a way to find relevant information before answering.

Understand → Connect → Apply → Accomplish

1. The Problem: AI Does Not Know Your Documents

Imagine an organization with hundreds of policy documents, technical manuals, project reports, and operating procedures.

An employee asks:

"What is our organization's current policy for approving AI-generated software code?"

A general-purpose language model may not have access to that organization's latest policy.

Even if the model knows common industry practices, that knowledge is not a substitute for the organization's actual approved document.

This creates an important engineering challenge:

How can an AI system answer questions using information it was not specifically trained on?

2. The Active Concept: Retrieval-Augmented Generation

Retrieval-Augmented Generation, commonly called RAG, is an approach that combines information retrieval with language-model generation.

A typical RAG application first searches an external knowledge source for information relevant to the user's question.

It then provides the retrieved information to a language model as context for generating a response.

QUESTION → RETRIEVE → AUGMENT → GENERATE → VERIFY

Verification is shown here as an important application-level engineering step. It is not automatically guaranteed by RAG.

The essential idea is simple:

Do not rely only on what the model learned. Retrieve what the application needs to know.

3. How a Typical RAG System Works

Step 1 — Prepare the knowledge source

Documents are collected, extracted, cleaned, and organized.

Long documents may be divided into smaller passages called chunks.

Step 2 — Index the content

A common approach converts document chunks into numerical representations called embeddings.

These can be stored in a vector index for similarity-based retrieval.

Other implementations use keyword search, metadata filtering, or hybrid retrieval.

Step 3 — Receive the question

A user submits a question. The system prepares it for retrieval.

Step 4 — Retrieve relevant passages

The retrieval component identifies candidate passages related to the question.

Some systems also rerank results to improve relevance.

Step 5 — Generate a grounded response

The application supplies selected passages along with instructions and the user's question to a language model.

The model generates an answer using the supplied context.

Step 6 — Evaluate the answer

A well-designed application checks whether the answer is supported by the retrieved evidence.

It may provide citations, acknowledge missing information, or request clarification.

4. Connect RAG to Other AI Engineering Concepts

Concept	Connection to RAG
Tokens	Retrieved passages consume context-window capacity.
Embeddings	Support semantic retrieval in many RAG architectures.
Tool Calling	Can let an application invoke retrieval tools dynamically.
MCP	Can expose external resources and retrieval tools through standardized integrations.
Evaluation	Measures retrieval relevance, answer correctness, and evidence support.
Observability	Helps trace retrieved passages, model calls, latency, and failures.

5. Try It Yourself — Make a Document Answer Questions

You can explore document-grounded question answering without writing code.

Open Google NotebookLM .

NotebookLM supports source-grounded exploration of uploaded or connected material. It is useful for demonstrating the general idea of retrieval-grounded answering, although its internal implementation should not be assumed to match every RAG architecture.

Step 1 — Create a fictional policy document

Create a short document with the following fictional policy:

Sample AI Code Review Policy

All AI-generated production code must undergo human review before deployment.

Security-sensitive changes require approval from the designated security reviewer.

Automated tests must pass before release.

The engineering lead is responsible for recording the final deployment approval.

This is a fictional learning example, not an actual organizational policy.

Step 2 — Add the document

Create a notebook and add the fictional policy as a source, using an available supported source-upload method.

Step 3 — Ask a question

Who must review AI-generated production code before deployment?

Compare the answer with the original document. Inspect any available source citations.

Step 4 — Ask a question with no answer

What is the maximum permitted deployment budget for AI-generated code?

The fictional policy does not specify a budget.

A well-grounded answer should acknowledge that the source does not provide this information, rather than inventing a number.

Step 5 — Ask for supporting evidence

Answer using only the supplied policy. Identify the supporting passage. If the information is absent, state that it is not specified.

Check whether the response matches the actual source text.

6. What Should an AI Engineer Evaluate?

A functioning RAG demonstration is not automatically a reliable production system.

Engineers should evaluate several dimensions:

Retrieval relevance: Were the right passages found?
Answer correctness: Does the response answer the question accurately?
Groundedness: Are the claims supported by the supplied sources?
Abstention: Does the system acknowledge missing evidence?
Access control: Can users retrieve only authorized information?
Latency and cost: Can the application meet operational requirements?

RAG can reduce some unsupported responses by supplying relevant evidence. It does not eliminate hallucinations.

Retrieved documents can also contain incorrect, outdated, sensitive, or malicious instructions. They must be handled as lower-trust content.

7. A Practical Engineering Decision

When should an application consider RAG?

RAG is particularly useful when answers depend on information that changes, is organization-specific, or must be traceable to external sources.

Examples include:

Internal knowledge assistants
Technical documentation search
Customer support knowledge systems
Policy and procedure question answering
Research assistants using selected sources

However, RAG is not always necessary.

Simple deterministic lookups may be better handled through direct database queries or APIs. Tasks requiring exact calculations may need specialized tools.

The engineering question is not "Can we use RAG?"

It is: "Does retrieval improve the reliability, relevance, and maintainability of this application?"

8. Today's Accomplishment

Complete this small experiment:

Create one fictional source document.
Ask two questions supported by the document.
Ask one question the document cannot answer.
Check the answers against the original source.
Record one strength and one limitation.

You will have explored the difference between generating an answer from general model capabilities and answering with specific external evidence.

The Bigger Insight

A useful AI system does not need to know everything. It needs a reliable way to find, use, and verify what matters.

RAG shifts part of the engineering challenge from storing knowledge in model parameters to designing reliable access to external knowledge.

That shift makes retrieval quality, source governance, evaluation, and system design central to the AI engineer's work.

Friday, November 13, 2026

AI Engineering Active Concepts #012 — Observability and Tracing: Understanding What AI Systems Actually Do

AI ENGINEERING — ACTIVE CONCEPTS & PRACTICES | #012

Observability and Tracing: Understanding What AI Systems Actually Do

Chapter 2: Engineering AI Applications and Agents

AIYING — Accomplishing with AI

The Big Idea: Observability makes the internal behavior of AI applications understandable through telemetry such as traces, metrics, logs, and execution events.

Tracing reveals how individual steps contribute to an end-to-end AI workflow.

Engineering question: How can engineers diagnose failures, understand costs, and improve reliability when AI systems involve multiple model calls, retrieval operations, tools, and decisions?

Why Observability Matters
UNDERSTAND — The Concept
CONNECT — AI Engineering Relationships
Observability Architecture
APPLY — Enterprise Procurement Agent
Worked Example: Diagnosing Slow Execution
Engineering Decisions and Trade-offs
Active Industry Practices
ACCOMPLISH — Practical Exercise
Student and Practitioner Project
Check Your Understanding
Active Connections
References and Further Reading

1. Why Observability Matters

Imagine an enterprise AI agent that retrieves purchase orders, checks inventory, recommends recovery actions, and prepares approval requests.

Yesterday, the workflow completed in 12 seconds. Today, the same type of request takes 45 seconds.

The final answer still looks correct.

Without execution telemetry, the engineering team cannot determine whether the delay came from retrieval, model inference, tool execution, retries, or external systems.

Observability makes these internal operations visible.

An AI system that cannot be observed is difficult to diagnose, improve, and operate reliably.

2. UNDERSTAND — The Concept

What is observability?

Observability is the ability to understand the internal state and behavior of a system using information it emits during operation.

In AI engineering, this includes model calls, prompts and responses where permitted, retrieval operations, tool invocations, workflow transitions, latency, errors, and resource consumption.

Three foundational telemetry signals

Signal	What It Reveals	Example
Traces	How a request progresses across operations	Model → Retrieval → Tool → Response
Metrics	Aggregated quantitative behavior	Latency, error rate, token usage
Logs	Recorded events and diagnostic details	Tool timeout, validation failure

What is tracing?

A trace represents the execution path of an operation across components.

Individual operations are often represented as spans.

Each span may record its name, start time, duration, status, attributes, and relationship to other spans.

Example trace

Trace: Procurement Request
|
+-- Span 1: Parse Request
|
+-- Span 2: Retrieve Purchase Order
|
+-- Span 3: Check Inventory
|
+-- Span 4: Generate Recommendation
|
+-- Span 5: Validate Recommendation
|
+-- Span 6: Prepare Approval Request

Tracing helps engineers understand which operations occurred, their order, and where time or failures accumulated.

Observability versus evaluation

Observability: What happened during execution?

Evaluation: Did the system perform correctly against defined criteria?

Observability supplies evidence that evaluation can use, but traces alone do not establish whether a result was correct.

3. CONNECT — AI Engineering Relationships

Concept	Connection to Observability
Context Engineering	Tracks context assembly and token usage
Retrieval Engineering	Measures retrieval latency and failures
Structured Outputs	Records validation failures
Tool Calling	Tracks tool requests, results, and errors
MCP	Monitors interactions with external servers
Agent Orchestration	Tracks workflow steps and state transitions
Agent Evaluation	Uses traces as evidence for quality assessment
Token Economics	Measures token consumption and estimated cost
AI Governance	Supports auditability and accountability

Active connection: Observability connects AI development, testing, operations, and governance through recorded evidence of system behavior.

4. Observability Architecture

User Request

↓

AI Application / Agent

↓

Instrumented Model, Retrieval, and Tool Operations

↓

Telemetry Collection

↓

Traces + Metrics + Logs

↓

Monitoring, Analysis, and Alerts

↓

Diagnosis, Evaluation, and Improvement

Instrumentation

Instrumentation adds the mechanisms that generate telemetry from application operations.

Trace correlation

Related spans share trace identifiers so that operations across services can be analyzed together.

Metrics collection

Systems aggregate measurements such as request counts, latency distributions, error rates, and token consumption.

Logging

Structured logs capture relevant events, errors, and operational details.

Dashboards and alerts

Dashboards display trends, while alerts notify operators when defined thresholds or conditions are met.

Security and privacy

Observability systems must avoid unnecessary exposure of sensitive prompts, personal information, credentials, and confidential tool results.

5. APPLY — Enterprise Procurement Agent

Scenario: A Slow Procurement Workflow

A procurement AI agent performs the following operations:

Interprets the user request.
Retrieves purchase-order information.
Checks inventory.
Generates a recovery recommendation.
Validates the recommendation.
Prepares an approval request.

The workflow is taking substantially longer than expected.

What should engineers inspect?

Component	Observable Signal
Model inference	Latency, token usage, errors
Retrieval	Query duration, result count, failures
Inventory API	Response time, timeout rate, retries
Workflow controller	Step count, state transitions, loops
Validation	Schema and business-rule failures
Approval service	Request creation and delivery status

With distributed tracing, engineers can identify which operation is contributing most to latency.

With metrics, they can determine whether the problem affects one request or a larger population.

With logs, they can investigate specific error events.

6. Worked Example: Diagnosing Slow Execution

Consider the following fictional trace of a sequential AI workflow.

Operation	Duration
Request interpretation	2 seconds
Purchase-order retrieval	3 seconds
Inventory API call	25 seconds
Recommendation generation	10 seconds
Validation and response	5 seconds
Total	45 seconds

Latency contribution

Inventory API contribution =
25 / 45 × 100
= 55.6%

In this example, the inventory API accounts for approximately 56% of total execution time.

What should the engineer investigate?

Is the inventory service responding slowly?
Did the application retry the request?
Was there a network timeout?
Was the query unusually expensive?
Is the latency problem persistent or isolated?

The trace identifies where time was spent, but additional evidence is needed to establish the underlying cause.

Example structured trace record

{
  "trace_id": "trace-1048",
  "span_name": "inventory_lookup",
  "duration_ms": 25000,
  "status": "ok",
  "retry_count": 2,
  "service": "inventory-api",
  "workflow_id": "WF-1048"
}

This is an illustrative application record, not a complete OpenTelemetry span representation.

Engineering interpretation

The engineer now has evidence that the inventory lookup experienced retries and substantial latency.

The next step is to inspect the underlying API and retry policy rather than blindly changing the model or prompt.

7. Engineering Decisions and Trade-offs

Decision	Benefit	Trade-off
Detailed tracing	Better diagnosis	Storage and processing overhead
Full prompt logging	Detailed debugging context	Privacy and confidentiality risks
Sampling	Reduced telemetry cost	Some traces may be unavailable
Real-time alerts	Faster incident response	False positives and alert fatigue
Token-level metrics	Better cost analysis	Instrumentation complexity
Long retention	Historical analysis	Storage and data governance burden

Common observability mistakes

Recording only final responses
Failing to correlate tool calls with workflow traces
Ignoring retry behavior
Logging sensitive information unnecessarily
Measuring averages without latency distributions
Collecting telemetry without actionable dashboards
Confusing operational success with answer correctness

Recommended engineering practices

Instrument important workflow boundaries.
Use consistent trace and span identifiers.
Record model, retrieval, and tool latency.
Capture token usage and estimated costs.
Record relevant workflow state transitions.
Use structured logs.
Protect sensitive telemetry.
Monitor error rates and latency percentiles.
Connect traces with evaluation results.
Define operational alerts and incident procedures.

Good observability collects the information engineers need to explain behavior and make decisions—not simply the largest possible volume of logs.

8. Active Industry Practices

Established foundations

Distributed tracing
Structured logging
Metrics and dashboards
Latency and error monitoring
Alerting and incident investigation
Trace correlation across services

AI-specific practices

Model-call tracing
Token and cost tracking
Retrieval and tool-call instrumentation
Agent execution trajectory tracing
Prompt and response metadata tracking
Evaluation-linked traces
Privacy-aware telemetry collection

Relevant technologies

Engineering teams may use OpenTelemetry, Jaeger, Grafana, LangSmith, MLflow, or other observability platforms according to application requirements.

OpenTelemetry provides vendor-neutral instrumentation concepts and conventions, while specialized AI observability platforms add workflow-oriented capabilities.

Specific generative AI semantic conventions and tooling support can vary by implementation and version.

Industry applications

Observability is important for production AI agents, RAG applications, enterprise assistants, AI-enabled software systems, workflow automation, and operational AI platforms.

Practice status: Established software observability discipline extended to generative AI and agentic systems.

Reviewed: November 2026.

9. ACCOMPLISH — Practical Exercise

Exercise: Diagnose an AI Workflow

Consider the following fictional telemetry:

Workflow duration: 45 seconds

Model calls: 4

Tool calls: 3

Inventory API duration: 25 seconds

Inventory retries: 2

Estimated execution cost: $0.18

Your tasks

Identify the likely latency bottleneck.
Calculate the inventory API's share of total execution time.
Identify additional telemetry required for root-cause analysis.
Recommend improvements to retry handling.
Define three operational metrics.
Propose two alerts.
Explain what information should not be logged.
Describe how evaluation results could be linked to traces.

Reusable AI-assisted prompt

Act as an AI systems observability engineer.

Analyze this fictional agent workflow:

Total duration: 45 seconds
Model calls: 4
Tool calls: 3
Inventory API duration: 25 seconds
Inventory retries: 2
Estimated cost: $0.18

Provide:
1. Initial performance diagnosis.
2. Latency contribution analysis.
3. Possible root causes.
4. Additional telemetry required.
5. Recommended metrics.
6. Trace and log requirements.
7. Alerting recommendations.
8. Privacy and security safeguards.
9. Improvement experiments.
10. Verification plan.

Distinguish observed facts from hypotheses.
Do not assume the root cause is proven.

Accomplishment: Produce an evidence-based diagnosis and observability improvement plan for an AI workflow.

10. Student and Practitioner Project

Mini Project: Build an AI Agent Observability Dashboard

Objective: Instrument a fictional AI workflow and create a basic monitoring dashboard.

Project requirements

Define a multi-step fictional AI workflow.
Instrument model and tool operations.
Assign trace and span identifiers.
Capture execution duration and status.
Track token usage and estimated cost.
Record tool errors and retries.
Create a simple latency and error dashboard.
Simulate a slow external API.
Investigate the resulting trace.
Recommend and test an improvement.

Suggested dashboard measures

Metric	Purpose
Request count	Tracks workload volume
End-to-end latency	Measures user-visible processing time
Tool latency	Identifies slow external operations
Model latency	Measures inference time
Error rate	Tracks operational failures
Retry count	Identifies repeated operations
Token usage	Measures model consumption
Estimated cost	Tracks financial efficiency

Project deliverable: A trace diagram, telemetry dataset, dashboard or dashboard design, incident analysis, and engineering improvement recommendation.

11. Check Your Understanding

What is observability in AI engineering?
How do traces, metrics, and logs differ?
What is a span?
Why are trace identifiers important?
How does observability support agent evaluation?
Why can logging complete prompts create privacy risks?
How would you investigate an unexpectedly slow AI workflow?
What distinguishes operational success from task correctness?

Reflection: If an AI workflow completes successfully but consumes three times its normal cost, should the system be considered healthy? Which additional measures would help you decide?

12. Active Connections

Coming next — #013: Guardrails and Policy Enforcement: Keeping AI Applications Within Operational Boundaries.

13. References and Further Reading

Instrumentation libraries, semantic conventions, and AI observability tools evolve. Verify the latest documentation before production implementation.

Final Takeaway

Observability makes AI execution understandable. Tracing shows how work progresses, metrics reveal performance patterns, and logs provide diagnostic evidence. Together, they enable engineers to investigate failures, control costs, and improve operational reliability.

AI Engineering — Active Concepts & Practices
Active Concept #012 — Observability and Tracing

AIYING — Accomplishing with AI

Understand → Connect → Apply → Accomplish

AI Engineering Active Concepts #011 — Agent Evaluation: Measuring Whether AI Workflows Actually Succeed

AI ENGINEERING — ACTIVE CONCEPTS & PRACTICES | #011

Agent Evaluation: Measuring Whether AI Workflows Actually Succeed

Chapter 2: Engineering AI Applications and Agents

AIYING — Accomplishing with AI

The Big Idea: Agent evaluation measures whether an AI workflow completes its intended task correctly, reliably, safely, and efficiently.

Fluent responses and successful tool calls do not necessarily demonstrate successful task completion.

Engineering question: What evidence proves that an AI agent accomplished the intended business outcome?

Why Agent Evaluation Matters
UNDERSTAND — The Concept
CONNECT — AI Engineering Relationships
Evaluation Architecture
APPLY — Enterprise Procurement Agent
Worked Example: Evaluating 100 Workflows
Engineering Decisions and Trade-offs
Active Industry Practices
ACCOMPLISH — Practical Exercise
Student and Practitioner Project
Check Your Understanding
Active Connections
References and Further Reading

1. Why Agent Evaluation Matters

Imagine a procurement AI agent assigned to investigate delayed purchase orders and recommend recovery actions.

During testing, it successfully calls the required tools, produces professional reports, and appears to follow the intended workflow.

But closer inspection reveals that some recommendations are based on outdated inventory, some approvals are missing, and several completed tasks were reported incorrectly.

The agent may look effective without being operationally reliable.

The success of an AI agent must be evaluated against the intended outcome, not merely the quality of its generated response.

2. UNDERSTAND — The Concept

What is agent evaluation?

Agent evaluation is the systematic assessment of how well an AI agent or agentic workflow performs defined tasks under specified conditions.

It examines the final outcome, intermediate decisions, tool interactions, operational constraints, and failure behavior.

Five evaluation dimensions

Dimension	Key Question
Correctness	Did the agent produce the right result?
Reliability	Does it succeed consistently across relevant cases?
Efficiency	How much time and cost does execution require?
Safety	Did it respect permissions and operational boundaries?
Usefulness	Did the outcome help accomplish the real task?

Three levels of evaluation

Component evaluation: Tests individual operations such as retrieval, classification, and tool selection.

Trajectory evaluation: Examines the sequence of steps, tool calls, decisions, and state transitions.

Outcome evaluation: Determines whether the overall task was completed correctly.

Evaluation versus monitoring

Evaluation determines whether a system meets defined criteria.

Monitoring observes its behavior during operation.

Production traces and feedback can supply evidence for ongoing evaluation, but monitoring alone does not establish correctness.

3. CONNECT — AI Engineering Relationships

Concept	Connection to Evaluation
Context Engineering	Tests whether the model receives relevant information
Retrieval Engineering	Measures relevance, coverage, and evidence quality
Structured Outputs	Tests schema adherence and data accuracy
Tool Calling	Evaluates tool selection and argument correctness
MCP	Tests external capability discovery and invocation
Agent Orchestration	Evaluates workflow progression and recovery
Observability	Supplies execution traces and operational signals
AI Governance	Defines accountability, safety, and approval requirements
Token Economics	Measures execution costs and efficiency

Active connection: Evaluation turns the technical capabilities studied in earlier lessons into measurable engineering performance.

4. Evaluation Architecture

Define Intended Task and Success Criteria

↓

Build Representative Test Cases

↓

Execute Agent Workflow

↓

Capture Outputs and Execution Traces

↓

Apply Deterministic and Judgment-Based Checks

↓

Analyze Failures and Performance

↓

Improve and Re-Evaluate

Step 1 — Define success

Specify observable completion conditions, acceptable errors, and prohibited actions before testing.

Step 2 — Construct evaluation cases

Include normal cases, edge cases, ambiguous requests, incomplete data, tool failures, and authorization scenarios.

Step 3 — Run the workflow

Execute the system against controlled inputs using representative tools or simulated environments.

Step 4 — Capture evidence

Record final outputs, tool calls, execution state, latency, cost, and relevant decisions.

Step 5 — Score results

Use exact checks where objective answers exist and carefully designed human or model-based judgments where interpretation is required.

Step 6 — Diagnose failures

Determine whether failures originated in retrieval, planning, tool use, reasoning, authorization, or workflow execution.

Step 7 — Improve and retest

Repeat evaluations after changes and check for regressions in previously successful cases.

5. APPLY — Enterprise Procurement Agent

Scenario: Evaluating Purchase Order Recovery

A manufacturing organization uses an AI agent to identify delayed purchase orders and recommend recovery actions.

The system can retrieve order records, inspect alternative stock, examine procurement policies, and prepare approval requests.

What should be evaluated?

Evaluation Area	Example Test
Order retrieval	Did the agent identify the correct purchase order?
Inventory accuracy	Did it use current, authorized inventory data?
Recommendation	Is the proposed recovery action feasible?
Policy compliance	Did it follow procurement constraints?
Approval handling	Did it pause before restricted operations?
Execution reporting	Did it distinguish proposed and completed actions?
Failure handling	Did it recover or escalate appropriately?

Why end-to-end evaluation matters

A system may retrieve the correct order and select the correct tool yet recommend an invalid stock transfer.

Conversely, it may produce a correct recommendation but fail to obtain mandatory approval.

Evaluation must consider the complete workflow and its operational requirements.

6. Worked Example: Evaluating 100 Workflows

Consider the following fictional test results for a procurement agent.

Measure	Illustrative Result
Total test cases	100
Correct final outcomes	82
Correct tool selection	94
Correct tool arguments	90
Approval violations	2
Average execution time	18 seconds
Average estimated execution cost	$0.06

Assume each case contributes one binary result to each applicable measure, and all 100 cases are eligible for the listed accuracy checks.

Task success rate

Task Success Rate =
Successful Cases / Total Cases × 100

= 82 / 100 × 100
= 82%

Tool selection accuracy

Tool Selection Accuracy =
Correct Selections / Evaluated Cases × 100

= 94 / 100 × 100
= 94%

Approval violation rate

Approval Violation Rate =
Cases with Violations / Total Cases × 100

= 2 / 100 × 100
= 2%

For production evaluation, approval violations should also be measured against the subset of cases where approval requirements actually apply.

Interpretation

The agent selects tools correctly in most cases, but its final task-success rate is lower.

This indicates that tool selection alone does not explain overall performance.

More importantly, two approval violations indicate a control failure requiring investigation. A high average success rate cannot compensate for unauthorized consequential actions.

Engineering conclusion

The system requires root-cause analysis, stronger approval enforcement, and targeted regression tests before its suitability for production can be established.

7. Engineering Decisions and Trade-offs

Decision	Benefit	Trade-off
Exact-match scoring	Repeatable and objective	May reject valid alternatives
Human evaluation	Contextual judgment	Time and reviewer variability
LLM-as-judge	Scalable qualitative assessment	Bias and grading errors
Simulated environments	Safe and repeatable tests	May differ from production
Production feedback	Real-world relevance	Noise and incomplete ground truth
Trace-level scoring	Detailed diagnosis	Higher evaluation complexity
End-to-end scoring	Measures task completion	May obscure root causes

Important evaluation risks

Unrepresentative test datasets
Ambiguous or incorrect reference answers
Overreliance on subjective grading
Data leakage between development and test sets
Ignoring rare but severe failures
Confusing fluent explanations with correct outcomes
Failing to retest after changes
Using averages that conceal critical failure cases

Recommended practices

Define success criteria before implementation.
Use representative and adversarial test cases.
Combine deterministic checks with calibrated human judgment.
Capture execution traces.
Separate quality, safety, latency, and cost measures.
Track performance by scenario and failure category.
Maintain regression test suites.
Investigate critical failures independently of aggregate scores.

Evaluation quality depends not only on the metric but also on the relevance of the test cases, the validity of the reference answers, and the consequences of failure.

8. Active Industry Practices

Established practices

Task-based benchmark datasets
Unit and integration testing for tools
Human review of model outputs
Automated regression testing
Latency and cost measurement
Failure classification and analysis

Evolving agent evaluation practices

Trajectory and trace evaluation
LLM-assisted grading
Simulation-based agent testing
Multi-turn and multi-step task evaluation
Continuous evaluation from production feedback
Risk-weighted evaluation of agent actions

Relevant technologies

Engineering teams may use OpenAI Evals and agent evaluation tooling, LangSmith, MLflow, or custom test harnesses depending on their requirements.

Evaluation tools do not replace the need for clearly defined business success criteria and valid test data.

Industry relevance

Agent evaluation is important in enterprise automation, customer support, software development, financial operations, procurement, research assistants, and other systems where AI-generated decisions influence operational outcomes.

Practice status: Established software testing principles combined with rapidly developing agent-specific evaluation methods.

Reviewed: November 2026.

9. ACCOMPLISH — Practical Exercise

Exercise: Evaluate a Procurement Agent

Consider a fictional agent that investigates delayed purchase orders.

Task: Recommend a recovery action.

Purchase order: PO-2056

Required quantity: 500 units

Alternative stock: 350 units

Approval: Required for stock transfer

Your tasks

Define what successful completion means.
Identify the required evidence.
Write five normal test cases.
Write three failure or edge cases.
Define a scoring rubric.
Identify critical safety checks.
Specify the execution information to record.
Describe how failures should be classified.
Recommend a release decision based on the results.

Reusable AI-assisted prompt

Act as an AI engineering evaluation specialist.

Design an evaluation plan for a
fictional procurement AI agent.

The agent:
- Retrieves purchase-order information
- Checks alternative inventory
- Recommends recovery actions
- Requests approval when required
- Reports workflow outcomes

Provide:
1. Task success criteria.
2. Representative test scenarios.
3. Edge and failure cases.
4. Expected results.
5. Tool-use evaluation criteria.
6. Workflow trace checks.
7. Safety and approval tests.
8. Cost and latency metrics.
9. Failure classification.
10. Release-readiness recommendation.

Distinguish simulated test results
from real measured performance.

Accomplishment: Create an evaluation plan that measures whether an AI agent accomplishes its intended task safely and reliably.

10. Student and Practitioner Project

Mini Project: Build an Agent Evaluation Harness

Objective: Develop a small evaluation system for a fictional procurement agent.

Project requirements

Define 20 representative test cases.
Create expected outcomes for each case.
Implement or simulate an agent workflow.
Capture tool calls and execution results.
Score final task completion.
Check tool selection and argument correctness.
Test approval compliance.
Measure execution latency and estimated cost.
Classify failed cases.
Produce a performance report and improvement plan.

Suggested evaluation scorecard

Metric	Purpose
Task success rate	Measures correct final outcomes
Tool selection accuracy	Measures correct tool choice
Argument accuracy	Measures correctness of tool inputs
Policy compliance	Measures adherence to operational rules
Recovery success	Measures handling of failures
Average latency	Measures execution speed
Average cost	Measures resource efficiency
Critical failure count	Tracks severe errors independently

Project deliverable: A test dataset, evaluation harness or design, execution traces, scorecard, failure analysis, and engineering recommendations.

11. Check Your Understanding

What is agent evaluation?
Why is fluent output insufficient evidence of success?
How do component, trajectory, and outcome evaluations differ?
What is the difference between evaluation and monitoring?
When is deterministic scoring preferable?
What are the limitations of LLM-as-judge evaluation?
Why must critical failures be examined separately?
How would you evaluate an agent before production deployment?

Reflection: If an AI agent achieves 98% task success but occasionally performs unauthorized actions, should it be considered production-ready? What additional controls or evidence would be required?

12. Active Connections

Coming next — #012: Observability and Tracing: Understanding What AI Systems Actually Do.

13. References and Further Reading

Evaluation frameworks, metrics, and tooling evolve. Consult current documentation and validate scoring methods against the requirements of each application.

Final Takeaway

An AI agent is not successful because it completed a sequence of steps. It is successful when evidence demonstrates that it achieved the intended outcome correctly, safely, and reliably.

AI Engineering — Active Concepts & Practices
Active Concept #011 — Agent Evaluation

AIYING — Accomplishing with AI

Understand → Connect → Apply → Accomplish

AI Engineering Active Concepts #010 — Agent Orchestration: Designing Reliable Multi-Step AI Workflows

AI ENGINEERING — ACTIVE CONCEPTS & PRACTICES | #010

Agent Orchestration: Designing Reliable Multi-Step AI Workflows

Chapter 2: Engineering AI Applications and Agents

AIYING — Accomplishing with AI

The Big Idea: Agent orchestration coordinates the sequence, dependencies, tools, decisions, state, and controls required to complete multi-step AI tasks.

An individual model response may be useful. An orchestrated workflow must deliver a verifiable outcome.

Engineering question: How do we make an AI workflow reliable when it involves multiple steps, external systems, failures, and human approvals?

Why Agent Orchestration Matters
UNDERSTAND — The Concept
CONNECT — AI Engineering Relationships
Agent Orchestration Architecture
APPLY — Enterprise Procurement Workflow
Worked Example: A Multi-Step Workflow
Engineering Decisions and Trade-offs
Active Industry Practices
ACCOMPLISH — Practical Exercise
Student and Practitioner Project
Check Your Understanding
Active Connections
References and Further Reading

1. Why Agent Orchestration Matters

Consider an enterprise procurement manager asking:

"Check purchase order PO-1048. Verify whether the required material is available elsewhere. If delivery is delayed, recommend a recovery action and prepare the necessary follow-up."

This is not a single question. It is a sequence of dependent tasks.

The AI application may need to retrieve purchase-order information, inspect inventory, compare delivery alternatives, apply procurement policies, prepare a recommendation, and obtain approval before making changes.

Each step depends on information or decisions from previous steps.

What happens if the inventory service is unavailable? What if the purchase-order record is inconsistent? What if a human reviewer rejects the proposed action?

These are orchestration problems.

Agent orchestration is not simply connecting several AI calls. It is engineering the control flow that turns multiple operations into a dependable business outcome.

2. UNDERSTAND — The Concept

What is agent orchestration?

Agent orchestration is the coordination of AI models, tools, workflow steps, decisions, application state, and control mechanisms to accomplish a task.

The orchestrator may be implemented through conventional software logic, a workflow engine, an agent framework, or a combination of these.

Five essential responsibilities

Responsibility	Engineering Question
Planning	Which steps are required?
Coordination	What should run next, and what depends on what?
State management	What has already happened?
Control	Which operations are permitted?
Recovery	What happens when a step fails?

Workflow versus agent

A workflow generally follows a predefined control structure. An agent may dynamically select actions and tools based on intermediate observations.

In practice, production systems often combine both approaches.

For example, an agent may analyze a supplier delay while a deterministic workflow controls approvals, record updates, and completion status.

Common orchestration patterns

Sequential: Execute dependent steps in order.
Parallel: Run independent operations concurrently.
Conditional routing: Choose a branch based on validated results.
Iterative: Repeat a bounded process until a condition is satisfied.
Supervisor-worker: Delegate specialized tasks to different components.
Human-in-the-loop: Pause for an authorized decision.
Event-driven: Resume when an external event occurs.

Not every problem needs multiple agents. A deterministic workflow with one model and a few tools may be simpler, cheaper, and easier to test.

3. CONNECT — AI Engineering Relationships

Concept	Relationship to Orchestration
Context Engineering	Supplies relevant information to each step
Token Economics	Controls the cost of repeated model calls
Retrieval Engineering	Provides external evidence
Context Management	Preserves state and continuity
Structured Outputs	Defines data contracts between steps
Tool Calling	Invokes external capabilities
MCP	Provides standardized access to external capabilities
Evaluation	Tests both individual steps and overall outcomes
Observability	Traces execution, latency, cost, and failures
Governance	Establishes accountability and approval controls

Active connection: Orchestration brings together the capabilities studied in earlier lessons into an operational AI application.

4. Agent Orchestration Architecture

User Request

↓

Workflow Controller / Orchestrator

↓

Task Planning and State Initialization

↓

Model and Tool Execution

↓

Result Validation

↓

Decision: Continue, Retry, Escalate, or Stop?

↓

Human Approval When Required

↓

Authorized Business Action

↓

Outcome Verification and Audit Record

State transitions

A workflow should have explicit states, such as:

CREATED
   |
   v
RUNNING
   |
   +--> WAITING_FOR_APPROVAL
   |           |
   |           v
   |        RUNNING
   |
   +--> FAILED
   |
   +--> COMPLETED

Real implementations may need additional states such as cancelled, timed out, rejected, or requiring manual intervention.

Why state matters

State enables a workflow to resume after interruptions, avoid repeating completed actions, and distinguish a pending operation from a successful one.

State should be stored in a durable application system when the workflow must survive process restarts or extended human approval delays.

5. APPLY — Enterprise Procurement Workflow

Scenario: Recovering from a Supplier Delay

A manufacturing company uses an AI assistant to investigate delayed material deliveries.

The assistant has access to fictional procurement, inventory, and supplier systems.

Step 1 — Retrieve purchase order

The system obtains the current order status through an authorized lookup tool.

Step 2 — Check inventory

The application retrieves stock availability from alternative locations.

Step 3 — Evaluate alternatives

The AI analyzes available evidence and prepares possible recovery options.

Step 4 — Apply business constraints

Deterministic checks verify inventory eligibility, policy requirements, and permitted actions.

Step 5 — Request approval

If a transfer or supplier change requires approval, the workflow pauses for the designated decision-maker.

Step 6 — Execute authorized action

The application invokes the approved operation and verifies its result.

Step 7 — Complete and record

The workflow reports the outcome and records the relevant execution history.

Important: The assistant should never describe an operation as completed merely because the model proposed it.

6. Worked Example: A Multi-Step Workflow

The following is a fictional design illustration, not a live enterprise integration.

Sample workflow state

{
  "workflow_id": "WF-1048",
  "po_id": "PO-1048",
  "status": "waiting_for_approval",
  "order_status": "delayed",
  "alternative_stock_available": true,
  "recommended_action": "internal_transfer",
  "approval_status": "pending",
  "execution_status": "not_started"
}

Illustrative orchestration pseudocode

async def process_order(po_id, user):
    order = await get_order(po_id, user)
    validate_order(order)

    if order["status"] != "delayed":
        return {"status": "completed",
                "action": "none"}

    inventory = await check_inventory(order, user)
    validate_inventory(inventory)

    proposal = await recommend_action(
        order, inventory
    )
    validate_proposal(proposal)

    approval_id = await request_approval(
        proposal, user
    )

    # Persist state and stop execution.
    # Resume only after a verified approval event.
    return {
        "status": "waiting_for_approval",
        "approval_id": approval_id,
        "execution_status": "not_started"
    }

This pseudocode illustrates a workflow boundary. A production implementation must authenticate the approver, persist state, resume through a controlled event, enforce authorization, and verify any eventual write operation.

What makes the workflow reliable?

Each step has defined inputs and outputs.
External results are validated.
State is recorded before suspension.
Approvals are explicit.
Retries are bounded and controlled.
Side-effecting actions use duplicate-prevention safeguards.
Completion is based on verified execution results.

7. Engineering Decisions and Trade-offs

Decision	Benefit	Trade-off
Fixed workflow	Predictability and testability	Less flexibility
Dynamic agent planning	Adapts to varied tasks	Harder to constrain and evaluate
Parallel execution	Reduced latency	Dependency and concurrency risks
Persistent state	Resumability	Storage and consistency complexity
Automatic retries	Failure recovery	Cost and duplicate-action risks
Human approval	Stronger oversight	Additional time
Multiple specialized agents	Division of responsibilities	Coordination overhead

Common failure modes

Infinite or excessive execution loops
Incorrect tool selection
Loss of workflow state
Contradictory intermediate results
Repeated actions after retries
Unauthorized execution
Unbounded token consumption
Incorrect completion reporting
Prompt injection through retrieved data or tool results

Recommended engineering controls

Maximum step and execution budgets
Timeouts and bounded retries
Checkpointing and durable state
Idempotency for operations with side effects
Structured contracts between components
Explicit approval boundaries
Least-privilege tool permissions
Execution tracing and audit records
Outcome-based evaluations

Reliable orchestration requires a controlled workflow, not merely a capable model.

8. Active Industry Practices

Established engineering approaches

State-machine and graph-based workflows
Task dependency management
Tool execution with validation
Human approval checkpoints
Persistent workflow state
Execution tracing and monitoring

Evolving AI engineering practices

Model-directed workflow routing
Supervisor and specialist-agent architectures
Agent evaluation using execution traces
Policy-aware tool orchestration
Adaptive planning with bounded autonomy
Durable execution for long-running agents

Relevant technologies

Developers may evaluate frameworks such as LangGraph, Microsoft Agent Framework, OpenAI Agents SDK, and conventional workflow engines.

These technologies have different architectures and operational characteristics. Framework selection should follow the requirements of the application rather than determine the architecture in advance.

Industry applications

Agent orchestration is relevant to customer support, software engineering, incident response, research assistants, enterprise operations, procurement, document processing, and multi-step business automation.

Practice status: Established workflow-engineering principles combined with evolving agentic AI architectures.

Reviewed: November 2026.

9. ACCOMPLISH — Practical Exercise

Exercise: Design a Procurement Recovery Workflow

Use this fictional scenario:

Purchase order: PO-2056

Status: Delayed

Required quantity: 500 units

Alternative location stock: 350 units

Proposed action: Partial internal transfer

Approval: Required

Your tasks

Define the workflow objective.
List the required tools and data sources.
Identify sequential and parallel steps.
Define workflow states and transitions.
Specify validation checkpoints.
Identify actions requiring approval.
Design failure and retry handling.
Define completion and escalation conditions.
Explain how the remaining 150-unit shortage will be handled.

Reusable AI-assisted prompt

Act as an enterprise AI workflow architect.

Design an agent orchestration workflow
for a delayed purchase order.

Scenario:
- Order: PO-2056
- Required quantity: 500 units
- Alternative stock: 350 units
- Supplier delivery: delayed
- Internal transfer: approval required

Provide:
1. Workflow objective.
2. Required tools and data.
3. Step-by-step execution plan.
4. State transitions.
5. Validation rules.
6. Approval checkpoints.
7. Failure recovery strategy.
8. Cost and execution limits.
9. Observability requirements.
10. Completion and escalation criteria.

Distinguish AI-generated recommendations
from verified system actions.

Do not claim any real action was executed.

Accomplishment: Produce an orchestration design that can be reviewed for reliability, authorization, recovery, and measurable completion.

10. Student and Practitioner Project

Mini Project: Build a Stateful Procurement Agent

Objective: Prototype a multi-step AI workflow using simulated enterprise systems.

Project requirements

Create fictional purchase-order and inventory datasets.
Define lookup and simulated action tools.
Implement a workflow controller.
Persist workflow state between steps.
Use structured inputs and outputs.
Introduce an approval checkpoint.
Simulate a tool timeout and a service failure.
Test workflow resumption after interruption.
Prevent duplicate side effects.
Record execution traces and evaluate outcomes.

Suggested evaluation metrics

Metric	What It Measures
Task completion rate	Successful completion of authorized workflows
Step accuracy	Correct execution of required stages
Recovery success	Resumption after failures
State consistency	Correctness of persisted workflow information
Approval compliance	Whether required approvals are enforced
Duplicate action rate	Repeated side effects after retries
Execution cost	Model and tool resource consumption
End-to-end latency	Total workflow processing time

Project deliverable: A workflow diagram, working prototype or design, sample execution traces, evaluation results, and an engineering recommendation.

11. Check Your Understanding

What is agent orchestration?
How is orchestration different from tool calling?
What is the difference between a fixed workflow and a dynamic agent?
Why is persistent state important?
When should workflow steps run in parallel?
How should approval checkpoints be implemented?
Why are retries dangerous for write operations?
How would you measure end-to-end workflow reliability?

Reflection: If every individual AI step succeeds but the overall workflow performs an unauthorized action, has the system succeeded? What does this reveal about orchestration quality?

12. Active Connections

Coming next — #011: Agent Evaluation: Measuring Whether AI Workflows Actually Succeed.

13. References and Further Reading

Framework capabilities and implementation guidance evolve. Verify the current documentation when building production systems.

Final Takeaway

A reliable AI workflow is not defined by how many agents or tools it uses. It is defined by whether it coordinates work correctly, handles failures, respects controls, and delivers a verified outcome.

AI Engineering — Active Concepts & Practices
Active Concept #010 — Agent Orchestration

AIYING — Accomplishing with AI

Understand → Connect → Apply → Accomplish

AI Engineering Active Concepts #009 — Model Context Protocol (MCP): Connecting AI to Tools and Data

AI ENGINEERING — ACTIVE CONCEPTS & PRACTICES | #009

Model Context Protocol (MCP): Standardizing AI Connections to Tools and Data

Chapter 2: Engineering AI Applications and Agents

AIYING — Accomplishing with AI

The Big Idea: Tool calling enables AI applications to use external capabilities. Model Context Protocol (MCP) provides a common interface through which compatible AI applications can discover and interact with external tools, resources, and prompts.

Engineering question: How can an organization make its existing systems accessible to multiple AI applications without building and maintaining a separate custom integration for every combination?

Why MCP Matters
UNDERSTAND — What Is MCP?
CONNECT — Related Engineering Concepts
MCP Architecture and Lifecycle
APPLY — Enterprise Procurement Integration
Worked Example: Purchase Order Lookup
Engineering Decisions and Trade-offs
Active Industry Practices
ACCOMPLISH — Design an MCP Integration
Student and Practitioner Project
Check Your Understanding
Active Connections
References and Further Reading

1. Why MCP Matters

Imagine an enterprise operating three AI applications:

A procurement assistant
A technical-support assistant
An AI operations assistant

Each application needs information from enterprise databases, document repositories, and business software.

Without a common integration approach, engineering teams may develop separate connectors for each application and external service.

This creates duplicated work, inconsistent interfaces, maintenance costs, and additional security review requirements.

MCP addresses part of this integration challenge by standardizing how AI applications discover and interact with exposed capabilities.

MCP standardizes the interface between compatible AI applications and external capabilities. It does not eliminate the need to implement, secure, and maintain the underlying integrations.

↑ Back to Contents

2. UNDERSTAND — What Is MCP?

Model Context Protocol (MCP) is an open protocol for connecting AI applications to external systems that provide tools, resources, and reusable prompts.

Originally introduced by Anthropic, MCP has developed as an ecosystem protocol with implementations across multiple AI platforms and developer tools.

The three architectural roles

Component	Responsibility
MCP Host	The AI application that manages user interaction and MCP connections
MCP Client	A protocol component within the host that communicates with an MCP server
MCP Server	Exposes capabilities through a standardized MCP interface

A host can manage connections to multiple servers through separate MCP clients.

The three foundational server capabilities

Capability	Purpose	Example
Tools	Expose callable operations	Retrieve a purchase order
Resources	Expose contextual information	Read an approved supplier policy
Prompts	Expose reusable prompt templates	Supplier delay analysis template

Tools, resources, and prompts are distinct protocol concepts. A server may expose one or more of them.

How is MCP different from an API?

An API defines how software accesses a particular service. MCP defines a common interface for presenting capabilities to compatible AI applications.

An MCP server can wrap an existing REST API, database, or enterprise service. The original API remains part of the implementation.

How is MCP different from tool calling?

Tool calling is the process through which a model or AI application requests an external operation.

MCP provides a standardized mechanism for discovering and accessing tools and other capabilities.

An AI application may translate a model-generated tool request into an MCP tool invocation.

Neither tool calling nor MCP automatically guarantees that an operation is safe or authorized.

↑ Back to Contents

3. CONNECT — Related Engineering Concepts

Concept	Connection to MCP
Tool Calling	MCP tools can be made available for model-requested operations
Structured Outputs	Tool arguments and results use structured data
JSON Schema	Describes tool input and output structures
APIs	MCP servers can expose capabilities backed by APIs
Context Engineering	MCP resources can contribute external context
AI Agents	Agents may coordinate capabilities exposed by MCP servers
Authentication	Establishes identities and access credentials
Authorization	Determines which operations and records are permitted
Observability	Monitors server interactions, errors, and latency
AI Governance	Establishes trust, oversight, and accountability requirements

An important architectural insight

MCP separates the presentation of external capabilities from much of the application-specific integration code.

This can improve reuse and interoperability when both the host and server implement compatible protocol capabilities.

↑ Back to Contents

4. MCP Architecture and Lifecycle

Enterprise AI Assistant — MCP Host

↓

MCP Client

↓ Protocol Communication

MCP Server

↓

Enterprise API / Database / Service

↓

Authorized Result

↓

AI Application

Step 1 — Connection and initialization

The MCP client and server establish communication and negotiate supported protocol capabilities.

Step 2 — Capability discovery

The client can discover available tools, resources, or prompts using the relevant protocol operations.

Step 3 — Model or application selection

The host determines which available capability is relevant to the task. A model may propose a tool call, but application logic remains responsible for execution decisions.

Step 4 — Invocation

The MCP client sends a request to the server using the defined protocol interface.

Step 5 — External execution

The server may access an underlying API or database, subject to applicable permissions and controls.

Step 6 — Result handling

The result returns to the host, which may validate it, display it, or supply relevant information to the model.

Transport options

MCP supports communication arrangements including local standard input/output (stdio) and remote Streamable HTTP transport.

Transport selection affects deployment, authentication, operational monitoring, and security architecture.

Use the current MCP specification for implementation details because protocol features and transport guidance evolve.

↑ Back to Contents

5. APPLY — Enterprise Procurement Integration

Scenario: Multiple Assistants, Shared Enterprise Capabilities

A manufacturing company has purchase-order information in an ERP system, inventory records in a database, and supplier policies in a document repository.

The organization wants multiple AI assistants to access these capabilities through controlled interfaces.

Approach A — Separate integrations

Each assistant implements its own connection logic for the ERP system, inventory database, and document repository.

Changes to an underlying API may require updates across multiple applications.

Approach B — Shared MCP servers

The engineering team develops or deploys MCP servers that expose approved capabilities:

Procurement server: Purchase-order lookup tools.
Inventory server: Stock availability tools.
Policy server: Approved procurement documents as resources.

Compatible AI applications connect through MCP clients.

Server implementations still need to enforce user permissions, data restrictions, input validation, and operational controls.

Engineering outcome

This architecture may reduce duplicated integration work and improve reuse.

However, standardizing the interface does not automatically make business semantics, permissions, or error handling identical across systems.

↑ Back to Contents

6. Worked Example: Purchase Order Lookup

The following is a conceptual example using fictional enterprise data. It is not a live MCP connection.

Available MCP tool

{
  "name": "get_purchase_order",
  "description": "Retrieve an authorized purchase order",
  "inputSchema": {
    "type": "object",
    "properties": {
      "po_id": {
        "type": "string"
      }
    },
    "required": ["po_id"],
    "additionalProperties": false
  }
}

Illustrative MCP tool request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_purchase_order",
    "arguments": {
      "po_id": "PO-1048"
    }
  }
}

Illustrative tool result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "PO-1048: delayed; revised delivery 2026-11-23"
      }
    ]
  }
}

The tool result is illustrative. Production implementations should use appropriate typed outputs, validation, error reporting, and access controls.

What happens next?

The AI assistant can report the retrieved order status.

If the user also requests a follow-up task, the host may make an additional authorized tool available for that purpose.

The MCP server must not assume that a request from an AI model is automatically permitted.

Key distinction

The model may select the capability. The MCP client transports the request. The server implements the operation. The application and supporting systems remain responsible for authorization and outcome verification.

↑ Back to Contents

7. Engineering Decisions and Trade-offs

Decision	Potential Benefit	Risk or Trade-off
Shared MCP servers	Reusable integrations	Shared dependency and operational concentration
Local servers	Convenient local tool access	Host-machine access and process security risks
Remote servers	Centralized services	Network, authentication, and availability concerns
Read-only capabilities	Lower operational impact	Limited automation
Write-enabled tools	Greater workflow automation	Higher risk of unintended side effects
Broad tool catalogs	More capabilities	Selection complexity and attack surface
Third-party servers	Faster integration	Supply-chain and trust assessment requirements

Important security risks

Malicious or compromised MCP servers
Excessive tool permissions
Unauthorized access to enterprise records
Prompt injection through tool results or resources
Credential leakage or insecure token handling
Unapproved data transmission
Misleading tool descriptions
Unintended or repeated write operations

Recommended engineering controls

Maintain an approved server inventory.
Review server provenance and implementation.
Use least-privilege credentials.
Enforce authorization for each sensitive operation.
Validate tool inputs and outputs.
Require appropriate approval for consequential actions.
Restrict access to sensitive resources.
Log relevant operations without exposing secrets.
Monitor errors, changes, and unusual tool activity.
Test resilience and failure recovery.

MCP standardizes connectivity. Security, trust, and governance must still be engineered around every connection.

↑ Back to Contents

8. Active Industry Practices

Established foundations

Client-server protocol architecture
Structured tool discovery and invocation
Resource access through standardized interfaces
Reusable prompt templates
Local and remote server deployments
Integration with existing APIs and services

Developing engineering practices

Enterprise MCP server registries
Centralized server governance
Fine-grained tool access policies
Multi-server agent architectures
Server trust and provenance assessment
MCP observability and evaluation

Where MCP is relevant

MCP is relevant to AI coding assistants, enterprise knowledge assistants, data-analysis workflows, business-process automation, agentic applications, and AI-enabled developer environments.

It is particularly useful when multiple compatible AI applications need reusable access to external capabilities.

For a simple application with one stable API integration, a direct API connection may remain the more practical engineering choice.

Practice status: Open integration protocol with an evolving ecosystem and operational practices.

Reviewed: November 2026.

↑ Back to Contents

9. ACCOMPLISH — Design an MCP Integration

Exercise: Enterprise Procurement MCP Architecture

Consider a fictional manufacturing company with the following systems:

ERP: Purchase orders and supplier records.

Inventory database: Stock availability.

Document repository: Procurement policies.

AI applications: Procurement assistant and operations assistant.

Your tasks

Identify the capabilities each AI application needs.
Decide which capabilities should be tools and which should be resources.
Design an MCP server architecture.
Define a purchase-order lookup tool and its input schema.
Specify how user permissions should be enforced.
Identify operations requiring approval.
Describe how errors and unavailable services should be handled.
Explain how the design reduces duplicated integrations.

Reusable AI-assisted prompt

Act as an enterprise AI integration engineer.

Design an MCP-based architecture for a
fictional procurement organization.

Systems:
- ERP purchase orders
- Inventory database
- Procurement policy repository

AI applications:
- Procurement assistant
- Operations assistant

Provide:
1. MCP host, client, and server roles.
2. Proposed tools, resources, and prompts.
3. Tool input schemas.
4. Capability discovery and execution flow.
5. Authentication and authorization controls.
6. Human approval requirements.
7. Failure handling and observability.
8. Integration reuse benefits.
9. Risks and limitations.
10. A small implementation test plan.

Do not assume that MCP automatically
provides security or business authorization.

Accomplishment: Design an MCP integration architecture that supports reusable capabilities while preserving operational control.

↑ Back to Contents

10. Student and Practitioner Project

Mini Project: Build a Read-Only MCP Server

Objective: Build or prototype an MCP server that exposes purchase-order lookup capabilities using fictional data.

Project requirements

Create a small fictional purchase-order dataset.
Choose a compatible MCP SDK.
Implement a read-only purchase-order lookup tool.
Define and validate tool input parameters.
Expose a sample procurement-policy resource.
Connect using a compatible MCP client or inspection tool.
Test capability discovery.
Test successful and unsuccessful tool invocations.
Check that unauthorized or invalid requests are rejected.
Document execution logs and observed limitations.

Suggested evaluation measures

Metric	What It Measures
Discovery success	Whether the client can discover capabilities
Invocation accuracy	Whether valid tool calls return correct results
Input validation	Whether invalid arguments are rejected
Access control	Whether unauthorized operations are blocked
Latency	Time required to complete tool requests
Error handling	Whether failures are reported accurately
Reuse potential	Whether multiple compatible clients can use the server

Deliverable: A working demonstration or architecture prototype, tool definition, sample request and response, test results, and an engineering recommendation.

Use fictional data and a local development environment. Do not expose real credentials or production systems during the exercise.

↑ Back to Contents

11. Check Your Understanding

What problem does MCP address in AI engineering?
What is the difference between an MCP host, client, and server?
How do MCP tools differ from resources and prompts?
How is MCP different from a conventional API?
How does MCP relate to model tool calling?
Does MCP automatically enforce enterprise authorization?
What risks arise from connecting untrusted MCP servers?
When might a direct API integration be preferable?

Reflection: If an MCP server exposes a tool named "approve_payment", should an AI assistant be allowed to invoke it merely because the tool is discoverable? What additional controls are necessary?

↑ Back to Contents

12. Active Connections

Coming next — #010: Agent Orchestration: Designing Reliable Multi-Step AI Workflows.

↑ Back to Contents

13. References and Further Reading

MCP specifications, SDKs, transport guidance, and security practices evolve. Consult the latest official documentation before implementing production integrations.

Final Takeaway

MCP helps make external tools, data, and reusable prompts accessible through a common protocol. Effective AI engineering combines this interoperability with explicit security, authorization, validation, and operational accountability.

AI Engineering — Active Concepts & Practices
Active Concept #009 — Model Context Protocol

AIYING — Accomplishing with AI

Understand → Connect → Apply → Accomplish