REPL. New AgentCard in md fromat and CLI loading/lazy hot swap with --agent-cards | --watch | --reload options. New workflow-md samples (#585)

* Add AgentCard RFC and samples

* Add AgentCard reload/watch and workflow dumps

Implement incremental AgentCard reloads with mtime/size cache and registry_version tracking.

Wire /reload into the TUI and expose refresh callbacks on AgentApp.

Add lazy shared-instance hot-swap for MCP/ACP servers and dispose stale instances when idle.

Export workflow examples as AgentCards under examples/workflows-md.

Document reload/watch semantics and watchfiles fallback in plan/agent-card-rfc.md.

* Add CLI agent-cards loading

Introduce --agent-cards with --watch/--reload support in fast-agent go.

Update AgentCard RFC examples for CLI usage and one-shot messages.

Add workflows-md symlinks for local config and short_story examples.

* Replace workflows-md symlinks with files

* Fix typecheck issues in examples and Azure auth

* Adjust Azure import ignore for typecheck

* Skip null agent-as-tools fields in dumps

* (unrelated to PR) fix uvloop tty blocking

* tool example

* example agent with functions
agent card at url
--card alias
allow use from `serve`

* lint

* (markdown render change) improve error handling for Agent Cards

* agent card default type "agent". update test signature

* Update AgentCard and hook-tool specs

* Make --card the primary AgentCard flag

* Add --dump alias for AgentCard export

* Merge hook-tool declarative specs

* Refine hook-tool AgentCard example

* Align hook-tool declarative spec examples

* Update hook-tool examples plan

* add /card and /card <foo> --tool

* update rfc, add description to hf api tool

* Docs: clarify history controls and next-stage work

* Docs: simplify history controls

* Docs: clarify orchestrator-owned history fields

* Docs: reorder history options

* Docs: describe history option semantics

* Docs: note stateless /card --tool MVP

* Docs: align history defaults and CLI order

* ToolAgent: spawn stateless clones for agent tools

* ToolAgent: tighten add_agent_tool type

* ToolAgent: drop unused AgentProtocol import

* Fix typing in elicitation example

* Fix ruff typing.cast quoting

* Add stateless add_agent_tool test

* Refine AGENTS guidance and test override

* add progress notifications; fix tool definitions for detached agents.

* use model in card as precedent

* typecheck/lint

---------

Co-authored-by: evalstate <[email protected]>

Author: iqdoctor

AGENTS.md

@@ -1,2 +1,7 @@
-Present links to images and other content in Markdown links -- for example: ![Image](https://link.to.image)
+## fast-agent contributor notes
 
+- Use `uv run` for repo scripts and examples.
+- Always run `uv run scripts/lint.py` and `uv run scripts/typecheck.py` after code changes.
+- Keep examples under `examples/` in sync with packaged resources when relevant.
+- Prefer small, focused diffs; avoid reformatting unrelated code.
+- Use Markdown links for images and other content (example: `![Image](https://link.to.image)`).

examples/mcp/elicitations/elicitation_forms_server.py

@@ -7,7 +7,7 @@
 
 import logging
 import sys
-from typing import Optional, TypedDict
+from typing import Optional, TypedDict, cast
 
 from mcp import ReadResourceResult
 from mcp.server.elicitation import (
@@ -51,7 +51,10 @@ def _create_enum_schema_options(data: dict[str, str]) -> list[TitledEnumOption]:
         >>> _create_enum_schema_options({"dark": "Dark Mode", "light": "Light Mode"})
         [{"const": "dark", "title": "Dark Mode"}, {"const": "light", "title": "Light Mode"}]
     """
-    return [{"const": k, "title": v} for k, v in data.items()]
+    options: list[TitledEnumOption] = [
+        cast("TitledEnumOption", {"const": k, "title": v}) for k, v in data.items()
+    ]
+    return options
 
 
 @mcp.resource(uri="elicitation://event-registration")

examples/mcp/elicitations/game_character_handler.py

@@ -33,8 +33,9 @@ async def game_character_elicitation_handler(
     """Custom handler that creates an interactive character creation experience."""
     logger.info(f"Game character elicitation handler called: {params.message}")
 
-    if params.requestedSchema:
-        properties = params.requestedSchema.get("properties", {})
+    requested_schema = getattr(params, "requestedSchema", None)
+    if requested_schema:
+        properties = requested_schema.get("properties", {})
         content: dict[str, Any] = {}
 
         console.print("\n[bold magenta]🎮 Character Creation Studio 🎮[/bold magenta]\n")

examples/tensorzero/simple_agent.py

@@ -18,7 +18,7 @@ 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)
+        await agent_app.interactive(agent_name=agent_name)
 
 
 if __name__ == "__main__":

examples/workflows-md/agents_as_tools_extended/London-Project-Manager.md

@@ -0,0 +1,8 @@
+---
+type: agent
+name: London-Project-Manager
+servers:
+- time
+- fetch
+---
+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/

examples/workflows-md/agents_as_tools_extended/NY-Project-Manager.md

@@ -0,0 +1,8 @@
+---
+type: agent
+name: NY-Project-Manager
+servers:
+- time
+- fetch
+---
+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

examples/workflows-md/agents_as_tools_extended/PMO-orchestrator.md

@@ -0,0 +1,13 @@
+---
+type: agent
+name: PMO-orchestrator
+default: true
+agents:
+- NY-Project-Manager
+- London-Project-Manager
+history_mode: scratch
+max_parallel: 128
+child_timeout_sec: 120
+max_display_instances: 20
+---
+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.

examples/workflows-md/agents_as_tools_simple/London-Project-Manager.md

@@ -0,0 +1,7 @@
+---
+type: agent
+name: London-Project-Manager
+servers:
+- time
+---
+Return London time + timezone, plus a one-line news update.

examples/workflows-md/agents_as_tools_simple/NY-Project-Manager.md

@@ -0,0 +1,7 @@
+---
+type: agent
+name: NY-Project-Manager
+servers:
+- time
+---
+Return NY time + timezone, plus a one-line project status.

examples/workflows-md/agents_as_tools_simple/PMO-orchestrator.md

@@ -0,0 +1,9 @@
+---
+type: agent
+name: PMO-orchestrator
+default: true
+agents:
+- NY-Project-Manager
+- London-Project-Manager
+---
+Get reports. Always use one tool call per project/news. Responsibilities: NY projects: [OpenAI, Fast-Agent, Anthropic]. London news: [Economics, Art, Culture]. Aggregate results and add a one-line PMO summary.