dspy-agents (MVP)

• Runtime/ops via Agno AgentOS. Skills via DSPy (Signatures + ChainOfThought + MIPROv2). SQLite memory. Structured workflow plus MultiMCP-powered tooling (e.g., fetch_url).

Getting Started

• Python 3.10+
• Create and activate a virtualenv (recommended):
  • macOS/Linux: python3 -m venv .venv && source .venv/bin/activate
  • Windows (PowerShell): py -m venv .venv; .\.venv\Scripts\Activate.ps1
• Install deps: pip install -r requirements.txt
• Set OPENAI_API_KEY (copy .env.sample)

-Run the AgentOS API

• uvicorn apps.agentos_api.app:app --reload

• Endpoints (auto): /agents, /agents/{agent_id}/runs (supports stream=true), /docs

• Example structured brief request:

  curl -sS -X POST \
    -F "message=Use research_report to answer: What are the steps in the research workflow?" \
    -F "stream=false" \
    http://localhost:8000/agents/researcher/runs | jq

• Example MCP request (requires MCP_SSE_URL or MCP_URLS configured):

  curl -sS -X POST \
    -F "message=Use fetch_url to fetch: https://dspy.ai" \
    -F "stream=false" \
    http://localhost:8000/agents/researcher/runs | jq

  (If the MCP server is offline, the API will start without remote tools and log a warning.)

• Local Agent UI chat (optional, requires Node 18+):

  # Backend on 127.0.0.1:7778 with optional bearer auth
  cd /Users/ben/code/dspy-agents
  source .venv/bin/activate
  export OS_SECURITY_KEY=dev-key  # optional; omit for unauthenticated local runs
  uvicorn apps.agentos_api.app:app --host 127.0.0.1 --port 7778 --reload
  
  # Frontend in a second terminal
  cd /Users/ben/code
  npx create-agent-ui@latest agent-ui
  cd agent-ui
  npm install
  npm run dev  # defaults to http://localhost:3000

  In the Agent UI, set the endpoint to http://127.0.0.1:7778 (add Authorization: Bearer dev-key if you exported OS_SECURITY_KEY), then send a prompt such as Use mini_report to answer: what does the Researcher agent do? to verify chat works end-to-end.

Compile the DSPy Program

• python dspy_optimize/compile_rag.py
• Output directory: dspy_optimize/artifacts/rag_compiled/

Evaluate (quick EM)

• python eval/harness.py
• Compares zero-shot vs compiled on 28 doc-grounded Q/A pairs (latest run: zero-shot 2/28, compiled 9/28).

Workflow

• workflows/mini_report.py exposes a MiniReport workflow with steps answer, outline, expand.
• The answer step uses a tiny in-memory search (skills/rag/search.py) and a DSPy program (context, question -> answer). If a compiled artifact exists, it is used; otherwise zero-shot.

MCP Integration (fetch_url)

• Start local SSE MCP server: python mcp/server.py (listens on http://localhost:8001/sse).
• Set MCP_SSE_URL=http://localhost:8001/sse (or provide multiple endpoints via MCP_URLS / MCP_COMMANDS).
• Streamable HTTP endpoints are supported by default when you supply MCP_URLS; add MCP_URL_TRANSPORTS=sse only if you need SSE.
• Call the API as shown above or run the client demo: python scripts/run_agent_with_mcp.py (uses MCPTools).
• The Researcher agent now shares MCP access with its DSPy toolkits, so a single run can fetch remote context and synthesize answers when the MCP servers are reachable. Otherwise it falls back to local tools.

Repo Layout

• apps/agentos_api/app.py – FastAPI via AgentOS, Researcher agent + MultiMCP configuration
• workflows/mini_report.py – minimal workflow; uses DSPy program
• skills/rag/search.py – tiny in-memory corpus + naive keyword search
• dspy_optimize/compile_rag.py – MIPROv2 compile, saves artifact
• dspy_optimize/datasets/qa_agno_dspy.jsonl – compact doc-grounded Q/A set (~28 examples)
• eval/harness.py – zero-shot vs compiled EM comparison
• mcp/server.py – FastMCP SSE server with fetch_url tool
• scripts/run_agent_with_mcp.py – client demo connecting to MCP via SSE

Notes / Next Steps

• Keep CoT visible in streams but not in final answers unless requested.
• After MVP: add real retrieval (DuckDuckGo or pgvector), a second DSPy skill (classification + BootstrapFinetune), try GEPA, then UI (AgentUI).

Troubleshooting

• On macOS, if you see errors mentioning the Xcode license or clang++ when installing packages, run sudo xcodebuild -license once and re-run pip install -r requirements.txt.