agno-agentos-apps
Build Agno AgentOS apps with Grok and Parallel.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- agno-agentos-apps
- author
- Hermes Agent
- license
- MIT
- version
- 1.4.0
- metadata
- { "hermes": { "tags": [ "agno", "agentos", "grok", "xai", "parallel", "multi-agent", "workflows", "skills", "localskills", "anda", "kip", "multi-agency" ], "related_skills": [ "openhands-llm-auth", "hermes-agent-skill-authoring", "ai-dropshipping-agency-mcp", "ai-agency-enterprise-ops", "anda-ecosystem", "hermes-project-soul" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Build Agno AgentOS apps with Grok and Parallel.
02 资源文件 11
- 参考文档references/agentos-mcp-server.md1.8 KB
- 参考文档references/agentos-team-mode.md997 B
- 参考文档references/agno-localskills.md2.6 KB
- 参考文档references/ai-agency-ops-from-hermes.md2.5 KB
- 参考文档references/enterprise-lifecycle-tools.md1.8 KB
- 参考文档references/hitl-spend-and-ads.md1.6 KB
- 参考文档references/multi-agency-anda-scaffold.md3.5 KB
- 参考文档references/parallel-search-api-quirks.md1.4 KB
- 参考文档references/parallel-task-ultra.md1.3 KB
- 参考文档references/persona-packs-and-toolbelts.md2.0 KB
- 参考文档references/xai-device-code-standalone.md1.6 KB
03 SKILL.md 正文
Agno AgentOS Apps (Grok + Parallel)
Scaffold and run multi-agent apps on Agno AgentOS using xAI Grok (OpenAI-compatible), Parallel Web Systems research tools, and Agno LocalSkills packs.
Canonical examples on this VPS:
| Repo | Domain | Port | Notes |
|---|---|---|---|
/root/src/repos/ai-agency |
Dropshipping | 7777 | Full enterprise + Drop :7788 |
/root/src/repos/ai-clipping |
AI clipping | 7766 | Lean Anda/KIP base (10a/5t/4wf) |
When the user wants Anda / iclabs / ldclabs as the base agent framework, follow the clipping pattern: local kip_memory/ + factory auto-attach anda_brain + optional ANDA_NEXUS_URL. Detail: references/multi-agency-anda-scaffold.md.
When to Use
- New Agno
Agent/Team/Workflow+AgentOSproject - Second/third agency on the same host (port isolation, shared SuperGrok, forked foundation)
- Expand an agency with domain agents (ops, retention, compliance, finance, clipping)
- Wire Grok via SuperGrok OAuth or
XAI_API_KEY - Attach Parallel Search/Extract/Task/FindAll/Monitor as agent tools
- Author Agno
skills/<pack>/<name>/SKILL.md(not Hermes skills) - SOTA agent design: markdown personas, scoped skills, toolbelts, output schemas, evals
- Enable AgentOS as MCP server for Hermes (or other MCP clients)
- Hybrid FastMCP + ACP gateway on one port (see Drop pattern)
- Fix paste-pack scaffolds that break on current Agno or Parallel APIs
Don't use for: day-to-day operating the live dropshipping agency from Hermes (use ai-agency-enterprise-ops + ai-dropshipping-agency-mcp); raw Parallel CLI only (parallel-web / parallel-*); OpenHands dual-auth UI (openhands-llm-auth); Hermes skill authoring (hermes-agent-skill-authoring).
Prerequisites
- Project venv (never pollute system/Hermes site-packages)
PARALLEL_API_KEY— env, or/root/.config/parallel/api.env, or~/.hermes/.env- xAI:
XAI_API_KEYor device-code OAuth (see below) - Offline Agno docs: skill
docs-agno+ FTS DB (external corpus; do not patch that skill) PyYAMLcomes with Agno for LocalSkills frontmatter
python3 -m venv .venv && source .venv/bin/activate
pip install -U "agno[os,mcp]" openai httpx python-dotenv uvicorn parallel-web \
opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno \
fal-client agent-client-protocol
# fastmcp comes via agno[mcp] — required for AgentOS(mcp_server=...)
Canonical layout (SOTA)
app/main.py # AgentOS + optional mcp_server=MCPServerConfig
agents/_factory.py # persona md + scoped skills + toolbelts + schemas
agents/profiles.py # declarative per-agent config
agents/prompt_loader.py # SOUL/SYSTEM/OUTPUT/EXAMPLES
agents/schemas.py # Pydantic handoff contracts
agents/__init__.py # LIGHT only — no eager roster imports
agents/*.py # thin wiring only
prompts/<agent>/{SOUL,SYSTEM,OUTPUT,EXAMPLES}.md
prompts/teams/<team>/SYSTEM.md
teams/_factory.py + teams/*.py
workflows/*.py # Step(name=..., team=...)
tools/xai_oauth_pkce.py | xai_model.py | parallel_tools.py
tools/skills_loader.py # skills_for(*names) scoped LocalSkills
tools/toolbelts.py # role-shaped tool sets
tools/guardrails.py # L2 autonomy tool_hooks
tools/mcp_custom.py # optional custom /mcp tools
tools/anda_knowledge.py # Anda brain tools (when Anda-base)
kip_memory/ # local KIP + Brain (when Anda-base)
knowledge/anda/ # offline ldclabs docs slice
skills/{agency,<domain>,agents}/<name>/SKILL.md
evals/run_agent_evals.py # structural evals
tests/test_*.py # pytest multi-gate (required for new agencies)
scripts/start_agentos.sh
SOUL/ + AGENTS.md + .hermes.md
Procedure
-
Model factory (import-safe)
Resolve token insideget_grok_model(); on missing creds use a placeholder key and log — do not raise at import so AgentOS can still load. Runtime calls fail clearly until login. -
xAI credentials (order)
XAI_API_KEY- Project store
~/.config/<agency-slug>/xai_oauth.json(mode 600) — e.g.ai-agencyorai-clipping - Fallback: sibling agency store and/or Hermes
~/.hermes/auth.jsonproviderxai-oauth
CLI:python -m tools.xai_oauth_pkce login|status|logout
Flow is device code (RFC 8628), not browser PKCE — filename is historical.
When forking OAuth helper code, retargetDEFAULT_TOKEN_PATHand allow reading the other agency’s store so SuperGrok login is shared.
-
SOTA agent brain (prefer over inline instruction lists)
- Always-on:
prompts/<agent>/SOUL.md+SYSTEM.md→instructions - Contract:
OUTPUT.md→expected_output+ Pydanticoutput_schema - Few-shot:
EXAMPLES.md→additional_input - On-demand playbooks: Agno LocalSkills via
skills_for("a","b")— not the full library on every agent - Tools: named toolbelts (
parallel_research,economics, …) — not “everyone gets Parallel”
Seereferences/persona-packs-and-toolbelts.md.
- Always-on:
-
Agent factory
build_agent( name=..., role=..., persona="product_scout", toolbelts=("parallel_research","economics","linear"), skill_names=("product-scoring","unit-economics"), output_schema=ProductCandidateBatch, add_history_to_context=False, # True for Ops/CS/Growth/Finance use_json_mode=True, )Keep
agents/*.pythin; iterate prompts in markdown.
Anda-base factories also auto-appendanda_brain+hermes_bridgeunlessAGENCY_DISABLE_*, and inject a short recall→formation protocol (no secrets in KIP). -
Agents / teams
Teams must use the enum, not a bare string:from agno.team.mode import TeamMode Team(mode=TeamMode.coordinate, members=[...], skills=skills_for(...), ...)Do not pass
show_tool_calls(removed on current Agno Agent).
Scope team skills to the union of member domains — avoid global skill dump. -
Workflows
Usefrom agno.workflow import Step, WorkflowandStep(name=..., team=...).
Dict steps{"name": ..., "team": ...}are outdated and break. -
Agno LocalSkills
skills_for(*names)loads individual skill folders (exact name match). Emptyskills_for()= all packs (legacy).
Each skill folder name == frontmattername(lowercase, hyphens). Progressive tools:get_skill_instructions/get_skill_reference— skill names are not callable.
Seereferences/agno-localskills.md. -
AgentOS + optional MCP server
from agno.os.config import MCPServerConfig agent_os = AgentOS( ..., tracing=True, mcp_server=MCPServerConfig( enable_builtin_tools=True, tools=get_mcp_custom_tools(), # optional allowed_hosts=["localhost","127.0.0.1"], result_mode="trimmed", ), )Requires
agno[mcp]/fastmcp. Endpoint:/mcp(Streamable HTTP).
Built-ins:get_agentos_config,run_agent,run_team,run_workflow,continue_run,cancel_run,get_sessions,get_session_runs.
Hermes registration: skillai-dropshipping-agency-mcp+references/agentos-mcp-server.md. -
Hybrid FastMCP + ACP gateway (optional second port)
When external clients need Linear + reasoning + lifecycle on one URL (ai-agency Drop pattern):mcp = FastMCP("drop-…") mcp_app = mcp.streamable_http_app() # already routes /mcp @asynccontextmanager async def lifespan(app): async with mcp.session_manager.run(): # REQUIRED yield Starlette(routes=[Route("/health", …), Mount("/", app=mcp_app)], lifespan=lifespan)ACP stdio:
agent-client-protocol+python -m drop_server.acp_agent.
Ops details: skillai-agency-enterprise-ops→references/drop-mcp-acp-gateway.md. -
Parallel tools
PreferparallelSDK; REST fallback withx-api-key. Task:parallel_task(..., processor="ultra", wait=True, timeout_s=3600)for deep research. Search quirks below. -
Autonomy hooks
Default L2:tool_hooksblock irreversible live actions and agent self-confirm. Dropshipping: active Shopify publish / spend confirm; Meta/TikTok launch needs HITL tokens. Clipping: live publish + rights auto-clear blocked;request_publish_approvalsurfaces human code once. -
End-to-end agency shapes
- Dropshipping: Research → Supply → Creative → Store Ops + Compliance → Growth → Retention → Director/Finance.
- Clipping: Source → Transcript → Viral moments → Edit → Captions → Package → Rights → HITL publish → KIP learnings.
-
Scaffold a new agency from an existing one (multi-agency)
Prefer copy foundation modules, not the whole roster. Full checklist:references/multi-agency-anda-scaffold.md.- Empty repo + project
.venv. - Copy reusable tools + optional entire
kip_memory/+ Anda docs slice. - Rewrite
agents/__init__.pylight (never copy ai-agency eager imports). - Retarget identity: OAuth path, Parallel UA, KIP
$self,formation(space=), skill roots, AgentOS id/port. - Unique port (7777 taken by dropshipping → clipping uses 7766).
- Domain tools + thin agents + personas + profiles + teams + workflows.
- Hermes SOUL wiring (
hermes-project-soul). - Gates: structural evals and pytest; offline env disables bridge/brain/knowledge.
- Reset
kip_memory/data/*.dbafter genesis identity retarget if already bootstrapped.
- Empty repo + project
Pitfalls
Team(mode="coordinate")breaks AgentOS/teams— schema doesteam.mode.value. AlwaysTeamMode.coordinate.- LocalSkills YAML — quote
description:when it contains:. - Directory name == skill
name— lowercase hyphens only. - Do not load all skills on every agent — scopes tokens and attention; Creative should not load
supplier-vetting. - Inline instruction lists do not scale — move brains to
prompts/<agent>/*.md; keep Python thin. - Parallel Search has no
max_results— 422extra_forbidden. Usemax_chars_totalif needed. - Search modes — only
turbo|basic|advanced(aliasfast→turbo,one-shot→basic). - Task ultra is slow —
wait=True+ timeout ≥ 3600; Hermes MCP server timeout must match. - OAuth HTTP 403 on refresh — tier gate; use
XAI_API_KEY; do not loop device-code. - MCP needs
agno[mcp]/fastmcp — without itmcp_server=Truefails at get_app/serve. - MCP tools inject at Hermes process start — restart TUI/gateway after
hermes mcp add. hermes mcp addis interactive — non-interactive:printf 'n\nY\n' | hermes mcp add ...(n = no auth for local open MCP).- Custom FastMCP + Starlette — lifespan
session_manager.run()required; mount at/not nested/mcp. - Autonomy L2 — never let agents self-confirm spend/publish; launch/publish needs HITL tokens.
- Tracing deps — opentelemetry + openinference-instrumentation-agno.
- Install into project
.venv— never global hermes site-packages. - Hermes skills ≠ Agno skills — different packages and frontmatter.
- DIM shipping —
billable_g = max(weight_g, L*W*H/5)grams; no extra ×1000. - Copying
agents/__init__.pyfrom ai-agency — eager-imports every dropshipping agent →ModuleNotFoundError. Keep__init__empty/light. - Port clash — second AgentOS must not bind 7777 if dropshipping is live; clipping uses 7766.
- Forked
kip_memorystill says Dropshipping — retarget nexus$self+formation(space=...)+ domain genesis capsule; delete localnexus.dbafter fix. - skills_loader roots — new agencies need their own pack dirs (e.g.
skills/clipping/), not deadmarketing//ops/copies. - Structural evals alone — also ship
tests/pytest; prefer multi-gate verification over “smoke only”.
Verification
source .venv/bin/activate && export PYTHONPATH=.
export XAI_API_KEY=missing-ci-placeholder
export AGENCY_DISABLE_HERMES_BRIDGE=1 AGENCY_DISABLE_ANDA_BRAIN=1 AGENCY_DISABLE_ANDA_KNOWLEDGE=1
ruff check agents app tools teams workflows evals scripts kip_memory tests
pytest tests/ -q
python -m evals.run_agent_evals
python -m tools.xai_oauth_pkce status
# Ports: ai-agency :7777 · ai-clipping :7766 · drop :7788 · hermes-bridge :7790
curl -s localhost:7777/health # dropshipping
curl -s localhost:7766/health # clipping
curl -s localhost:7777/info | jq .mcp
curl -s localhost:7777/teams # TeamMode enum
hermes mcp test ai-agency
hermes mcp test ai-clipping # after mcp add :7766/mcp
hermes mcp test drop # if Drop registered
Live Parallel smoke: parallel_search(..., mode="basic") → search_id + results.
Ad-hoc verify pattern: /tmp/hermes-verify-*.py with project venv, delete after (not CI).
References
references/multi-agency-anda-scaffold.md— fork ai-agency → new domain (clipping) with Anda/KIP basereferences/persona-packs-and-toolbelts.md— SOTA agent layering (md + skills + schemas)references/agentos-mcp-server.md— MCPServerConfig, built-ins, Hermes registerreferences/parallel-search-api-quirks.md— Search request shapereferences/parallel-task-ultra.md— Task wait/ultra product-rank patternreferences/xai-device-code-standalone.md— OAuth module contractreferences/agno-localskills.md— LocalSkills validationreferences/agentos-team-mode.md— TeamMode +/teamsreferences/enterprise-lifecycle-tools.md— lifecycle tool mapreferences/hitl-spend-and-ads.md— spend vault + Meta/TikTok- Live dropshipping ops: skill
ai-agency-enterprise-ops+ user-ownedai-dropshipping-agency-mcp - Anda/KIP ops: skill
anda-ecosystem· SOUL wiring:hermes-project-soul - Drop hybrid gateway ops:
ai-agency-enterprise-ops→references/drop-mcp-acp-gateway.md - Offline Agno:
docs-agno· Parallel umbrella:parallel-web(external) - SuperGrok protocol:
openhands-llm-auth→references/xai-supergrok-oauth.md
04 同仓库更多 Skills
xurl
X/Twitter via xurl CLI: raw post search, posting, DM, media.
weights-and-biases
W&B: log ML experiments, sweeps, model registry, dashboards.
touchdesigner-mcp
Control TouchDesigner via twozero MCP.
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
technical-docs-corpora
Use when bulk-crawling public tech docs into agent skills.
teams-meeting-pipeline
Teams meeting summaries, job replay, Graph subscriptions.