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

fast_agent/resources/examples/researcher/researcher-imp.py

@@ -0,0 +1,189 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+agents = FastAgent(name="Enhanced Researcher")
+
+
+@agents.agent(
+    name="ResearchPlanner",
+    model="sonnet",  # Using a more capable model for planning
+    instruction="""
+You are a strategic research planner. Your job is to:
+1. Break down complex research questions into specific sub-questions
+2. Identify the key information sources needed to answer each sub-question
+3. Outline a structured research plan
+
+When given a research topic:
+- Analyze what is being asked and identify the core components
+- Define 3-5 specific sub-questions that need to be answered
+- For each sub-question, suggest specific search queries and information sources
+- Prioritize the most important areas to investigate first
+- Include suggestions for data visualization or analysis if appropriate
+
+Your output should be a clear, structured research plan that the Researcher can follow.
+""",
+    servers=["brave"],
+)
+@agents.agent(
+    name="Researcher",
+    model="sonnet",  # Using a more capable model for deep research
+    instruction="""
+You are an expert research assistant with access to multiple resources:
+- Brave Search for initial exploration and discovering sources
+- Website fetching to read and extract information directly from webpages
+- Python interpreter for data analysis and visualization
+- Filesystem tools to save and organize your findings
+
+RESEARCH METHODOLOGY:
+1. First understand the research plan provided
+2. For each sub-question, use search tools to find multiple relevant sources
+3. Go beyond surface-level information by:
+   - Consulting primary sources when possible
+   - Cross-referencing information across multiple sources
+   - Using the fetch tool to access complete articles rather than just search snippets
+   - Analyzing data with Python when numerical evidence is needed
+   - Creating visualizations when they help clarify complex information
+
+CRITICAL INFORMATION ASSESSMENT:
+- Evaluate the credibility of each source (consider recency, authority, potential bias)
+- Look for consensus across multiple sources
+- Highlight any contradictions or areas of debate in the research
+- Clearly state limitations in the available information
+
+DOCUMENTATION:
+- Save important information, data, and visualizations to files
+- Always create a comprehensive bibliography with links to all sources
+- Include specific citation details (author, date, publication) when available
+- Note which specific information came from which source
+
+FINAL RESPONSE:
+- Structure your findings logically with clear headings
+- Synthesize the information rather than just listing facts
+- Directly address each sub-question from the research plan
+- Use data and visualizations to support key points
+- End with a concise executive summary of your findings
+- Include a "Methodology" section explaining how you conducted your research
+""",
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+    use_history=True,
+)
+@agents.agent(
+    name="FactChecker",
+    instruction="""
+You are a meticulous fact-checker and critical evaluator of research. Your responsibilities are to:
+
+1. Verify factual claims by cross-checking with authoritative sources
+2. Identify any unsupported assertions or logical fallacies
+3. Detect potential biases or limitations in the research methodology
+4. Ensure proper representation of diverse perspectives on controversial topics
+5. Evaluate the quality, reliability, and currency of cited sources
+
+When reviewing research:
+- Flag any claims that lack sufficient evidence or citation
+- Identify information that seems outdated or contradicts current consensus
+- Check for oversimplifications of complex topics
+- Ensure numerical data and statistics are accurately represented
+- Verify that quotations are accurate and in proper context
+- Look for any gaps in the research or important perspectives that were omitted
+
+Your feedback should be specific, actionable, and structured to help improve accuracy and comprehensiveness.
+""",
+    servers=["brave", "fetch"],
+)
+@agents.agent(
+    name="Evaluator",
+    model="sonnet",
+    instruction="""
+You are a senior research quality evaluator with expertise in academic and professional research standards.
+
+COMPREHENSIVE EVALUATION CRITERIA:
+1. Research Methodology
+   - Has the researcher followed a structured approach?
+   - Were appropriate research methods applied?
+   - Is there evidence of strategic information gathering?
+
+2. Source Quality & Diversity
+   - Are sources authoritative, current, and relevant?
+   - Is there appropriate diversity of sources?
+   - Were primary sources consulted when appropriate?
+
+3. Information Depth
+   - Does the research go beyond surface-level information?
+   - Is there evidence of in-depth analysis?
+   - Has the researcher explored multiple aspects of the topic?
+
+4. Critical Analysis
+   - Has information been critically evaluated rather than simply reported?
+   - Are limitations and uncertainties acknowledged?
+   - Are multiple perspectives considered on controversial topics?
+
+5. Data & Evidence
+   - Is quantitative data properly analyzed and presented?
+   - Are visualizations clear, accurate, and informative?
+   - Is qualitative information presented with appropriate context?
+
+6. Documentation & Attribution
+   - Are all sources properly cited with complete reference information?
+   - Is it clear which information came from which source?
+   - Is the bibliography comprehensive and well-formatted?
+
+7. Structure & Communication
+   - Is the research presented in a logical, well-organized manner?
+   - Are findings communicated clearly and precisely?
+   - Is the level of technical language appropriate for the intended audience?
+
+8. Alignment with Previous Feedback
+   - Has the researcher addressed specific feedback from previous evaluations?
+   - Have requested improvements been successfully implemented?
+
+For each criterion, provide:
+- A detailed RATING (EXCELLENT, GOOD, FAIR, or POOR)
+- Specific examples from the research that justify your rating
+- Clear, actionable suggestions for improvement
+
+Your evaluation should conclude with:
+- An OVERALL RATING that reflects the research quality
+- A concise summary of the research's major strengths
+- A prioritized list of the most important areas for improvement
+
+The researcher should be able to understand exactly why they received their rating and what specific steps they can take to improve.
+""",
+)
+@agents.chain(
+    name="ResearchProcess",
+    sequence=["ResearchPlanner", "Researcher", "FactChecker"],
+    instruction="A comprehensive research workflow that plans, executes, and verifies research",
+    cumulative=True,
+)
+@agents.evaluator_optimizer(
+    generator="ResearchProcess",
+    evaluator="Evaluator",
+    max_refinements=3,
+    min_rating="EXCELLENT",
+    name="EnhancedResearcher",
+)
+async def main() -> None:
+    async with agents.run() as agent:
+        # Start with a warm-up to set expectations and explain the research approach
+        await agent.Researcher.send(
+            """I'm an enhanced research assistant trained to conduct thorough, evidence-based research. 
+            I'll approach your question by:
+            1. Creating a structured research plan
+            2. Gathering information from multiple authoritative sources
+            3. Analyzing data and creating visualizations when helpful
+            4. Fact-checking and verifying all information
+            5. Providing a comprehensive, well-documented answer
+
+            What would you like me to research for you today?"""
+        )
+
+        # Start the main research workflow
+        await agent.prompt("EnhancedResearcher")
+
+        print("\nWould you like to ask follow-up questions to the Researcher? (Type 'STOP' to end)")
+        await agent.prompt("Researcher", default_prompt="STOP")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/researcher/researcher.py

@@ -0,0 +1,36 @@
+import asyncio
+
+from fast_agent import FastAgent
+
+# from rich import print
+
+agents = FastAgent(name="Researcher Agent")
+
+
+@agents.agent(
+    "Researcher",
+    instruction="""
+You are a research assistant, with access to internet search (via Brave),
+website fetch, a python interpreter (you can install packages with uv) and a filesystem.
+Use the current working directory to save and create files with both the Interpreter and Filesystem tools.
+The interpreter has numpy, pandas, matplotlib and seaborn already installed
+    """,
+    servers=["brave", "interpreter", "filesystem", "fetch"],
+)
+async def main() -> None:
+    research_prompt = """
+Produce an investment report for the company Eutelsat. The final report should be saved in the filesystem in markdown format, and
+contain at least the following: 
+1 - A brief description of the company
+2 - Current financial position (find data, create and incorporate charts)
+3 - A PESTLE analysis
+4 - An investment thesis for the next 3 years. Include both 'buy side' and 'sell side' arguments, and a final 
+summary and recommendation.
+Todays date is 15 February 2025. Include the main data sources consulted in presenting the report."""  # noqa: F841
+
+    async with agents.run() as agent:
+        await agent.prompt()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_agent/resources/examples/tensorzero/.env.sample

@@ -0,0 +1,2 @@
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=

fast_agent/resources/examples/tensorzero/Makefile

@@ -0,0 +1,31 @@
+.PHONY: all
+
+build:
+	docker compose build
+
+up:
+	docker compose up -d
+
+logs:
+	docker compose logs -f
+
+tensorzero-logs:
+	docker compose logs -f gateway
+
+mcp-logs:
+	docker compose logs -f mcp-server
+
+minio-logs:
+	docker compose logs -f minio
+
+stop:
+	docker compose stop
+
+agent:
+	uv run agent.py --model=tensorzero.test_chat
+
+simple-agent:
+	uv run simple_agent.py --model=tensorzero.simple_chat
+
+image-test:
+	uv run image_demo.py 

fast_agent/resources/examples/tensorzero/README.md

@@ -0,0 +1,56 @@
+# About the tensorzero / fast-agent integration
+
+[TensorZero](https://www.tensorzero.com/) is an open source project designed to help LLM application developers rapidly improve their inference calls. Its core features include:
+
+- A uniform inference interface to all leading LLM platforms.
+- The ability to dynamic route to different platforms and program failovers.
+- Automated parameter tuning and training
+- Advance templating features for your system prompts
+- Organization of LLM inference data into a Clickhouse DB allowing for sophisticated downstream analytics
+- A bunch of other good stuff is always in development
+
+`tensorzero` is powerful heavy, so we provide here a quickstart example that combines the basic components of `fast-agent`, an MCP server, `tensorzero`, and other supporting services into a cohesive whole.
+
+## Quickstart guide
+
+- Install `fast-agent` with the `[tensorzero]` dependency e.g. `uv pip install -U fast-agent-mcp[tensorzero]`
+- Build and activate the `uv` `fast-agent` environment
+- Ensure that ports `3000`, `4000`, `8000`, `9000`, and `9001` are unallocated before running this demo.
+- Run `cp .env.sample .env` and then drop in at least one of `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Make sure the accounts are funded.
+- `make up`
+- `make agent`
+
+The demo test's our implementation's ability to:
+
+- Implement the T0 model gateway as an inference backend
+- Implement T0's dynamic templating feature
+- Have in-conversation memory
+- Describe and execute tool calls
+- Remember previous tool calls
+
+A version of a conversation to test all of this could be:
+
+```
+Hi.
+
+Tell me a poem.
+
+Do you have any tools that you can use?
+
+Please demonstrate the use of that tool on your last response.
+
+Please summarize the conversation so far.
+
+What tool calls have you executed in this session, and what were their results?
+```
+
+## Multimodal support
+
+Run `make image-test` to test the gateway's ability to handle base64-encoded image data
+
+## Development notes:
+
+- `make stop` will stop the MCP server and the tensorzero server
+- `make tenzorzero-logs` will tail the tensorzero server logs
+- `make mcp-logs` will tail the MCP server logs
+- Generic `make logs` dumps all log output from all services to terminal

fast_agent/resources/examples/tensorzero/agent.py

@@ -0,0 +1,35 @@
+import asyncio
+
+from fast_agent import FastAgent
+from fast_agent.llm.request_params import RequestParams
+
+# Explicitly provide the path to the config file in the current directory
+CONFIG_FILE = "fastagent.config.yaml"
+fast = FastAgent("fast-agent example", config_path=CONFIG_FILE, ignore_unknown_args=True)
+
+# Define T0 system variables here
+my_t0_system_vars = {
+    "TEST_VARIABLE_1": "Roses are red",
+    "TEST_VARIABLE_2": "Violets are blue",
+    "TEST_VARIABLE_3": "Sugar is sweet",
+    "TEST_VARIABLE_4": "Vibe code responsibly 👍",
+}
+
+
+@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"],
+    request_params=RequestParams(template_vars=my_t0_system_vars),
+)
+async def main():
+    async with fast.run() as agent_app:  # Get the AgentApp wrapper
+        print("\nStarting interactive session with template_vars set via decorator...")
+        await agent_app.interactive()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())  # type: ignore

fast_agent/resources/examples/tensorzero/docker-compose.yml

@@ -0,0 +1,105 @@
+# This is a simplified example for learning purposes. Do not use this in production.
+# For production-ready deployments, see: https://www.tensorzero.com/docs/gateway/deployment
+
+# Top-level volumes definition
+volumes:
+  minio_data: {}
+
+services:
+  clickhouse:
+    image: clickhouse/clickhouse-server:24.12-alpine
+    environment:
+      CLICKHOUSE_USER: chuser
+      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
+      CLICKHOUSE_PASSWORD: chpassword
+    ports:
+      - "8123:8123"
+    healthcheck:
+      test: wget --spider --tries 1 http://chuser:chpassword@clickhouse:8123/ping
+      start_period: 30s
+      start_interval: 1s
+      timeout: 1s
+
+  gateway:
+    image: tensorzero/gateway
+    volumes:
+      - ./tensorzero_config:/app/config:ro
+    env_file:
+      - ./.env
+    command: --config-file /app/config/tensorzero.toml
+    environment: # WARNING: Insecure default credentials for local testing ONLY. Don't send this to production.
+      TENSORZERO_CLICKHOUSE_URL: http://chuser:chpassword@clickhouse:8123/tensorzero
+      S3_ACCESS_KEY_ID: user
+      S3_SECRET_ACCESS_KEY: password
+    ports:
+      - "3000:3000"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      clickhouse:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+      mcp-server:
+        condition: service_healthy
+
+  gateway-ui:
+    image: tensorzero/ui
+    volumes:
+      - ./tensorzero_config:/app/config:ro
+    env_file:
+      - ./.env
+    command: --config-file /app/config/tensorzero.toml
+    environment:
+      TENSORZERO_CLICKHOUSE_URL: http://chuser:chpassword@clickhouse:8123/tensorzero
+      TENSORZERO_GATEWAY_URL: http://gateway:3000
+      S3_ACCESS_KEY_ID: user
+      S3_SECRET_ACCESS_KEY: password
+    ports:
+      - "4000:4000"
+    depends_on:
+      clickhouse:
+        condition: service_healthy
+
+  mcp-server:
+    build:
+      context: ./mcp_server
+      dockerfile: Dockerfile
+    working_dir: /app
+    volumes:
+      - ./mcp_server:/app
+    ports:
+      - "8000:8000"
+    depends_on:
+      minio:
+        condition: service_healthy
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "wget",
+          "--spider",
+          "--tries=1",
+          "http://localhost:8000/t0-example-server/sse",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
+  minio:
+    image: minio/minio:latest
+    ports:
+      - "9000:9000" # API port
+      - "9001:9001" # Console port
+    volumes:
+      - minio_data:/data
+    environment: # WARNING: Insecure default credentials for local testing ONLY.
+      MINIO_ROOT_USER: user
+      MINIO_ROOT_PASSWORD: password
+    command: server /data --console-address :9001
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3

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

@@ -0,0 +1,19 @@
+default_model: haiku
+
+tensorzero:
+  base_url: http://localhost:3000
+  api_key: verysecret
+
+logger:
+  level: "info"
+  progress_display: true
+  show_chat: true
+  show_tools: true
+  truncate_tools: true
+
+mcp:
+  servers:
+    tester:
+      transport: "sse"
+      url: "http://localhost:8000/t0-example-server/sse"
+      read_transport_sse_timeout_seconds: 300

fast_agent/resources/examples/tensorzero/image_demo.py

@@ -0,0 +1,67 @@
+import asyncio
+import base64
+import mimetypes
+from pathlib import Path
+from typing import Union
+
+from mcp.types import ImageContent, TextContent
+
+from fast_agent import FastAgent
+from fast_agent.core.prompt import Prompt
+from fast_agent.llm.request_params import RequestParams
+
+AGENT_NAME = "tensorzero_image_tester"
+TENSORZERO_MODEL = "tensorzero.test_chat"
+TEXT_PROMPT = (
+    "Provide a description of the similarities and differences between these three images."
+)
+LOCAL_IMAGE_FILES = [
+    Path("./demo_images/clam.jpg"),
+    Path("./demo_images/shrimp.png"),
+    Path("./demo_images/crab.png"),
+]
+
+MY_T0_SYSTEM_VARS = {
+    "TEST_VARIABLE_1": "Roses are red",
+    "TEST_VARIABLE_2": "Violets are blue",
+    "TEST_VARIABLE_3": "Sugar is sweet",
+    "TEST_VARIABLE_4": "Vibe code responsibly 👍",
+}
+
+fast = FastAgent("TensorZero Image Demo - Base64 Only")
+
+
+@fast.agent(
+    name=AGENT_NAME,
+    model=TENSORZERO_MODEL,
+    request_params=RequestParams(template_vars=MY_T0_SYSTEM_VARS),
+)
+async def main():
+    content_parts: list[Union[TextContent, ImageContent]] = []
+    content_parts.append(TextContent(type="text", text=TEXT_PROMPT))
+
+    for file_path in LOCAL_IMAGE_FILES:
+        mime_type, _ = mimetypes.guess_type(file_path)
+        if not mime_type or not mime_type.startswith("image/"):
+            ext = file_path.suffix.lower()
+            if ext == ".jpg" or ext == ".jpeg":
+                mime_type = "image/jpeg"
+            elif ext == ".png":
+                mime_type = "image/png"
+        if mime_type is None:
+            mime_type = "image/png"  # Default fallback if still None
+
+        with open(file_path, "rb") as image_file:
+            image_bytes = image_file.read()
+
+        encoded_data = base64.b64encode(image_bytes).decode("utf-8")
+        content_parts.append(ImageContent(type="image", mimeType=mime_type, data=encoded_data))
+
+    message = Prompt.user(*content_parts)
+    async with fast.run() as agent_app:
+        agent = getattr(agent_app, AGENT_NAME)
+        await agent.send(message)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())  # type: ignore

fast_agent/resources/examples/tensorzero/mcp_server/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y curl wget && \
+    wget https://dl.min.io/client/mc/release/linux-amd64/mc -O /usr/local/bin/mc && \
+    chmod +x /usr/local/bin/mc && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+RUN pip install uv
+
+# Copy dependency files only
+COPY pyproject.toml /tmp/
+#COPY uv.lock /tmp/
+
+# Install dependencies
+WORKDIR /tmp
+RUN uv pip install --system .
+
+# Switch back to /app (this will be overridden by volume mount)
+WORKDIR /app
+
+# These files will come from the volume mount at runtime
+EXPOSE 8000
+ENTRYPOINT ["/app/entrypoint.sh"]
+CMD ["uvicorn", "mcp_server:app", "--host", "0.0.0.0", "--port", "8000"]

fast_agent/resources/examples/tensorzero/mcp_server/entrypoint.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+
+echo "Entrypoint: Waiting for MinIO to be healthy..."
+
+# Simple loop to check MinIO health endpoint (within the Docker network)
+# Adjust timeout as needed
+TIMEOUT=60
+START_TIME=$(date +%s)
+while ! curl -sf http://minio:9000/minio/health/live > /dev/null; do
+    CURRENT_TIME=$(date +%s)
+    ELAPSED=$(($CURRENT_TIME - $START_TIME))
+    if [ $ELAPSED -ge $TIMEOUT ]; then
+        echo "Entrypoint: Timeout waiting for MinIO!"
+        exit 1
+    fi
+    echo "Entrypoint: MinIO not ready, sleeping..."
+    sleep 2
+done
+echo "Entrypoint: MinIO is healthy."
+
+echo "Entrypoint: Configuring mc client and creating bucket 'tensorzero'..."
+
+# Configure mc to talk to the MinIO server using the service name
+# Use --insecure because we are using http
+mc --insecure alias set local http://minio:9000 user password
+
+# Create the bucket if it doesn't exist
+# Use --insecure because we are using http
+mc --insecure ls local/tensorzero > /dev/null 2>&1 || mc --insecure mb local/tensorzero
+
+echo "Entrypoint: Bucket 'tensorzero' check/creation complete."
+
+echo "Entrypoint: Executing the main container command: $@"
+
+exec "$@"

fast_agent/resources/examples/tensorzero/mcp_server/mcp_server.py

@@ -0,0 +1,31 @@
+import uvicorn
+from mcp.server.fastmcp.server import FastMCP
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+SERVER_PATH = "t0-example-server"
+
+
+mcp_instance = FastMCP(name="t0-example-server")
+mcp_instance.settings.message_path = f"/{SERVER_PATH}/messages/"
+mcp_instance.settings.sse_path = f"/{SERVER_PATH}/sse"
+
+
+@mcp_instance.tool()
+def example_tool(input_text: str) -> str:
+    """Example tool that reverses the text of a given string."""
+    reversed_text = input_text[::-1]
+    return reversed_text
+
+
+app = Starlette(
+    routes=[
+        Mount("/", app=mcp_instance.sse_app()),
+    ]
+)
+
+if __name__ == "__main__":
+    print(f"Starting minimal MCP server ({mcp_instance.name}) on http://127.0.0.1:8000")
+    print(f" -> SSE endpoint: {mcp_instance.settings.sse_path}")
+    print(f" -> Message endpoint: {mcp_instance.settings.message_path}")
+    uvicorn.run(app, host="127.0.0.1", port=8000)

fast_agent/resources/examples/tensorzero/mcp_server/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "mcp-server"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=2.10.6",
+    "starlette>=0.46.2",
+    "uvicorn>=0.34.3",
+]