title	3MagicLabs Agent
emoji	🕵🏻‍♂️
colorFrom	indigo
colorTo	indigo
sdk	gradio
sdk_version	6.15.1
app_file	app.py
pinned	false
hf_oauth	true
hf_oauth_expiration_minutes	480

3MagicLabs Agent

A supervisor multi-agent system for autonomous research, reasoning and code execution, built on LangGraph. A supervisor routes each turn to a specialist — web research or sandboxed code — and a finalizer produces an exact-match answer.

Near-term target: GAIA Level 1. Architecture target: Level 3. See the roadmap.

Quick start

pip install -e ".[dev,tools,app]"
cp .env.example .env          # add at least one provider key
agent doctor                  # what is configured, what is degraded
agent run --limit 3           # answer three benchmark tasks
agent submit --username <hf-user>

Or run the UI: python app.py.

How it works

flowchart LR
    Q([question]) --> S{supervisor}
    S -->|web_agent| W[web specialist]
    S -->|code_agent| C[code specialist]
    S -->|FINISH| F[finalizer]
    W --> S
    C --> S
    F --> A([answer])

Loading

Four design commitments, each learned from a production failure:

1. Nothing runs at import time. No client, credential read, or network call on import — a missing optional key degrades one tool instead of killing the process. (ADR 0003)
2. Everything is bounded. Every loop has an iteration cap, every request a timeout, every run a wall-clock budget. (ADR 0002)
3. Work is never lost. Answers cache to disk as they are produced; submission is a separate action.
4. Immutable by default. Configuration and metrics are frozen dataclasses.

Configuration

At least one model provider is required; everything else degrades gracefully.

Secret	Required	Without it
GROQ_API_KEY / OPENAI_API_KEY / HF_TOKEN	yes (one)	fails at the first model call
TAVILY_API_KEY	no	web_search returns "unavailable"; scraping still works
E2B_API_KEY	no	python_repl returns "unavailable"; the agent reasons instead
LANGSMITH_API_KEY	no	no traces; logs and metrics unaffected

Full table, including every budget: docs/configuration.md.

Observability

• Logs — stdout and logs/agent.log
• Traces — LangSmith, one trace per task named task:<task_id>
• Metrics — logs/metrics.jsonl: latency, tokens, status per task

See docs/observability.md.

Development

pytest -m unit                 # 122 tests, offline, no credentials
ruff check . && ruff format .
mypy                           # strict
pytest -m integration          # needs live credentials

CI runs lint, strict types, tests on Python 3.11–3.13 across Linux/macOS/Windows, a build, and an import check against the exact dependency set the Hugging Face Space installs. See CONTRIBUTING.md.

Documentation

Architecture	Supervisor, specialists, budgets
Configuration	Every environment variable
Observability	Logs, traces, metrics
GAIA benchmark	Running and scoring
Roadmap	Level 1 → Level 3
ADRs	Why it is built this way
Security	Threat model and reporting

License

Apache License 2.0. See NOTICE for attribution.