fast-agent-mcp 0.2.45__py3-none-any.whl → 0.2.46__py3-none-any.whl

{fast_agent_mcp-0.2.45.dist-info → fast_agent_mcp-0.2.46.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fast-agent-mcp
-Version: 0.2.45
+Version: 0.2.46
 Summary: Define, Prompt and Test MCP enabled Agents and Workflows
 Author-email: Shaun Smith <fastagent@llmindset.co.uk>
 License:                                  Apache License
@@ -218,7 +218,7 @@ Requires-Dist: deprecated>=1.2.18
 Requires-Dist: email-validator>=2.2.0
 Requires-Dist: fastapi>=0.115.6
 Requires-Dist: google-genai
-Requires-Dist: mcp==1.12.0
+Requires-Dist: mcp==1.12.1
 Requires-Dist: openai>=1.93.0
 Requires-Dist: opentelemetry-distro>=0.50b0
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.29.0

{fast_agent_mcp-0.2.45.dist-info → fast_agent_mcp-0.2.46.dist-info}/RECORD

@@ -1,4 +1,4 @@
-mcp_agent/__init__.py,sha256=18T0AG0W9sJhTY38O9GFFOzliDhxx9p87CvRyti9zbw,1620
+mcp_agent/__init__.py,sha256=HWWxZeB-VxrUNNXZnu4duzKGwdfCdD2M_O6drN4kfs8,2389
 mcp_agent/app.py,sha256=3mtHP1nRQcRaKhhxgTmCOv00alh70nT7UxNA8bN47QE,5560
 mcp_agent/config.py,sha256=RjwgvR-Sys4JIzhNyEsaS_NarCe157RenJLOsioUtDk,18980
 mcp_agent/console.py,sha256=Gjf2QLFumwG1Lav__c07X_kZxxEUSkzV-1_-YbAwcwo,813
@@ -7,6 +7,7 @@ mcp_agent/context_dependent.py,sha256=QXfhw3RaQCKfscEEBRGuZ3sdMWqkgShz2jJ1ivGGX1
 mcp_agent/event_progress.py,sha256=d7T1hQ1D289MYh2Z5bMPB4JqjGqTOzveJuOHE03B_Xo,3720
 mcp_agent/mcp_server_registry.py,sha256=lmz-aES-l7Gbg4itDF0iCmpso_KD8bVazVKSVzjwNE4,12398
 mcp_agent/progress_display.py,sha256=GeJU9VUt6qKsFVymG688hCMVCsAygG9ifiiEb5IcbN4,361
+mcp_agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mcp_agent/agents/agent.py,sha256=EAYlcP1qqI1D0_CS808I806z1048FBjZQxxpcCZPeIU,3154
 mcp_agent/agents/base_agent.py,sha256=VCBWJ-l1zMQiBuONGzqcbqPUQfXK4oq-pBB5lJrMgQ0,32318
@@ -24,15 +25,15 @@ mcp_agent/cli/constants.py,sha256=KawdkaN289nVB02DKPB4IVUJ8-fohIUD0gLfOp0P7B8,55
 mcp_agent/cli/main.py,sha256=Hfa6yn47gfx_d6TUEbzDz68k2gaIS9vvN0yDbVOUgnc,3181
 mcp_agent/cli/terminal.py,sha256=GRwD-RGW7saIz2IOWZn5vD6JjiArscELBThm1GTFkuI,1065
 mcp_agent/cli/commands/check_config.py,sha256=15YK0mtDQbVopnMm3HBjOeY2-00FUHj6tt8RvaemKmI,21081
-mcp_agent/cli/commands/go.py,sha256=mVNtupzDr-qb95cv2rp9JLC2_5-QQgv8x7uyTwYH7wY,13240
+mcp_agent/cli/commands/go.py,sha256=ydVEyLrMxkp0ZuiPbcOhxUuxBx5FE2RJAV02dppSkaU,14121
 mcp_agent/cli/commands/quickstart.py,sha256=lcozUGP9RRO8xZaayJg4pQNeY5zDQs-eg-ABm0A15cI,16471
 mcp_agent/cli/commands/server_helpers.py,sha256=x5tD_qhf1W4D2li09sfOyfRWCOCa6lmpumYAPsEfIQs,3649
 mcp_agent/cli/commands/setup.py,sha256=eOEd4TL-b0DaDeSJMGOfNOsTEItoZ67W88eTP4aP-bo,6482
 mcp_agent/cli/commands/url_parser.py,sha256=5VdtcHRHzi67YignStVbz7u-rcvNNErw9oJLAUFOtEY,5855
-mcp_agent/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_agent/core/__init__.py,sha256=7xAVBbyrsJwmrzL-we9tBY9PcJxFnajoJcaXSc6gBUw,391
 mcp_agent/core/agent_app.py,sha256=SolGwejEmv9XtsTsmiMkNKPia7RN1VcHXm6JoEo4hvQ,16187
 mcp_agent/core/agent_types.py,sha256=7zVzAFWjvh5dDV3TuDwmO9LAWmDjYnZd3eeLH-wvvIQ,1705
-mcp_agent/core/direct_decorators.py,sha256=zWnfs4sxONw_7UOno62ERb0gezMgV_AIOfxb0tRQg3w,18939
+mcp_agent/core/direct_decorators.py,sha256=CTM9KbzpLx-tPiT5KJN7nZycCyc74ekMJy3wdZhysmo,22065
 mcp_agent/core/direct_factory.py,sha256=d_HvbAxyv2WrM07zyCpLXFVn7eArXk1LZmLKS49hzJo,19537
 mcp_agent/core/enhanced_prompt.py,sha256=ZIeJCeW7rcGMBZ2OdEQwqOmRT0wNSp0hO2-dZRSnnLE,36068
 mcp_agent/core/error_handling.py,sha256=xoyS2kLe0eG0bj2eSJCJ2odIhGUve2SbDR7jP-A-uRw,624
@@ -48,17 +49,19 @@ mcp_agent/executor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuF
 mcp_agent/executor/executor.py,sha256=E44p6d-o3OMRoP_dNs_cDnyti91LQ3P9eNU88mSi1kc,9462
 mcp_agent/executor/task_registry.py,sha256=PCALFeYtkQrPBg4RBJnlA0aDI8nHclrNkHGUS4kV3W8,1242
 mcp_agent/executor/workflow_signal.py,sha256=Cg1uZBk3fn8kXhPOg-wINNuVaf3v9pvLD6NbqWy5Z6E,11142
-mcp_agent/human_input/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_agent/human_input/__init__.py,sha256=RydNC10PhvTYFbLXXs0JMTnAt0ihPYeJZoRTnsq3eMg,909
 mcp_agent/human_input/elicitation_form.py,sha256=VgS-DXlwYTU4qDntok4Pqt8qfl1w_-Xby5PTlfNerug,28324
 mcp_agent/human_input/elicitation_forms.py,sha256=w8XQ1GfZX8Jw-VB4jnDI0Im4mF-T9Ts8mT2zRZBtL6M,3824
 mcp_agent/human_input/elicitation_handler.py,sha256=YfVhIhSBc9wuszPS4zoHho4n1pwmIoq13huN4MSRkIs,3305
 mcp_agent/human_input/elicitation_state.py,sha256=Unl9uhEybUqACCUimnETdfUprJNpYDMq3DdbbHw5oAw,1175
+mcp_agent/human_input/form_fields.py,sha256=aE7HdR-wOPO_6HllNaJXtn3BzpPsC4TctUApbveRk8g,7644
 mcp_agent/human_input/handler.py,sha256=s712Z5ssTCwjL9-VKoIdP5CtgMh43YvepynYisiWTTA,3144
+mcp_agent/human_input/simple_form.py,sha256=u6iCo39IJftB1S1xljdQP3C18RuRCcwp7jKQTTDcLT4,3441
 mcp_agent/human_input/types.py,sha256=RtWBOVzy8vnYoQrc36jRLn8z8N3C4pDPMBN5vF6qM5Y,1476
 mcp_agent/llm/__init__.py,sha256=d8zgwG-bRFuwiMNMYkywg_qytk4P8lawyld_meuUmHI,68
-mcp_agent/llm/augmented_llm.py,sha256=UiOTOAaNVnc03yuLBbBZstnaOG6Q8XLwkyiHPA3yxEk,27434
+mcp_agent/llm/augmented_llm.py,sha256=UCAKqlsv3eUBIhOz0p3_bSNKOY3MykJIb7OBKoXJjWI,27973
 mcp_agent/llm/augmented_llm_passthrough.py,sha256=bu0DJkjyFPzBZEU7f6MHnOp__9BCYl56tFd5nZVhSeY,8808
-mcp_agent/llm/augmented_llm_playback.py,sha256=BQeBXRpO-xGAY9wIJxyde6xpHmZEdQPLd32frF8t3QQ,4916
+mcp_agent/llm/augmented_llm_playback.py,sha256=rLzgai496e2RlxqQp_Bp0U-Y1FF1SGsWl9COx4GiCNE,5004
 mcp_agent/llm/augmented_llm_silent.py,sha256=IUnK_1Byy4D9TG0Pj46LFeNezgSTQ8d6MQIHWAImBwE,1846
 mcp_agent/llm/augmented_llm_slow.py,sha256=DDSD8bL2flmQrVHZm-UDs7sR8aHRWkDOcOW-mX_GPok,2067
 mcp_agent/llm/memory.py,sha256=pTOaTDV3EA3X68yKwEtUAu7s0xGIQQ_cKBhfYUnfR0w,8614
@@ -99,13 +102,13 @@ mcp_agent/logging/listeners.py,sha256=_S4Jp5_KWp0kUfrx4BxDdNCeQK3MNT3Zi9AaolPri7
 mcp_agent/logging/logger.py,sha256=v2_D5kWLSS9u4ueSU7q6cWF1oSmTVeAAtgnwR0LrbXI,11056
 mcp_agent/logging/rich_progress.py,sha256=uMAKDPO8TlhT7uTeJzOEwQPme8pu8qCADLNbsI1vV8g,5544
 mcp_agent/logging/transport.py,sha256=_RVckOdcs_mXv6Jwz-MPe0vVTQEKsbejHdteyK5hBQA,16960
-mcp_agent/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_agent/mcp/__init__.py,sha256=yxtzSmWBNqRf_nJckqgzYoozyGKja05FvSRLLus_7eM,1100
 mcp_agent/mcp/common.py,sha256=MpSC0fLO21RcDz4VApah4C8_LisVGz7OXkR17Xw-9mY,431
 mcp_agent/mcp/elicitation_factory.py,sha256=gY0gEsF8Jdg01nSsrVbbl62ZS1A725QgDRB6UDPCadc,3162
 mcp_agent/mcp/elicitation_handlers.py,sha256=w2S4kBn05pIKdq2-X13MErinFg5jSElwFsoTuW3zFSs,6618
 mcp_agent/mcp/gen_client.py,sha256=fAVwFVCgSamw4PwoWOV4wrK9TABx1S_zZv8BctRyF2k,3030
 mcp_agent/mcp/hf_auth.py,sha256=7szw4rkwRyK3J-sUTcVZHdwoLIZqlYo8XolJnZdjOww,4571
-mcp_agent/mcp/interfaces.py,sha256=Zrb-O-TuExlWJxuP0bIN8ZV0UpIoz5Rw7x1Lj-BsbHc,7717
+mcp_agent/mcp/interfaces.py,sha256=pe8WKvu3dnNnPWmrkDlu15xdkhuRDAjLUMn2vIE0Mj8,7963
 mcp_agent/mcp/logger_textio.py,sha256=vljC1BtNTCxBAda9ExqNB-FwVNUZIuJT3h1nWmCjMws,3172
 mcp_agent/mcp/mcp_agent_client_session.py,sha256=nEHrSalG5z47BKGwE9ooOmlSTc4Gb7qdEut071Dwepo,8987
 mcp_agent/mcp/mcp_aggregator.py,sha256=D1xFBVVq_4Tn1Ka16SZTVB3qeU-FO5501ITHGXTuXs0,49730
@@ -116,7 +119,7 @@ mcp_agent/mcp/prompt_render.py,sha256=k3v4BZDThGE2gGiOYVQtA6x8WTEdOuXIEnRafANhN1
 mcp_agent/mcp/prompt_serialization.py,sha256=MQY6QxnhQTiq0oBDsyRzFtX8sBiovUjzUFX78As8q60,17974
 mcp_agent/mcp/resource_utils.py,sha256=K4XY8bihmBMleRTZ2viMPiD2Y2HWxFnlgIJi6dd_PYE,6588
 mcp_agent/mcp/sampling.py,sha256=PpUtLDvu9K3U8445z6m_esHeKstdSr-JBTyn9d8ppJM,6665
-mcp_agent/mcp/helpers/__init__.py,sha256=sKqwlUR3jSsd9PVJKjXtxHgZA1YOdzPtsSW4xVey77Q,52
+mcp_agent/mcp/helpers/__init__.py,sha256=jJP_yVlewL0hePTX_k_MAnUmOzxpr0Tr_rXYZYeE2WY,456
 mcp_agent/mcp/helpers/content_helpers.py,sha256=_P5xfVpJg4F7lBM-v6-1Bjtvfgr9UfTQoW2FSxyxil4,4112
 mcp_agent/mcp/helpers/server_config_helpers.py,sha256=MkyZB2ZzfsBNsqyGd0LfUOoXxhAMS28VF-f747cJJpY,978
 mcp_agent/mcp/prompts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -162,8 +165,8 @@ mcp_agent/resources/examples/workflows/short_story.txt,sha256=X3y_1AyhLFN2AKzCKv
 mcp_agent/tools/tool_definition.py,sha256=L3Pxl-uLEXqlVoo-bYuFTFALeI-2pIU44YgFhsTKEtM,398
 mcp_agent/ui/console_display.py,sha256=cv-dvpJT7-zd7d8nqlcDLKfYg9_pDEQQOt7rGnDvj54,26057
 mcp_agent/ui/console_display_legacy.py,sha256=sm2v61-IPVafbF7uUaOyhO2tW_zgFWOjNS83IEWqGgI,14931
-fast_agent_mcp-0.2.45.dist-info/METADATA,sha256=xdue1zGI50YjprDUaZUnOlO4vW-S02iGdK6dKh5Cq74,31041
-fast_agent_mcp-0.2.45.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-fast_agent_mcp-0.2.45.dist-info/entry_points.txt,sha256=QaX5kLdI0VdMPRdPUF1nkG_WdLUTNjp_icW6e3EhNYU,232
-fast_agent_mcp-0.2.45.dist-info/licenses/LICENSE,sha256=Gx1L3axA4PnuK4FxsbX87jQ1opoOkSFfHHSytW6wLUU,10935
-fast_agent_mcp-0.2.45.dist-info/RECORD,,
+fast_agent_mcp-0.2.46.dist-info/METADATA,sha256=nJUU501B28wTMPXWrVCWA5Tgo7M_Eem1c_thiUB6aLM,31041
+fast_agent_mcp-0.2.46.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+fast_agent_mcp-0.2.46.dist-info/entry_points.txt,sha256=QaX5kLdI0VdMPRdPUF1nkG_WdLUTNjp_icW6e3EhNYU,232
+fast_agent_mcp-0.2.46.dist-info/licenses/LICENSE,sha256=Gx1L3axA4PnuK4FxsbX87jQ1opoOkSFfHHSytW6wLUU,10935
+fast_agent_mcp-0.2.46.dist-info/RECORD,,

mcp_agent/__init__.py

@@ -31,9 +31,32 @@ from mcp_agent.core.direct_decorators import (
 # FastAgent components
 from mcp_agent.core.fastagent import FastAgent
 
+# MCP content creation utilities
+from mcp_agent.core.mcp_content import (
+    Assistant,
+    MCPFile,
+    MCPImage,
+    MCPPrompt,
+    MCPText,
+    User,
+    create_message,
+)
+
 # Request configuration
 from mcp_agent.core.request_params import RequestParams
 
+# MCP content helpers
+from mcp_agent.mcp.helpers import (
+    get_image_data,
+    get_resource_text,
+    get_resource_uri,
+    get_text,
+    is_image_content,
+    is_resource_content,
+    is_resource_link,
+    is_text_content,
+)
+
 # Core protocol interfaces
 from mcp_agent.mcp.interfaces import AgentProtocol, AugmentedLLMProtocol
 from mcp_agent.mcp.mcp_aggregator import MCPAggregator
@@ -71,4 +94,21 @@ __all__ = [
     "evaluator_optimizer",
     # Request configuration
     "RequestParams",
+    # MCP content helpers
+    "get_text",
+    "get_image_data",
+    "get_resource_uri",
+    "is_text_content",
+    "is_image_content",
+    "is_resource_content",
+    "is_resource_link",
+    "get_resource_text",
+    # MCP content creation utilities
+    "MCPText",
+    "MCPImage",
+    "MCPFile",
+    "MCPPrompt",
+    "User",
+    "Assistant",
+    "create_message",
 ]

mcp_agent/cli/commands/go.py

@@ -259,8 +259,8 @@ def run_async_agent(
 def go(
     ctx: typer.Context,
     name: str = typer.Option("FastAgent CLI", "--name", help="Name for the agent"),
-    instruction: str = typer.Option(
-        "You are a helpful AI Agent.", "--instruction", "-i", help="Instruction for the agent"
+    instruction: Optional[str] = typer.Option(
+        None, "--instruction", "-i", help="Path to file or URL containing instruction for the agent"
     ),
     config_path: Optional[str] = typer.Option(
         None, "--config-path", "-c", help="Path to config file"
@@ -297,7 +297,8 @@ def go(
     Run an interactive agent directly from the command line.
 
     Examples:
-        fast-agent go --model=haiku --instruction="You are a coding assistant" --servers=fetch,filesystem
+        fast-agent go --model=haiku --instruction=./instruction.md --servers=fetch,filesystem
+        fast-agent go --instruction=https://raw.githubusercontent.com/user/repo/prompt.md
         fast-agent go --message="What is the weather today?" --model=haiku
         fast-agent go --prompt-file=my-prompt.txt --model=haiku
         fast-agent go --url=http://localhost:8001/mcp,http://api.example.com/sse
@@ -335,9 +336,29 @@ def go(
     if stdio:
         stdio_commands.append(stdio)
 
+    # Resolve instruction from file/URL or use default
+    resolved_instruction = "You are a helpful AI Agent."  # Default
+    if instruction:
+        try:
+            from pathlib import Path
+
+            from pydantic import AnyUrl
+
+            from mcp_agent.core.direct_decorators import _resolve_instruction
+
+            # Check if it's a URL
+            if instruction.startswith(("http://", "https://")):
+                resolved_instruction = _resolve_instruction(AnyUrl(instruction))
+            else:
+                # Treat as file path
+                resolved_instruction = _resolve_instruction(Path(instruction))
+        except Exception as e:
+            typer.echo(f"Error loading instruction from {instruction}: {e}", err=True)
+            raise typer.Exit(1)
+
     run_async_agent(
         name=name,
-        instruction=instruction,
+        instruction=resolved_instruction,
         config_path=config_path,
         servers=servers,
         urls=urls,

mcp_agent/core/__init__.py

@@ -0,0 +1,26 @@
+"""
+Core components and utilities for MCP Agent.
+"""
+
+from .mcp_content import (
+    Assistant,
+    MCPContentType,
+    MCPFile,
+    MCPImage,
+    MCPPrompt,
+    MCPText,
+    User,
+    create_message,
+)
+
+__all__ = [
+    # MCP content creation functions
+    "MCPText",
+    "MCPImage",
+    "MCPFile",
+    "MCPPrompt",
+    "User",
+    "Assistant",
+    "create_message",
+    "MCPContentType",
+]

mcp_agent/core/direct_decorators.py

@@ -6,6 +6,7 @@ for creating agents in the DirectFastAgent framework.
 
 import inspect
 from functools import wraps
+from pathlib import Path
 from typing import (
     Awaitable,
     Callable,
@@ -21,6 +22,7 @@ from typing import (
 )
 
 from mcp.client.session import ElicitationFnT
+from pydantic import AnyUrl
 
 from mcp_agent.agents.agent import AgentConfig
 from mcp_agent.agents.workflow.router_agent import (
@@ -85,6 +87,91 @@ class DecoratedEvaluatorOptimizerProtocol(DecoratedAgentProtocol[P, R], Protocol
     _evaluator: str
 
 
+def _fetch_url_content(url: str) -> str:
+    """
+    Fetch content from a URL.
+
+    Args:
+        url: The URL to fetch content from
+
+    Returns:
+        The text content from the URL
+
+    Raises:
+        requests.RequestException: If the URL cannot be fetched
+        UnicodeDecodeError: If the content cannot be decoded as UTF-8
+    """
+    import requests
+
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()  # Raise exception for HTTP errors
+    return response.text
+
+
+def _apply_templates(text: str) -> str:
+    """
+    Apply template substitutions to instruction text.
+
+    Supported templates:
+        {{currentDate}} - Current date in format "24 July 2025"
+        {{url:https://...}} - Content fetched from the specified URL
+
+    Args:
+        text: The text to process
+
+    Returns:
+        Text with template substitutions applied
+
+    Raises:
+        requests.RequestException: If a URL in {{url:...}} cannot be fetched
+        UnicodeDecodeError: If URL content cannot be decoded as UTF-8
+    """
+    import re
+    from datetime import datetime
+
+    # Apply {{currentDate}} template
+    current_date = datetime.now().strftime("%d %B %Y")
+    text = text.replace("{{currentDate}}", current_date)
+
+    # Apply {{url:...}} templates
+    url_pattern = re.compile(r"\{\{url:(https?://[^}]+)\}\}")
+
+    def replace_url(match):
+        url = match.group(1)
+        return _fetch_url_content(url)
+
+    text = url_pattern.sub(replace_url, text)
+
+    return text
+
+
+def _resolve_instruction(instruction: str | Path | AnyUrl) -> str:
+    """
+    Resolve instruction from either a string, Path, or URL with template support.
+
+    Args:
+        instruction: Either a string instruction, Path to a file, or URL containing the instruction
+
+    Returns:
+        The resolved instruction string with templates applied
+
+    Raises:
+        FileNotFoundError: If the Path doesn't exist
+        PermissionError: If the Path can't be read
+        UnicodeDecodeError: If the file/URL content can't be decoded as UTF-8
+        requests.RequestException: If the URL cannot be fetched
+    """
+    if isinstance(instruction, Path):
+        text = instruction.read_text(encoding="utf-8")
+    elif isinstance(instruction, AnyUrl):
+        text = _fetch_url_content(str(instruction))
+    else:
+        text = instruction
+
+    # Apply template substitutions
+    return _apply_templates(text)
+
+
 def _decorator_impl(
     self,
     agent_type: AgentType,
@@ -183,9 +270,9 @@ def _decorator_impl(
 def agent(
     self,
     name: str = "default",
-    instruction_or_kwarg: Optional[str] = None,
+    instruction_or_kwarg: Optional[str | Path | AnyUrl] = None,
     *,
-    instruction: str = "You are a helpful agent.",
+    instruction: str | Path | AnyUrl = "You are a helpful agent.",
     servers: List[str] = [],
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
@@ -220,7 +307,10 @@ def agent(
     Returns:
         A decorator that registers the agent with proper type annotations
     """
-    final_instruction = instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    final_instruction_raw = (
+        instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    )
+    final_instruction = _resolve_instruction(final_instruction_raw)
 
     return _decorator_impl(
         self,
@@ -245,9 +335,9 @@ def custom(
     self,
     cls,
     name: str = "default",
-    instruction_or_kwarg: Optional[str] = None,
+    instruction_or_kwarg: Optional[str | Path | AnyUrl] = None,
     *,
-    instruction: str = "You are a helpful agent.",
+    instruction: str | Path | AnyUrl = "You are a helpful agent.",
     servers: List[str] = [],
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
@@ -277,7 +367,10 @@ def custom(
     Returns:
         A decorator that registers the agent with proper type annotations
     """
-    final_instruction = instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    final_instruction_raw = (
+        instruction_or_kwarg if instruction_or_kwarg is not None else instruction
+    )
+    final_instruction = _resolve_instruction(final_instruction_raw)
 
     return _decorator_impl(
         self,
@@ -311,7 +404,7 @@ def orchestrator(
     name: str,
     *,
     agents: List[str],
-    instruction: str = DEFAULT_INSTRUCTION_ORCHESTRATOR,
+    instruction: str | Path | AnyUrl = DEFAULT_INSTRUCTION_ORCHESTRATOR,
     model: Optional[str] = None,
     request_params: RequestParams | None = None,
     use_history: bool = False,
@@ -341,6 +434,7 @@ def orchestrator(
     """
 
     # Create final request params with plan_iterations
+    resolved_instruction = _resolve_instruction(instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedOrchestratorProtocol[P, R]]",
@@ -348,7 +442,7 @@ def orchestrator(
             self,
             AgentType.ORCHESTRATOR,
             name=name,
-            instruction=instruction,
+            instruction=resolved_instruction,
             servers=[],  # Orchestrators don't connect to servers directly
             model=model,
             use_history=use_history,
@@ -368,7 +462,7 @@ def router(
     name: str,
     *,
     agents: List[str],
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     servers: List[str] = [],
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
@@ -400,6 +494,7 @@ def router(
     Returns:
         A decorator that registers the router with proper type annotations
     """
+    resolved_instruction = _resolve_instruction(instruction or ROUTING_SYSTEM_INSTRUCTION)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedRouterProtocol[P, R]]",
@@ -407,7 +502,7 @@ def router(
             self,
             AgentType.ROUTER,
             name=name,
-            instruction=instruction or ROUTING_SYSTEM_INSTRUCTION,
+            instruction=resolved_instruction,
             servers=servers,
             model=model,
             use_history=use_history,
@@ -429,7 +524,7 @@ def chain(
     name: str,
     *,
     sequence: List[str],
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     cumulative: bool = False,
     default: bool = False,
 ) -> Callable[[AgentCallable[P, R]], DecoratedChainProtocol[P, R]]:
@@ -456,6 +551,7 @@ def chain(
     You are a chain that processes requests through a series of specialized agents in sequence.
     Pass the output of each agent to the next agent in the chain.
     """
+    resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedChainProtocol[P, R]]",
@@ -463,7 +559,7 @@ def chain(
             self,
             AgentType.CHAIN,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             sequence=sequence,
             cumulative=cumulative,
             default=default,
@@ -477,7 +573,7 @@ def parallel(
     *,
     fan_out: List[str],
     fan_in: str | None = None,
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     include_request: bool = True,
     default: bool = False,
 ) -> Callable[[AgentCallable[P, R]], DecoratedParallelProtocol[P, R]]:
@@ -499,6 +595,7 @@ def parallel(
     You are a parallel processor that executes multiple agents simultaneously
     and aggregates their results.
     """
+    resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedParallelProtocol[P, R]]",
@@ -506,7 +603,7 @@ def parallel(
             self,
             AgentType.PARALLEL,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             servers=[],  # Parallel agents don't connect to servers directly
             fan_in=fan_in,
             fan_out=fan_out,
@@ -522,7 +619,7 @@ def evaluator_optimizer(
     *,
     generator: str,
     evaluator: str,
-    instruction: Optional[str] = None,
+    instruction: Optional[str | Path | AnyUrl] = None,
     min_rating: str = "GOOD",
     max_refinements: int = 3,
     default: bool = False,
@@ -547,6 +644,7 @@ def evaluator_optimizer(
     evaluated for quality, and then refined based on specific feedback until
     it reaches an acceptable quality standard.
     """
+    resolved_instruction = _resolve_instruction(instruction or default_instruction)
 
     return cast(
         "Callable[[AgentCallable[P, R]], DecoratedEvaluatorOptimizerProtocol[P, R]]",
@@ -554,7 +652,7 @@ def evaluator_optimizer(
             self,
             AgentType.EVALUATOR_OPTIMIZER,
             name=name,
-            instruction=instruction or default_instruction,
+            instruction=resolved_instruction,
             servers=[],  # Evaluator-optimizer doesn't connect to servers directly
             generator=generator,
             evaluator=evaluator,

mcp_agent/human_input/__init__.py

@@ -0,0 +1,50 @@
+"""Human input modules for forms and elicitation."""
+
+# Export the simple form API
+# Export field types and schema builder
+from mcp_agent.human_input.form_fields import (
+    BooleanField,
+    EnumField,
+    FormSchema,
+    IntegerField,
+    NumberField,
+    # Field classes
+    StringField,
+    boolean,
+    choice,
+    date,
+    datetime,
+    email,
+    integer,
+    number,
+    # Convenience functions
+    string,
+    url,
+)
+from mcp_agent.human_input.simple_form import ask, ask_sync, form, form_sync
+
+__all__ = [
+    # Form functions
+    "form",
+    "form_sync",
+    "ask",
+    "ask_sync",
+    # Schema builder
+    "FormSchema",
+    # Field classes
+    "StringField",
+    "IntegerField",
+    "NumberField",
+    "BooleanField",
+    "EnumField",
+    # Field convenience functions
+    "string",
+    "email",
+    "url",
+    "date",
+    "datetime",
+    "integer",
+    "number",
+    "boolean",
+    "choice",
+]

mcp_agent/human_input/form_fields.py

@@ -0,0 +1,252 @@
+"""High-level field types for elicitation forms with default support."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class StringField:
+    """String field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[str] = None
+    min_length: Optional[int] = None
+    max_length: Optional[int] = None
+    format: Optional[str] = None  # email, uri, date, date-time
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "string"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.min_length is not None:
+            schema["minLength"] = self.min_length
+        if self.max_length is not None:
+            schema["maxLength"] = self.max_length
+        if self.format:
+            schema["format"] = self.format
+
+        return schema
+
+
+@dataclass
+class IntegerField:
+    """Integer field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[int] = None
+    minimum: Optional[int] = None
+    maximum: Optional[int] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "integer"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.minimum is not None:
+            schema["minimum"] = self.minimum
+        if self.maximum is not None:
+            schema["maximum"] = self.maximum
+
+        return schema
+
+
+@dataclass
+class NumberField:
+    """Number (float) field with validation and default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[float] = None
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "number"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.minimum is not None:
+            schema["minimum"] = self.minimum
+        if self.maximum is not None:
+            schema["maximum"] = self.maximum
+
+        return schema
+
+
+@dataclass
+class BooleanField:
+    """Boolean field with default support."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[bool] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "boolean"}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+
+        return schema
+
+
+@dataclass
+class EnumField:
+    """Enum/choice field with default support."""
+
+    choices: List[str]
+    choice_names: Optional[List[str]] = None  # Human-readable names
+    title: Optional[str] = None
+    description: Optional[str] = None
+    default: Optional[str] = None
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP elicitation schema format."""
+        schema: Dict[str, Any] = {"type": "string", "enum": self.choices}
+
+        if self.title:
+            schema["title"] = self.title
+        if self.description:
+            schema["description"] = self.description
+        if self.default is not None:
+            schema["default"] = self.default
+        if self.choice_names:
+            schema["enumNames"] = self.choice_names
+
+        return schema
+
+
+# Field type union
+FieldType = Union[StringField, IntegerField, NumberField, BooleanField, EnumField]
+
+
+class FormSchema:
+    """High-level form schema builder."""
+
+    def __init__(self, **fields: FieldType):
+        """Create a form schema with named fields."""
+        self.fields = fields
+        self._required_fields: List[str] = []
+
+    def required(self, *field_names: str) -> "FormSchema":
+        """Mark fields as required."""
+        self._required_fields.extend(field_names)
+        return self
+
+    def to_schema(self) -> Dict[str, Any]:
+        """Convert to MCP ElicitRequestedSchema format."""
+        properties = {}
+
+        for field_name, field in self.fields.items():
+            properties[field_name] = field.to_schema()
+
+        schema: Dict[str, Any] = {"type": "object", "properties": properties}
+
+        if self._required_fields:
+            schema["required"] = self._required_fields
+
+        return schema
+
+
+# Convenience functions for creating fields
+def string(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[str] = None,
+    min_length: Optional[int] = None,
+    max_length: Optional[int] = None,
+    format: Optional[str] = None,
+) -> StringField:
+    """Create a string field."""
+    return StringField(title, description, default, min_length, max_length, format)
+
+
+def email(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create an email field."""
+    return StringField(title, description, default, format="email")
+
+
+def url(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a URL field."""
+    return StringField(title, description, default, format="uri")
+
+
+def date(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a date field."""
+    return StringField(title, description, default, format="date")
+
+
+def datetime(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[str] = None
+) -> StringField:
+    """Create a datetime field."""
+    return StringField(title, description, default, format="date-time")
+
+
+def integer(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[int] = None,
+    minimum: Optional[int] = None,
+    maximum: Optional[int] = None,
+) -> IntegerField:
+    """Create an integer field."""
+    return IntegerField(title, description, default, minimum, maximum)
+
+
+def number(
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[float] = None,
+    minimum: Optional[float] = None,
+    maximum: Optional[float] = None,
+) -> NumberField:
+    """Create a number field."""
+    return NumberField(title, description, default, minimum, maximum)
+
+
+def boolean(
+    title: Optional[str] = None, description: Optional[str] = None, default: Optional[bool] = None
+) -> BooleanField:
+    """Create a boolean field."""
+    return BooleanField(title, description, default)
+
+
+def choice(
+    choices: List[str],
+    choice_names: Optional[List[str]] = None,
+    title: Optional[str] = None,
+    description: Optional[str] = None,
+    default: Optional[str] = None,
+) -> EnumField:
+    """Create a choice/enum field."""
+    return EnumField(choices, choice_names, title, description, default)

mcp_agent/human_input/simple_form.py

@@ -0,0 +1,111 @@
+"""Simple form API for elicitation schemas without MCP wrappers."""
+
+import asyncio
+from typing import Any, Dict, Optional, Union
+
+from mcp.types import ElicitRequestedSchema
+
+from mcp_agent.human_input.elicitation_form import show_simple_elicitation_form
+from mcp_agent.human_input.form_fields import FormSchema
+
+
+async def form(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please fill out the form",
+    title: str = "Form Input",
+) -> Optional[Dict[str, Any]]:
+    """
+    Simple form API that presents an elicitation form and returns results.
+
+    Args:
+        schema: FormSchema, ElicitRequestedSchema, or dict schema
+        message: Message to display to the user
+        title: Title for the form (used as agent_name)
+
+    Returns:
+        Dict with form data if accepted, None if cancelled/declined
+
+    Example:
+        from mcp_agent.human_input.form_fields import FormSchema, string, email, integer
+
+        schema = FormSchema(
+            name=string("Name", "Your full name", min_length=2),
+            email=email("Email", "Your email address"),
+            age=integer("Age", "Your age", minimum=0, maximum=120)
+        ).required("name", "email")
+
+        result = await form(schema, "Please enter your information")
+        if result:
+            print(f"Name: {result['name']}, Email: {result['email']}")
+    """
+    # Convert schema to ElicitRequestedSchema format
+    if isinstance(schema, FormSchema):
+        elicit_schema = schema.to_schema()
+    elif isinstance(schema, dict):
+        elicit_schema = schema
+    else:
+        elicit_schema = schema
+
+    # Show the form
+    action, result = await show_simple_elicitation_form(
+        schema=elicit_schema, message=message, agent_name=title, server_name="SimpleForm"
+    )
+
+    # Return results based on action
+    if action == "accept":
+        return result
+    else:
+        return None
+
+
+def form_sync(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please fill out the form",
+    title: str = "Form Input",
+) -> Optional[Dict[str, Any]]:
+    """
+    Synchronous wrapper for the form function.
+
+    Args:
+        schema: FormSchema, ElicitRequestedSchema, or dict schema
+        message: Message to display to the user
+        title: Title for the form (used as agent_name)
+
+    Returns:
+        Dict with form data if accepted, None if cancelled/declined
+    """
+    return asyncio.run(form(schema, message, title))
+
+
+# Convenience function with a shorter name
+async def ask(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please provide the requested information",
+) -> Optional[Dict[str, Any]]:
+    """
+    Short alias for form() function.
+
+    Example:
+        from mcp_agent.human_input.form_fields import FormSchema, string, email
+
+        schema = FormSchema(
+            name=string("Name", "Your name"),
+            email=email("Email", "Your email")
+        ).required("name")
+
+        result = await ask(schema, "What's your info?")
+    """
+    return await form(schema, message)
+
+
+def ask_sync(
+    schema: Union[FormSchema, ElicitRequestedSchema, Dict[str, Any]],
+    message: str = "Please provide the requested information",
+) -> Optional[Dict[str, Any]]:
+    """
+    Synchronous version of ask().
+
+    Example:
+        result = ask_sync(schema, "What's your info?")
+    """
+    return form_sync(schema, message)

mcp_agent/llm/augmented_llm.py

@@ -9,6 +9,7 @@ from typing import (
     Tuple,
     Type,
     TypeVar,
+    Union,
     cast,
 )
 
@@ -203,7 +204,7 @@ class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT
 
     async def generate(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         request_params: RequestParams | None = None,
     ) -> PromptMessageMultipart:
         """
@@ -212,6 +213,10 @@ class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT
         # note - check changes here are mirrored in structured(). i've thought hard about
         # a strategy to reduce duplication etc, but aiming for simple but imperfect for the moment
 
+        # Convert PromptMessage to PromptMessageMultipart if needed
+        if multipart_messages and isinstance(multipart_messages[0], PromptMessage):
+            multipart_messages = PromptMessageMultipart.to_multipart(multipart_messages)
+
         # TODO -- create a "fast-agent" control role rather than magic strings
 
         if multipart_messages[-1].first_text().startswith("***SAVE_HISTORY"):
@@ -259,12 +264,16 @@ class AugmentedLLM(ContextDependent, AugmentedLLMProtocol, Generic[MessageParamT
 
     async def structured(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         model: Type[ModelT],
         request_params: RequestParams | None = None,
     ) -> Tuple[ModelT | None, PromptMessageMultipart]:
         """Return a structured response from the LLM using the provided messages."""
 
+        # Convert PromptMessage to PromptMessageMultipart if needed
+        if multipart_messages and isinstance(multipart_messages[0], PromptMessage):
+            multipart_messages = PromptMessageMultipart.to_multipart(multipart_messages)
+
         self._precall(multipart_messages)
         result, assistant_response = await self._apply_prompt_provider_specific_structured(
             multipart_messages, model, request_params

mcp_agent/llm/augmented_llm_playback.py

@@ -1,4 +1,6 @@
-from typing import Any, List, Type
+from typing import Any, List, Type, Union
+
+from mcp.types import PromptMessage
 
 from mcp_agent.core.exceptions import ModelConfigError
 from mcp_agent.core.prompt import Prompt
@@ -51,7 +53,7 @@ class PlaybackLLM(PassthroughLLM):
 
     async def generate(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         request_params: RequestParams | None = None,
     ) -> PromptMessageMultipart:
         """
@@ -106,7 +108,7 @@ class PlaybackLLM(PassthroughLLM):
 
     async def structured(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         model: Type[ModelT],
         request_params: RequestParams | None = None,
     ) -> tuple[ModelT | None, PromptMessageMultipart]:

mcp_agent/mcp/__init__.py

@@ -0,0 +1,50 @@
+"""
+MCP (Model Context Protocol) integration components.
+"""
+
+from mcp.types import PromptMessage
+
+from .helpers import (
+    get_image_data,
+    get_resource_text,
+    get_resource_uri,
+    get_text,
+    is_image_content,
+    is_resource_content,
+    is_resource_link,
+    is_text_content,
+)
+from .interfaces import (
+    AgentProtocol,
+    AugmentedLLMProtocol,
+    MCPConnectionManagerProtocol,
+    ModelFactoryClassProtocol,
+    ModelT,
+    ServerConnection,
+    ServerRegistryProtocol,
+)
+from .prompt_message_multipart import PromptMessageMultipart
+
+__all__ = [
+    # Types from mcp.types
+    "PromptMessage",
+    # Multipart message handling
+    "PromptMessageMultipart",
+    # Protocol interfaces
+    "AugmentedLLMProtocol",
+    "AgentProtocol",
+    "MCPConnectionManagerProtocol",
+    "ServerRegistryProtocol",
+    "ServerConnection",
+    "ModelFactoryClassProtocol",
+    "ModelT",
+    # Helper functions
+    "get_text",
+    "get_image_data",
+    "get_resource_uri",
+    "is_text_content",
+    "is_image_content",
+    "is_resource_content",
+    "is_resource_link",
+    "get_resource_text",
+]

mcp_agent/mcp/helpers/__init__.py

@@ -1,3 +1,25 @@
 """
 Helper modules for working with MCP content.
-"""
+"""
+
+from .content_helpers import (
+    get_image_data,
+    get_resource_text,
+    get_resource_uri,
+    get_text,
+    is_image_content,
+    is_resource_content,
+    is_resource_link,
+    is_text_content,
+)
+
+__all__ = [
+    "get_text",
+    "get_image_data",
+    "get_resource_uri",
+    "is_text_content",
+    "is_image_content",
+    "is_resource_content",
+    "is_resource_link",
+    "get_resource_text",
+]

mcp_agent/mcp/interfaces.py

@@ -36,6 +36,17 @@ if TYPE_CHECKING:
     from mcp_agent.llm.usage_tracking import UsageAccumulator
 
 
+__all__ = [
+    "MCPConnectionManagerProtocol",
+    "ServerRegistryProtocol",
+    "ServerConnection",
+    "AugmentedLLMProtocol",
+    "AgentProtocol",
+    "ModelFactoryClassProtocol",
+    "ModelT",
+]
+
+
 @runtime_checkable
 class MCPConnectionManagerProtocol(Protocol):
     """Protocol for MCPConnectionManager functionality needed by ServerRegistry."""
@@ -101,7 +112,7 @@ class AugmentedLLMProtocol(Protocol):
 
     async def structured(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         model: Type[ModelT],
         request_params: RequestParams | None = None,
     ) -> Tuple[ModelT | None, PromptMessageMultipart]:
@@ -110,7 +121,7 @@ class AugmentedLLMProtocol(Protocol):
 
     async def generate(
         self,
-        multipart_messages: List[PromptMessageMultipart],
+        multipart_messages: List[Union[PromptMessageMultipart, PromptMessage]],
         request_params: RequestParams | None = None,
     ) -> PromptMessageMultipart:
         """