fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/resources/examples/tensorzero/simple_agent.py

@@ -0,0 +1,25 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+CONFIG_FILE = "fastagent.config.yaml"
+fast = FastAgent("fast-agent example", config_path=CONFIG_FILE, ignore_unknown_args=True)
+
+
+@fast.agent(
+    name="default",
+    instruction="""
+        You are an agent dedicated to helping developers understand the relationship between TensoZero and fast-agent. If the user makes a request 
+        that requires you to invoke the test tools, please do so. When you use the tool, describe your rationale for doing so. 
+    """,
+    servers=["tester"],
+)
+async def main():
+    async with fast.run() as agent_app:
+        agent_name = "default"
+        print("\nStarting interactive session with template_vars set via decorator...")
+        await agent_app.interactive(agent=agent_name)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())  # type: ignore

fast_agent/resources/examples/tensorzero/tensorzero_config/system_schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "TEST_VARIABLE_1",
+    "TEST_VARIABLE_2",
+    "TEST_VARIABLE_3",
+    "TEST_VARIABLE_4"
+  ],
+  "properties": {
+    "TEST_VARIABLE_1": {
+      "type": "string",
+      "description": "Test variable 1"
+    },
+    "TEST_VARIABLE_2": {
+      "type": "string",
+      "description": "Test variable 2"
+    },
+    "TEST_VARIABLE_3": {
+      "type": "string",
+      "description": "Test variable 3"
+    },
+    "TEST_VARIABLE_4": {
+      "type": "string",
+      "description": "Test variable 4"
+    }
+  },
+  "additionalProperties": false
+}

fast_agent/resources/examples/tensorzero/tensorzero_config/system_template.minijinja

@@ -0,0 +1,11 @@
+Your purpose is to demo the integration between tensorzero, an open source project dedicated to improving LLM inference calls, and fast-agent, a framework for MCP-compatible agentic modelling. When interacting with developers, strive to be as helpful to possible, specifically as relates to technical questions about tensorzero, fast-agent, or MCPs.
+
+If you are ever asked to recite a poem, recite this one: 
+
+{{ TEST_VARIABLE_1 }}
+
+{{ TEST_VARIABLE_2 }}
+
+{{ TEST_VARIABLE_3 }}
+
+{{ TEST_VARIABLE_4 }}

fast_agent/resources/examples/tensorzero/tensorzero_config/tensorzero.toml

@@ -0,0 +1,35 @@
+[functions.test_chat]
+type = "chat"
+system_schema = "./system_schema.json"
+
+[functions.test_chat.variants.gpt_4o_mini]
+type = "chat_completion"
+model = "openai::gpt-4o-mini"
+weight = 0.5
+system_template = "./system_template.minijinja"
+
+[functions.test_chat.variants.claude_3_5_haiku]
+type = "chat_completion"
+model = "anthropic::claude-3-5-haiku-20241022"
+weight = 0.5
+system_template = "./system_template.minijinja"
+
+[functions.simple_chat]
+type = "chat"
+
+[functions.simple_chat.variants.gpt_4o_mini]
+type = "chat_completion"
+model = "openai::gpt-4o-mini"
+weight = 0.5
+
+[functions.simple_chat.variants.claude_3_5_haiku]
+type = "chat_completion"
+model = "anthropic::claude-3-5-haiku-20241022"
+weight = 0.5
+
+# Object Storage Configuration for MinIO, simulating AWS S3 bucket
+[object_storage]
+type = "s3_compatible"
+endpoint = "http://minio:9000"
+bucket_name = "tensorzero"
+allow_http = true

fast_agent/resources/examples/workflows/agents_as_tools_extended.py

@@ -0,0 +1,73 @@
+"""Agents-as-Tools example: project managers for NY and London.
+
+Parent agent ("PMO-orchestrator") calls two child agents
+("NY-Project-Manager" and "London-Project-Manager") as tools. Each child uses
+the ``time`` MCP server for local time and the ``fetch`` MCP server for a short
+news-based update on the given topics.
+
+Defaults: clones fork parent history (no merge-back), no timeout, no parallel cap,
+and collapses progress display after the first 20 instances.
+To change behavior, pass decorator args such as
+`history_mode=HistoryMode.FORK_AND_MERGE`, `child_timeout_sec=600`,
+`max_parallel=8`, `max_display_instances=10`
+(HistoryMode import: fast_agent.agents.workflow.agents_as_tools_agent).
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Agents-as-Tools demo")
+
+
+@fast.agent(
+    name="NY-Project-Manager",
+    instruction=(
+        "You are a New York project manager. For each given topic, get the "
+        "current local time in New York and a brief, project-relevant news "
+        "summary using the 'time' and 'fetch' MCP servers. If a source returns "
+        "HTTP 403 or is blocked by robots.txt, try up to five alternative "
+        "public sources before giving up and clearly state any remaining "
+        "access limits. Hint: Fast-Agent site: https://fast-agent.ai"
+    ),
+    servers=[
+        "time",
+        "fetch",
+    ],  # MCP servers 'time' and 'fetch' configured in fastagent.config.yaml
+)
+@fast.agent(
+    name="London-Project-Manager",
+    instruction=(
+        "You are a London project manager. For each given topic, get the "
+        "current local time in London and a brief, project-relevant news "
+        "summary using the 'time' and 'fetch' MCP servers. If a source returns "
+        "HTTP 403 or is blocked by robots.txt, try up to five alternative "
+        "public sources before giving up and clearly state any remaining "
+        "access limits. Hint: BBC: https://www.bbc.com/ and FT: https://www.ft.com/"
+    ),
+    servers=["time", "fetch"],
+)
+@fast.agent(
+    name="PMO-orchestrator",
+    instruction=(
+        "Get project updates from the New York and London project managers. "
+        "Ask NY-Project-Manager three times about different projects: Anthropic, "
+        "evalstate/fast-agent, and OpenAI, and London-Project-Manager for economics review. "
+        "Return a brief, concise combined summary with clear city/time/topic labels."
+    ),
+    default=True,
+    agents=[
+        "NY-Project-Manager",
+        "London-Project-Manager",
+    ],  # children are exposed as tools: agent__NY-Project-Manager, agent__London-Project-Manager
+    # optional: history_mode="fork_and_merge", child_timeout_sec=600, max_parallel=8, max_display_instances=10
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        result = await agent("pls send me daily review.")
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/agents_as_tools_simple.py

@@ -0,0 +1,50 @@
+"""Simple Agents-as-Tools PMO example.
+
+Parent agent ("PMO-orchestrator") calls two child agents ("NY-Project-Manager"
+and "London-Project-Manager") as tools. Each child uses the ``time`` MCP
+server to include local time in a brief report.
+
+Defaults: clones fork parent history (no merge-back), no timeout, no parallel cap,
+and collapses progress display after the first 20 instances.
+If you want merge-back or other limits, pass decorator args:
+`history_mode=HistoryMode.FORK_AND_MERGE`, `child_timeout_sec=600`,
+`max_parallel=8`, `max_display_instances=10`
+(HistoryMode import: fast_agent.agents.workflow.agents_as_tools_agent).
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+fast = FastAgent("Agents-as-Tools simple demo")
+
+
+@fast.agent(
+    name="NY-Project-Manager",
+    instruction="Return current time and project status.",
+    servers=["time"],  # MCP server 'time' configured in fastagent.config.yaml
+)
+@fast.agent(
+    name="London-Project-Manager",
+    instruction="Return current time and news.",
+    servers=["time"],
+)
+@fast.agent(
+    name="PMO-orchestrator",
+    instruction="Get reports. Separate call per topic. NY: {OpenAI, Fast-Agent, Anthropic}, London: Economics",
+    default=True,
+    agents=[
+        "NY-Project-Manager",
+        "London-Project-Manager",
+    ],  # children are exposed as tools: agent__NY-Project-Manager, agent__London-Project-Manager
+    # optional: history_mode="fork_and_merge", child_timeout_sec=600, max_parallel=8, max_display_instances=10
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        result = await agent("Get PMO report")
+        await agent.interactive()
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/chaining.py

@@ -0,0 +1,37 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Agent Chaining")
+
+
+@fast.agent(
+    "url_fetcher",
+    instruction="Given a URL, provide a complete and comprehensive summary",
+    servers=["fetch"],
+)
+@fast.agent(
+    "social_media",
+    instruction="""
+    Write a 280 character social media post for any given text. 
+    Respond only with the post, never use hashtags.
+    """,
+)
+@fast.chain(
+    name="post_writer",
+    sequence=["url_fetcher", "social_media"],
+    default=True,
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        # using chain workflow
+        await agent.post_writer.send("https://llmindset.co.uk")
+
+
+# alternative syntax for above is result = agent["post_writer"].send(message)
+# alternative syntax for above is result = agent["post_writer"].prompt()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/evaluator.py

@@ -0,0 +1,77 @@
+"""
+This demonstrates creating an optimizer and evaluator to iteratively improve content.
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Evaluator-Optimizer")
+
+
+# Define generator agent
+@fast.agent(
+    name="generator",
+    instruction="""You are a career coach specializing in cover letter writing.
+    You are tasked with generating a compelling cover letter given the job posting,
+    candidate details, and company information. Tailor the response to the company and job requirements.
+    """,
+    servers=["fetch"],
+    model="gpt-5-nano.low",
+    use_history=True,
+)
+# Define evaluator agent
+@fast.agent(
+    name="evaluator",
+    instruction="""Evaluate the following response based on the criteria below:
+    1. Clarity: Is the language clear, concise, and grammatically correct?
+    2. Specificity: Does the response include relevant and concrete details tailored to the job description?
+    3. Relevance: Does the response align with the prompt and avoid unnecessary information?
+    4. Tone and Style: Is the tone professional and appropriate for the context?
+    5. Persuasiveness: Does the response effectively highlight the candidate's value?
+    6. Grammar and Mechanics: Are there any spelling or grammatical issues?
+    7. Feedback Alignment: Has the response addressed feedback from previous iterations?
+
+    For each criterion:
+    - Provide a rating (EXCELLENT, GOOD, FAIR, or POOR).
+    - Offer specific feedback or suggestions for improvement.
+
+    Summarize your evaluation as a structured response with:
+    - Overall quality rating.
+    - Specific feedback and areas for improvement.""",
+    model="o3-mini.medium",
+)
+# Define the evaluator-optimizer workflow
+@fast.evaluator_optimizer(
+    name="cover_letter_writer",
+    generator="generator",  # Reference to generator agent
+    evaluator="evaluator",  # Reference to evaluator agent
+    min_rating="EXCELLENT",  # Strive for excellence
+    max_refinements=3,  # Maximum iterations
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        job_posting = (
+            "Software Engineer at LastMile AI. Responsibilities include developing AI systems, "
+            "collaborating with cross-functional teams, and enhancing scalability. Skills required: "
+            "Python, distributed systems, and machine learning."
+        )
+        candidate_details = (
+            "Alex Johnson, 3 years in machine learning, contributor to open-source AI projects, "
+            "proficient in Python and TensorFlow. Motivated by building scalable AI systems to solve real-world problems."
+        )
+        company_information = (
+            "Look up from the LastMile AI About page: https://lastmileai.dev/about"
+        )
+
+        # Send the task
+        await agent.cover_letter_writer.send(
+            f"Write a cover letter for the following job posting: {job_posting}\n\n"
+            f"Candidate Details: {candidate_details}\n\n"
+            f"Company information: {company_information}",
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/fastagent.config.yaml

@@ -0,0 +1,26 @@
+# Please edit this configuration file to match your environment (on Windows).
+# Examples in comments below - check/change the paths.
+#
+#
+
+logger:
+  type: file
+  level: error
+  truncate_tools: true
+
+mcp:
+  servers:
+    filesystem:
+      # On windows update the command and arguments to use `node` and the absolute path to the server.
+      # Use `npm i -g @modelcontextprotocol/server-filesystem` to install the server globally.
+      # Use `npm -g root` to find the global node_modules path.`
+      # command: "node"
+      # args: ["c:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js","."]
+      command: "npx"
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    fetch:
+      command: "uvx"
+      args: ["mcp-server-fetch"]
+    time:
+      command: "uvx"
+      args: ["mcp-server-time"]

fast_agent/resources/examples/workflows/graded_report.md

@@ -0,0 +1,89 @@
+# Graded Report: "The Kittens Castle Adventure"
+
+## Proofreading Feedback
+
+### Spelling Errors
+1. "Adventuer" → "Adventure"
+2. "lil" → "little"
+3. "name" → "named"
+4. "threw" → "through"
+5. "mystirus" → "mysterious"
+6. "forrest" → "forest"
+7. "was" → "were"
+8. "an" → "and"
+9. "Suddenlee" → "Suddenly"
+10. "sawd" → "saw"
+11. "somthing" → "something"
+12. "chese" → "cheese"
+13. "windos" → "windows"
+14. "turrits" → "turrets"
+15. "tuch" → "touch"
+16. "clowds" → "clouds"
+17. "doars" → "doors"
+18. "enuff" → "enough"
+19. "elefant" → "elephant"
+20. "sed" → "said"
+21. "tale" → "tail"
+22. "poofy" → "puffy"
+23. "fowned" → "found"
+24. "meowed" → added missing period
+25. "smallist" → "smallest"
+26. "rond" → "round"
+27. "climed" → "climbed"
+28. "slip-slidin" → "slip-sliding"
+29. "smoth" → "smooth"
+30. "surfase" → "surface"
+31. "ful" → "full"
+32. "dangling" → added missing period
+33. "JINGEL" → "jingle"
+34. "paradyse" → "paradise"
+35. "figur" → "figure"
+36. "gaurd" → "guard"
+37. "sumthing" → "something"
+38. "mor" → "more"
+39. "hudeld" → "huddled"
+40. "togethar" → "together"
+41. "there" → "their"
+42. "happan" → "happen"
+43. "amazeing" → "amazing"
+
+### Grammar and Syntax Errors
+1. Inconsistent verb tenses throughout the story
+2. Improper use of articles (a/an)
+3. Missing punctuation
+4. Lack of subject-verb agreement
+5. Incorrect capitalization
+
+### Style and Formatting Recommendations
+1. Use standard capitalization for proper nouns
+2. Maintain consistent verb tense (past tense recommended)
+3. Use proper punctuation
+4. Avoid excessive use of exclamation points
+5. Use standard spelling for all words
+
+## Factuality and Logical Consistency
+- The story is a fictional narrative about three kittens, so traditional factual constraints do not strictly apply
+- The narrative maintains internal logical consistency
+- The cliffhanger ending leaves room for imagination
+
+## Style Adherence
+### APA Formatting Guidelines
+- Title should be centered and in title case
+- Use 12-point Times New Roman font (not applicable in markdown)
+- Double-spacing recommended (not applicable in markdown)
+- 1-inch margins (not applicable in markdown)
+
+### Recommendations for Improvement
+1. Proofread and correct all spelling errors
+2. Maintain consistent grammar and syntax
+3. Use standard English spelling
+4. Add more descriptive language
+5. Develop a more structured narrative arc
+
+## Overall Assessment
+**Writing Quality**: Needs Significant Improvement
+**Creativity**: Excellent
+**Potential**: High
+
+### Suggested Revision
+Revise the text to correct spelling, grammar, and syntax while preserving the original creative narrative and imaginative elements.

fast_agent/resources/examples/workflows/human_input.py

@@ -0,0 +1,28 @@
+"""
+Agent which demonstrates Human Input tool
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+# Create the application
+fast = FastAgent("Human Input")
+
+
+# Define the agent
+@fast.agent(
+    instruction="An AI agent that assists with basic tasks. Request Human Input when needed - for example"
+    "if being asked to predict a number sequence or pretending to take pizza orders.",
+    human_input=True,
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        # this usually causes the LLM to request the Human Input Tool
+        await agent("print the next number in the sequence")
+        await agent("pretend to be a pizza restaurant and take the users order")
+        await agent.interactive(default_prompt="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/workflows/maker.py

@@ -0,0 +1,156 @@
+"""
+MAKER: Massively decomposed Agentic processes with K-voting Error Reduction.
+
+This example demonstrates the MAKER workflow pattern for achieving high
+reliability through statistical consensus voting.
+
+Based on the paper:
+    "Solving a Million-Step LLM Task with Zero Errors"
+    Meyerson et al., 2024
+    https://arxiv.org/abs/2511.09030
+
+Key Concepts:
+-------------
+1. **First-to-ahead-by-k Voting**: Multiple samples are drawn from a worker
+   agent. The first response to achieve a k-vote margin over all alternatives
+   wins. This provides provable error bounds.
+
+2. **Red-Flagging**: Responses that show signs of confusion (too long,
+   malformed) are discarded before voting, improving effective success rate.
+
+3. **Cost-Effective Reliability**: By trading compute (multiple samples) for
+   accuracy (statistical consensus), cheap models can achieve high reliability.
+
+When to Use MAKER:
+------------------
+MAKER is designed for **long chains of simple steps** where errors compound:
+
+Good use cases:
+- **ETL pipelines**: 1000s of row transformations - one bad parse = corrupted data
+- **Code migration**: 1000s of file changes - one syntax error = build fails
+- **Document processing**: 1000s of pages - one missed field = compliance failure
+- **Data validation**: Millions of records - one wrong validation = bad data in prod
+- **Automated testing**: 1000s of assertions - one false positive = wasted debugging
+- **Cost optimization**: Cheap model + voting can replace expensive model
+
+When NOT to use MAKER:
+- Single classifications (just use a good model - 95% accuracy is fine)
+- Creative/open-ended tasks (no "correct" answer to vote on)
+- Complex reasoning (need smarter model, not more samples)
+- Tasks where occasional errors are acceptable
+
+The Math:
+---------
+- 95% per-step accuracy over 100 steps = 0.6% overall success (0.95^100)
+- 99.9% per-step accuracy (with MAKER) over 100 steps = 90% overall success
+- For million-step tasks, even 99% per-step fails; MAKER enables 99.99%+
+
+Demo Use Case:
+--------------
+This example shows customer message intent classification. While modern LLMs
+are quite consistent on this task (you'll see 3:0 votes), the mechanism
+demonstrates how voting works. In production with harder tasks or longer
+chains, MAKER's value becomes critical.
+
+Usage:
+------
+    uv run examples/workflows/maker.py
+
+Try modifying k (voting margin) and observe how it affects reliability vs cost.
+"""
+
+import asyncio
+
+from fast_agent import FastAgent
+
+fast = FastAgent("MAKER Example")
+
+
+# Define a classifier using a cheap model (Haiku) - may give inconsistent results
+# on ambiguous messages, which is why we wrap it with MAKER for reliability
+@fast.agent(
+    name="classifier",
+    model="claude-3-haiku-20240307", 
+    instruction="""You are a customer support intent classifier.
+Classify the customer message into exactly one of: COMPLAINT, QUESTION, REQUEST, FEEDBACK.
+Respond with ONLY the single word classification, nothing else.
+
+Examples:
+- "This product is broken!" → COMPLAINT
+- "How do I reset my password?" → QUESTION
+- "Please cancel my subscription" → REQUEST
+- "Just wanted to say I love the new feature" → FEEDBACK""",
+)
+# Wrap with MAKER for reliable, consistent classification
+@fast.maker(
+    name="reliable_classifier",
+    worker="classifier",
+    k=3,  # Require 3-vote margin for consensus
+    max_samples=10,  # Max attempts before falling back to plurality
+    match_strategy="normalized",  # Ignore case/whitespace differences
+    red_flag_max_length=20,  # Discard verbose responses (should be one word)
+)
+async def main():
+    """Demonstrate MAKER voting for reliable intent classification."""
+    async with fast.run() as agent:
+        print("=" * 70)
+        print("MAKER: Massively decomposed Agentic processes")
+        print("       with K-voting Error Reduction")
+        print("=" * 70)
+        print()
+        print("This example classifies customer messages where intent is ambiguous.")
+        print("MAKER voting ensures consistent routing even for edge cases.")
+        print()
+
+        # Ambiguous customer messages where intent is unclear
+        test_cases = [
+            "I've been waiting for 3 days now.",              # Complaint? Status question?
+            "Can someone explain how this works?",            # Question? Request for help?
+            "This isn't what I expected.",                    # Complaint? Feedback?
+            "I'd like to speak to a manager.",                # Complaint? Request?
+            "Why does this keep happening?",                  # Complaint? Question?
+            "Just wanted to let you know about this.",        # Feedback? Complaint?
+            "Is there any way to get a refund?",              # Question? Request?
+            "The new update changed everything.",             # Complaint? Feedback?
+        ]
+
+        # Collect all results first
+        results = []
+        for text in test_cases:
+            result = await agent.reliable_classifier.send(text)
+            stats = agent.reliable_classifier.last_result
+            results.append((text, result, stats))
+
+        # Display all results together
+        print("-" * 70)
+        print(f"{'Text':<50} {'Result':<10} {'Samples':<8} {'Votes'}")
+        print("-" * 70)
+
+        for text, result, stats in results:
+            votes_str = ""
+            samples = ""
+            if stats:
+                votes_str = ", ".join(f"{k}:{v}" for k, v in stats.votes.items())
+                samples = str(stats.total_samples)
+
+            print(f"{text:<50} {result:<10} {samples:<8} {votes_str}")
+
+        print("-" * 70)
+        print()
+        print("Notice how MAKER provides consistent routing decisions even for")
+        print("ambiguous messages by voting across multiple samples.")
+        print()
+
+        # Summary statistics
+        total_samples = sum(r[2].total_samples for r in results if r[2])
+        all_converged = all(r[2].converged for r in results if r[2])
+        print("Summary:")
+        print(f"  - Total API calls: {total_samples}")
+        print(f"  - All converged: {all_converged}")
+        print(f"  - Texts classified: {len(results)}")
+        print()
+        print("=" * 70)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())