[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AVHEHWSXABSXWHBNCTS49C":3,"skill-same:01M7AVHEHWSXABSXWHBNCTS49C":121},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":52,"commitSha":53,"skillDirectory":54,"forksCount":55,"repositoryHtmlUrl":56,"repositoryHomepageUrl":6,"ownerHtmlUrl":57,"ownerBlogUrl":58,"ownerDescription":59,"updatedAt":60,"install":61,"resources":74},"01M7AVHEHWSXABSXWHBNCTS49C","agno-agentos-apps",null,"Build Agno AgentOS apps with Grok and Parallel.","swcstudiospace\u002Faimeecodes","swcstudiospace","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F192491759?v=4","01M7AVGY9HD2GXDY0H77EBGRGQ","@swcstudio'(space)","01M7AVGYAKRDHFDMPG97W4D5M2",1,"MIT","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: agno-agentos-apps\ndescription: \"Build Agno AgentOS apps with Grok and Parallel.\"\nversion: 1.4.0\nauthor: Hermes Agent\nlicense: MIT\nplatforms: [linux, macos, windows]\nmetadata:\n  hermes:\n    tags: [agno, agentos, grok, xai, parallel, multi-agent, workflows, skills, localskills, anda, kip, multi-agency]\n    related_skills: [openhands-llm-auth, hermes-agent-skill-authoring, ai-dropshipping-agency-mcp, ai-agency-enterprise-ops, anda-ecosystem, hermes-project-soul]\n---\n\n# Agno AgentOS Apps (Grok + Parallel)\n\nScaffold and run multi-agent apps on **Agno AgentOS** using **xAI Grok** (OpenAI-compatible), **Parallel Web Systems** research tools, and **Agno LocalSkills** packs.\n\n**Canonical examples on this VPS:**\n\n| Repo | Domain | Port | Notes |\n|------|--------|------|-------|\n| `\u002Froot\u002Fsrc\u002Frepos\u002Fai-agency` | Dropshipping | **7777** | Full enterprise + Drop `:7788` |\n| `\u002Froot\u002Fsrc\u002Frepos\u002Fai-clipping` | AI clipping | **7766** | Lean Anda\u002FKIP base (10a\u002F5t\u002F4wf) |\n\nWhen the user wants **Anda \u002F iclabs \u002F ldclabs as the base agent framework**, follow the clipping pattern: local `kip_memory\u002F` + factory auto-attach `anda_brain` + optional `ANDA_NEXUS_URL`. Detail: `references\u002Fmulti-agency-anda-scaffold.md`.\n\n## When to Use\n\n- New Agno `Agent` \u002F `Team` \u002F `Workflow` + `AgentOS` project\n- **Second\u002Fthird agency** on the same host (port isolation, shared SuperGrok, forked foundation)\n- Expand an agency with domain agents (ops, retention, compliance, finance, clipping)\n- Wire Grok via SuperGrok OAuth or `XAI_API_KEY`\n- Attach Parallel Search\u002FExtract\u002FTask\u002FFindAll\u002FMonitor as agent tools\n- Author Agno `skills\u002F\u003Cpack>\u002F\u003Cname>\u002FSKILL.md` (not Hermes skills)\n- SOTA agent design: markdown personas, scoped skills, toolbelts, output schemas, evals\n- Enable AgentOS as MCP server for Hermes (or other MCP clients)\n- Hybrid FastMCP + ACP gateway on one port (see Drop pattern)\n- Fix paste-pack scaffolds that break on current Agno or Parallel APIs\n\nDon'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` \u002F `parallel-*`); OpenHands dual-auth UI (`openhands-llm-auth`); Hermes skill authoring (`hermes-agent-skill-authoring`).\n\n## Prerequisites\n\n- Project venv (never pollute system\u002FHermes site-packages)\n- `PARALLEL_API_KEY` — env, or `\u002Froot\u002F.config\u002Fparallel\u002Fapi.env`, or `~\u002F.hermes\u002F.env`\n- xAI: `XAI_API_KEY` **or** device-code OAuth (see below)\n- Offline Agno docs: skill `docs-agno` + FTS DB (external corpus; do not patch that skill)\n- `PyYAML` comes with Agno for LocalSkills frontmatter\n\n```bash\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install -U \"agno[os,mcp]\" openai httpx python-dotenv uvicorn parallel-web \\\n  opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno \\\n  fal-client agent-client-protocol\n# fastmcp comes via agno[mcp] — required for AgentOS(mcp_server=...)\n```\n\n## Canonical layout (SOTA)\n\n```text\napp\u002Fmain.py                 # AgentOS + optional mcp_server=MCPServerConfig\nagents\u002F_factory.py          # persona md + scoped skills + toolbelts + schemas\nagents\u002Fprofiles.py          # declarative per-agent config\nagents\u002Fprompt_loader.py     # SOUL\u002FSYSTEM\u002FOUTPUT\u002FEXAMPLES\nagents\u002Fschemas.py           # Pydantic handoff contracts\nagents\u002F__init__.py          # LIGHT only — no eager roster imports\nagents\u002F*.py                 # thin wiring only\nprompts\u002F\u003Cagent>\u002F{SOUL,SYSTEM,OUTPUT,EXAMPLES}.md\nprompts\u002Fteams\u002F\u003Cteam>\u002FSYSTEM.md\nteams\u002F_factory.py + teams\u002F*.py\nworkflows\u002F*.py              # Step(name=..., team=...)\ntools\u002Fxai_oauth_pkce.py | xai_model.py | parallel_tools.py\ntools\u002Fskills_loader.py      # skills_for(*names) scoped LocalSkills\ntools\u002Ftoolbelts.py          # role-shaped tool sets\ntools\u002Fguardrails.py         # L2 autonomy tool_hooks\ntools\u002Fmcp_custom.py         # optional custom \u002Fmcp tools\ntools\u002Fanda_knowledge.py     # Anda brain tools (when Anda-base)\nkip_memory\u002F                 # local KIP + Brain (when Anda-base)\nknowledge\u002Fanda\u002F             # offline ldclabs docs slice\nskills\u002F{agency,\u003Cdomain>,agents}\u002F\u003Cname>\u002FSKILL.md\nevals\u002Frun_agent_evals.py    # structural evals\ntests\u002Ftest_*.py             # pytest multi-gate (required for new agencies)\nscripts\u002Fstart_agentos.sh\nSOUL\u002F + AGENTS.md + .hermes.md\n```\n\n## Procedure\n\n1. **Model factory (import-safe)**  \n   Resolve token inside `get_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.\n\n2. **xAI credentials (order)**  \n   1. `XAI_API_KEY`  \n   2. Project store `~\u002F.config\u002F\u003Cagency-slug>\u002Fxai_oauth.json` (mode 600) — e.g. `ai-agency` or `ai-clipping`  \n   3. Fallback: sibling agency store and\u002For Hermes `~\u002F.hermes\u002Fauth.json` provider `xai-oauth`  \n   CLI: `python -m tools.xai_oauth_pkce login|status|logout`  \n   Flow is **device code** (RFC 8628), not browser PKCE — filename is historical.  \n   When forking OAuth helper code, retarget `DEFAULT_TOKEN_PATH` and allow reading the other agency’s store so SuperGrok login is shared.\n\n3. **SOTA agent brain (prefer over inline instruction lists)**  \n   - **Always-on:** `prompts\u002F\u003Cagent>\u002FSOUL.md` + `SYSTEM.md` → `instructions`  \n   - **Contract:** `OUTPUT.md` → `expected_output` + Pydantic `output_schema`  \n   - **Few-shot:** `EXAMPLES.md` → `additional_input`  \n   - **On-demand playbooks:** Agno LocalSkills via `skills_for(\"a\",\"b\")` — **not** the full library on every agent  \n   - **Tools:** named toolbelts (`parallel_research`, `economics`, …) — not “everyone gets Parallel”  \n   See `references\u002Fpersona-packs-and-toolbelts.md`.\n\n4. **Agent factory**  \n   ```python\n   build_agent(\n     name=..., role=..., persona=\"product_scout\",\n     toolbelts=(\"parallel_research\",\"economics\",\"linear\"),\n     skill_names=(\"product-scoring\",\"unit-economics\"),\n     output_schema=ProductCandidateBatch,\n     add_history_to_context=False,  # True for Ops\u002FCS\u002FGrowth\u002FFinance\n     use_json_mode=True,\n   )\n   ```\n   Keep `agents\u002F*.py` thin; iterate prompts in markdown.  \n   Anda-base factories also auto-append `anda_brain` + `hermes_bridge` unless `AGENCY_DISABLE_*`, and inject a short recall→formation protocol (no secrets in KIP).\n\n5. **Agents \u002F teams**  \n   **Teams must use the enum**, not a bare string:\n   ```python\n   from agno.team.mode import TeamMode\n   Team(mode=TeamMode.coordinate, members=[...], skills=skills_for(...), ...)\n   ```\n   Do **not** pass `show_tool_calls` (removed on current Agno Agent).  \n   Scope team skills to the union of member domains — avoid global skill dump.\n\n6. **Workflows**  \n   Use `from agno.workflow import Step, Workflow` and `Step(name=..., team=...)`.  \n   Dict steps `{\"name\": ..., \"team\": ...}` are outdated and break.\n\n7. **Agno LocalSkills**  \n   `skills_for(*names)` loads individual skill folders (exact name match). Empty `skills_for()` = all packs (legacy).  \n   Each skill folder name == frontmatter `name` (lowercase, hyphens). Progressive tools: `get_skill_instructions` \u002F `get_skill_reference` — skill names are **not** callable.  \n   See `references\u002Fagno-localskills.md`.\n\n8. **AgentOS + optional MCP server**  \n   ```python\n   from agno.os.config import MCPServerConfig\n   agent_os = AgentOS(\n     ...,\n     tracing=True,\n     mcp_server=MCPServerConfig(\n       enable_builtin_tools=True,\n       tools=get_mcp_custom_tools(),  # optional\n       allowed_hosts=[\"localhost\",\"127.0.0.1\"],\n       result_mode=\"trimmed\",\n     ),\n   )\n   ```\n   Requires `agno[mcp]` \u002F `fastmcp`. Endpoint: **`\u002Fmcp`** (Streamable HTTP).  \n   Built-ins: `get_agentos_config`, `run_agent`, `run_team`, `run_workflow`, `continue_run`, `cancel_run`, `get_sessions`, `get_session_runs`.  \n   Hermes registration: skill `ai-dropshipping-agency-mcp` + `references\u002Fagentos-mcp-server.md`.\n\n9. **Hybrid FastMCP + ACP gateway (optional second port)**  \n   When external clients need Linear + reasoning + lifecycle on one URL (ai-agency Drop pattern):\n   ```python\n   mcp = FastMCP(\"drop-…\")\n   mcp_app = mcp.streamable_http_app()  # already routes \u002Fmcp\n\n   @asynccontextmanager\n   async def lifespan(app):\n       async with mcp.session_manager.run():  # REQUIRED\n           yield\n\n   Starlette(routes=[Route(\"\u002Fhealth\", …), Mount(\"\u002F\", app=mcp_app)], lifespan=lifespan)\n   ```\n   ACP stdio: `agent-client-protocol` + `python -m drop_server.acp_agent`.  \n   Ops details: skill `ai-agency-enterprise-ops` → `references\u002Fdrop-mcp-acp-gateway.md`.\n\n10. **Parallel tools**  \n    Prefer `parallel` SDK; REST fallback with `x-api-key`. Task: `parallel_task(..., processor=\"ultra\", wait=True, timeout_s=3600)` for deep research. Search quirks below.\n\n11. **Autonomy hooks**  \n    Default L2: `tool_hooks` block irreversible live actions and agent self-confirm. Dropshipping: active Shopify publish \u002F spend confirm; Meta\u002FTikTok launch needs HITL tokens. Clipping: live publish + rights auto-clear blocked; `request_publish_approval` surfaces human code once.\n\n12. **End-to-end agency shapes**  \n    - Dropshipping: Research → Supply → Creative → Store Ops + Compliance → Growth → Retention → Director\u002FFinance.  \n    - Clipping: Source → Transcript → Viral moments → Edit → Captions → Package → Rights → HITL publish → KIP learnings.\n\n13. **Scaffold a new agency from an existing one (multi-agency)**  \n    Prefer **copy foundation modules**, not the whole roster. Full checklist: `references\u002Fmulti-agency-anda-scaffold.md`.\n    1. Empty repo + project `.venv`.\n    2. Copy reusable tools + optional entire `kip_memory\u002F` + Anda docs slice.\n    3. **Rewrite** `agents\u002F__init__.py` light (never copy ai-agency eager imports).\n    4. Retarget identity: OAuth path, Parallel UA, KIP `$self`, `formation(space=)`, skill roots, AgentOS id\u002Fport.\n    5. Unique port (7777 taken by dropshipping → clipping uses **7766**).\n    6. Domain tools + thin agents + personas + profiles + teams + workflows.\n    7. Hermes SOUL wiring (`hermes-project-soul`).\n    8. Gates: structural evals **and** pytest; offline env disables bridge\u002Fbrain\u002Fknowledge.\n    9. Reset `kip_memory\u002Fdata\u002F*.db` after genesis identity retarget if already bootstrapped.\n\n## Pitfalls\n\n- **`Team(mode=\"coordinate\")` breaks AgentOS `\u002Fteams`** — schema does `team.mode.value`. Always `TeamMode.coordinate`.\n- **LocalSkills YAML** — quote `description:` when it contains `:`.\n- **Directory name == skill `name`** — lowercase hyphens only.\n- **Do not load all skills on every agent** — scopes tokens and attention; Creative should not load `supplier-vetting`.\n- **Inline instruction lists do not scale** — move brains to `prompts\u002F\u003Cagent>\u002F*.md`; keep Python thin.\n- **Parallel Search has no `max_results`** — 422 `extra_forbidden`. Use `max_chars_total` if needed.\n- **Search modes** — only `turbo` | `basic` | `advanced` (alias `fast`→`turbo`, `one-shot`→`basic`).\n- **Task ultra is slow** — `wait=True` + timeout ≥ 3600; Hermes MCP server timeout must match.\n- **OAuth HTTP 403 on refresh** — tier gate; use `XAI_API_KEY`; do not loop device-code.\n- **MCP needs `agno[mcp]`\u002Ffastmcp** — without it `mcp_server=True` fails at get_app\u002Fserve.\n- **MCP tools inject at Hermes process start** — restart TUI\u002Fgateway after `hermes mcp add`.\n- **`hermes mcp add` is interactive** — non-interactive: `printf 'n\\nY\\n' | hermes mcp add ...` (n = no auth for local open MCP).\n- **Custom FastMCP + Starlette** — lifespan `session_manager.run()` required; mount at `\u002F` not nested `\u002Fmcp`.\n- **Autonomy L2** — never let agents self-confirm spend\u002Fpublish; launch\u002Fpublish needs HITL tokens.\n- **Tracing deps** — opentelemetry + openinference-instrumentation-agno.\n- **Install into project `.venv`** — never global hermes site-packages.\n- **Hermes skills ≠ Agno skills** — different packages and frontmatter.\n- **DIM shipping** — `billable_g = max(weight_g, L*W*H\u002F5)` grams; no extra ×1000.\n- **Copying `agents\u002F__init__.py` from ai-agency** — eager-imports every dropshipping agent → `ModuleNotFoundError`. Keep `__init__` empty\u002Flight.\n- **Port clash** — second AgentOS must not bind **7777** if dropshipping is live; clipping uses **7766**.\n- **Forked `kip_memory` still says Dropshipping** — retarget nexus `$self` + `formation(space=...)` + domain genesis capsule; delete local `nexus.db` after fix.\n- **skills_loader roots** — new agencies need their own pack dirs (e.g. `skills\u002Fclipping\u002F`), not dead `marketing\u002F`\u002F`ops\u002F` copies.\n- **Structural evals alone** — also ship `tests\u002F` pytest; prefer multi-gate verification over “smoke only”.\n\n## Verification\n\n```bash\nsource .venv\u002Fbin\u002Factivate && export PYTHONPATH=.\nexport XAI_API_KEY=missing-ci-placeholder\nexport AGENCY_DISABLE_HERMES_BRIDGE=1 AGENCY_DISABLE_ANDA_BRAIN=1 AGENCY_DISABLE_ANDA_KNOWLEDGE=1\nruff check agents app tools teams workflows evals scripts kip_memory tests\npytest tests\u002F -q\npython -m evals.run_agent_evals\npython -m tools.xai_oauth_pkce status\n# Ports: ai-agency :7777 · ai-clipping :7766 · drop :7788 · hermes-bridge :7790\ncurl -s localhost:7777\u002Fhealth            # dropshipping\ncurl -s localhost:7766\u002Fhealth            # clipping\ncurl -s localhost:7777\u002Finfo | jq .mcp\ncurl -s localhost:7777\u002Fteams             # TeamMode enum\nhermes mcp test ai-agency\nhermes mcp test ai-clipping              # after mcp add :7766\u002Fmcp\nhermes mcp test drop                     # if Drop registered\n```\n\nLive Parallel smoke: `parallel_search(..., mode=\"basic\")` → `search_id` + results.\n\nAd-hoc verify pattern: `\u002Ftmp\u002Fhermes-verify-*.py` with project venv, delete after (not CI).\n\n## References\n\n- `references\u002Fmulti-agency-anda-scaffold.md` — fork ai-agency → new domain (clipping) with Anda\u002FKIP base\n- `references\u002Fpersona-packs-and-toolbelts.md` — SOTA agent layering (md + skills + schemas)\n- `references\u002Fagentos-mcp-server.md` — MCPServerConfig, built-ins, Hermes register\n- `references\u002Fparallel-search-api-quirks.md` — Search request shape\n- `references\u002Fparallel-task-ultra.md` — Task wait\u002Fultra product-rank pattern\n- `references\u002Fxai-device-code-standalone.md` — OAuth module contract\n- `references\u002Fagno-localskills.md` — LocalSkills validation\n- `references\u002Fagentos-team-mode.md` — TeamMode + `\u002Fteams`\n- `references\u002Fenterprise-lifecycle-tools.md` — lifecycle tool map\n- `references\u002Fhitl-spend-and-ads.md` — spend vault + Meta\u002FTikTok\n- Live dropshipping ops: skill **`ai-agency-enterprise-ops`** + user-owned **`ai-dropshipping-agency-mcp`**\n- Anda\u002FKIP ops: skill **`anda-ecosystem`** · SOUL wiring: **`hermes-project-soul`**\n- Drop hybrid gateway ops: `ai-agency-enterprise-ops` → `references\u002Fdrop-mcp-acp-gateway.md`\n- Offline Agno: `docs-agno` · Parallel umbrella: `parallel-web` (external)\n- SuperGrok protocol: `openhands-llm-auth` → `references\u002Fxai-supergrok-oauth.md`\n","# Agno AgentOS Apps (Grok + Parallel)\n\nScaffold and run multi-agent apps on **Agno AgentOS** using **xAI Grok** (OpenAI-compatible), **Parallel Web Systems** research tools, and **Agno LocalSkills** packs.\n\n**Canonical examples on this VPS:**\n\n| Repo | Domain | Port | Notes |\n|------|--------|------|-------|\n| `\u002Froot\u002Fsrc\u002Frepos\u002Fai-agency` | Dropshipping | **7777** | Full enterprise + Drop `:7788` |\n| `\u002Froot\u002Fsrc\u002Frepos\u002Fai-clipping` | AI clipping | **7766** | Lean Anda\u002FKIP base (10a\u002F5t\u002F4wf) |\n\nWhen the user wants **Anda \u002F iclabs \u002F ldclabs as the base agent framework**, follow the clipping pattern: local `kip_memory\u002F` + factory auto-attach `anda_brain` + optional `ANDA_NEXUS_URL`. Detail: `references\u002Fmulti-agency-anda-scaffold.md`.\n\n## When to Use\n\n- New Agno `Agent` \u002F `Team` \u002F `Workflow` + `AgentOS` project\n- **Second\u002Fthird agency** on the same host (port isolation, shared SuperGrok, forked foundation)\n- Expand an agency with domain agents (ops, retention, compliance, finance, clipping)\n- Wire Grok via SuperGrok OAuth or `XAI_API_KEY`\n- Attach Parallel Search\u002FExtract\u002FTask\u002FFindAll\u002FMonitor as agent tools\n- Author Agno `skills\u002F\u003Cpack>\u002F\u003Cname>\u002FSKILL.md` (not Hermes skills)\n- SOTA agent design: markdown personas, scoped skills, toolbelts, output schemas, evals\n- Enable AgentOS as MCP server for Hermes (or other MCP clients)\n- Hybrid FastMCP + ACP gateway on one port (see Drop pattern)\n- Fix paste-pack scaffolds that break on current Agno or Parallel APIs\n\nDon'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` \u002F `parallel-*`); OpenHands dual-auth UI (`openhands-llm-auth`); Hermes skill authoring (`hermes-agent-skill-authoring`).\n\n## Prerequisites\n\n- Project venv (never pollute system\u002FHermes site-packages)\n- `PARALLEL_API_KEY` — env, or `\u002Froot\u002F.config\u002Fparallel\u002Fapi.env`, or `~\u002F.hermes\u002F.env`\n- xAI: `XAI_API_KEY` **or** device-code OAuth (see below)\n- Offline Agno docs: skill `docs-agno` + FTS DB (external corpus; do not patch that skill)\n- `PyYAML` comes with Agno for LocalSkills frontmatter\n\n```bash\npython3 -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install -U \"agno[os,mcp]\" openai httpx python-dotenv uvicorn parallel-web \\\n  opentelemetry-api opentelemetry-sdk openinference-instrumentation-agno \\\n  fal-client agent-client-protocol\n# fastmcp comes via agno[mcp] — required for AgentOS(mcp_server=...)\n```\n\n## Canonical layout (SOTA)\n\n```text\napp\u002Fmain.py                 # AgentOS + optional mcp_server=MCPServerConfig\nagents\u002F_factory.py          # persona md + scoped skills + toolbelts + schemas\nagents\u002Fprofiles.py          # declarative per-agent config\nagents\u002Fprompt_loader.py     # SOUL\u002FSYSTEM\u002FOUTPUT\u002FEXAMPLES\nagents\u002Fschemas.py           # Pydantic handoff contracts\nagents\u002F__init__.py          # LIGHT only — no eager roster imports\nagents\u002F*.py                 # thin wiring only\nprompts\u002F\u003Cagent>\u002F{SOUL,SYSTEM,OUTPUT,EXAMPLES}.md\nprompts\u002Fteams\u002F\u003Cteam>\u002FSYSTEM.md\nteams\u002F_factory.py + teams\u002F*.py\nworkflows\u002F*.py              # Step(name=..., team=...)\ntools\u002Fxai_oauth_pkce.py | xai_model.py | parallel_tools.py\ntools\u002Fskills_loader.py      # skills_for(*names) scoped LocalSkills\ntools\u002Ftoolbelts.py          # role-shaped tool sets\ntools\u002Fguardrails.py         # L2 autonomy tool_hooks\ntools\u002Fmcp_custom.py         # optional custom \u002Fmcp tools\ntools\u002Fanda_knowledge.py     # Anda brain tools (when Anda-base)\nkip_memory\u002F                 # local KIP + Brain (when Anda-base)\nknowledge\u002Fanda\u002F             # offline ldclabs docs slice\nskills\u002F{agency,\u003Cdomain>,agents}\u002F\u003Cname>\u002FSKILL.md\nevals\u002Frun_agent_evals.py    # structural evals\ntests\u002Ftest_*.py             # pytest multi-gate (required for new agencies)\nscripts\u002Fstart_agentos.sh\nSOUL\u002F + AGENTS.md + .hermes.md\n```\n\n## Procedure\n\n1. **Model factory (import-safe)**  \n   Resolve token inside `get_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.\n\n2. **xAI credentials (order)**  \n   1. `XAI_API_KEY`  \n   2. Project store `~\u002F.config\u002F\u003Cagency-slug>\u002Fxai_oauth.json` (mode 600) — e.g. `ai-agency` or `ai-clipping`  \n   3. Fallback: sibling agency store and\u002For Hermes `~\u002F.hermes\u002Fauth.json` provider `xai-oauth`  \n   CLI: `python -m tools.xai_oauth_pkce login|status|logout`  \n   Flow is **device code** (RFC 8628), not browser PKCE — filename is historical.  \n   When forking OAuth helper code, retarget `DEFAULT_TOKEN_PATH` and allow reading the other agency’s store so SuperGrok login is shared.\n\n3. **SOTA agent brain (prefer over inline instruction lists)**  \n   - **Always-on:** `prompts\u002F\u003Cagent>\u002FSOUL.md` + `SYSTEM.md` → `instructions`  \n   - **Contract:** `OUTPUT.md` → `expected_output` + Pydantic `output_schema`  \n   - **Few-shot:** `EXAMPLES.md` → `additional_input`  \n   - **On-demand playbooks:** Agno LocalSkills via `skills_for(\"a\",\"b\")` — **not** the full library on every agent  \n   - **Tools:** named toolbelts (`parallel_research`, `economics`, …) — not “everyone gets Parallel”  \n   See `references\u002Fpersona-packs-and-toolbelts.md`.\n\n4. **Agent factory**  \n   ```python\n   build_agent(\n     name=..., role=..., persona=\"product_scout\",\n     toolbelts=(\"parallel_research\",\"economics\",\"linear\"),\n     skill_names=(\"product-scoring\",\"unit-economics\"),\n     output_schema=ProductCandidateBatch,\n     add_history_to_context=False,  # True for Ops\u002FCS\u002FGrowth\u002FFinance\n     use_json_mode=True,\n   )\n   ```\n   Keep `agents\u002F*.py` thin; iterate prompts in markdown.  \n   Anda-base factories also auto-append `anda_brain` + `hermes_bridge` unless `AGENCY_DISABLE_*`, and inject a short recall→formation protocol (no secrets in KIP).\n\n5. **Agents \u002F teams**  \n   **Teams must use the enum**, not a bare string:\n   ```python\n   from agno.team.mode import TeamMode\n   Team(mode=TeamMode.coordinate, members=[...], skills=skills_for(...), ...)\n   ```\n   Do **not** pass `show_tool_calls` (removed on current Agno Agent).  \n   Scope team skills to the union of member domains — avoid global skill dump.\n\n6. **Workflows**  \n   Use `from agno.workflow import Step, Workflow` and `Step(name=..., team=...)`.  \n   Dict steps `{\"name\": ..., \"team\": ...}` are outdated and break.\n\n7. **Agno LocalSkills**  \n   `skills_for(*names)` loads individual skill folders (exact name match). Empty `skills_for()` = all packs (legacy).  \n   Each skill folder name == frontmatter `name` (lowercase, hyphens). Progressive tools: `get_skill_instructions` \u002F `get_skill_reference` — skill names are **not** callable.  \n   See `references\u002Fagno-localskills.md`.\n\n8. **AgentOS + optional MCP server**  \n   ```python\n   from agno.os.config import MCPServerConfig\n   agent_os = AgentOS(\n     ...,\n     tracing=True,\n     mcp_server=MCPServerConfig(\n       enable_builtin_tools=True,\n       tools=get_mcp_custom_tools(),  # optional\n       allowed_hosts=[\"localhost\",\"127.0.0.1\"],\n       result_mode=\"trimmed\",\n     ),\n   )\n   ```\n   Requires `agno[mcp]` \u002F `fastmcp`. Endpoint: **`\u002Fmcp`** (Streamable HTTP).  \n   Built-ins: `get_agentos_config`, `run_agent`, `run_team`, `run_workflow`, `continue_run`, `cancel_run`, `get_sessions`, `get_session_runs`.  \n   Hermes registration: skill `ai-dropshipping-agency-mcp` + `references\u002Fagentos-mcp-server.md`.\n\n9. **Hybrid FastMCP + ACP gateway (optional second port)**  \n   When external clients need Linear + reasoning + lifecycle on one URL (ai-agency Drop pattern):\n   ```python\n   mcp = FastMCP(\"drop-…\")\n   mcp_app = mcp.streamable_http_app()  # already routes \u002Fmcp\n\n   @asynccontextmanager\n   async def lifespan(app):\n       async with mcp.session_manager.run():  # REQUIRED\n           yield\n\n   Starlette(routes=[Route(\"\u002Fhealth\", …), Mount(\"\u002F\", app=mcp_app)], lifespan=lifespan)\n   ```\n   ACP stdio: `agent-client-protocol` + `python -m drop_server.acp_agent`.  \n   Ops details: skill `ai-agency-enterprise-ops` → `references\u002Fdrop-mcp-acp-gateway.md`.\n\n10. **Parallel tools**  \n    Prefer `parallel` SDK; REST fallback with `x-api-key`. Task: `parallel_task(..., processor=\"ultra\", wait=True, timeout_s=3600)` for deep research. Search quirks below.\n\n11. **Autonomy hooks**  \n    Default L2: `tool_hooks` block irreversible live actions and agent self-confirm. Dropshipping: active Shopify publish \u002F spend confirm; Meta\u002FTikTok launch needs HITL tokens. Clipping: live publish + rights auto-clear blocked; `request_publish_approval` surfaces human code once.\n\n12. **End-to-end agency shapes**  \n    - Dropshipping: Research → Supply → Creative → Store Ops + Compliance → Growth → Retention → Director\u002FFinance.  \n    - Clipping: Source → Transcript → Viral moments → Edit → Captions → Package → Rights → HITL publish → KIP learnings.\n\n13. **Scaffold a new agency from an existing one (multi-agency)**  \n    Prefer **copy foundation modules**, not the whole roster. Full checklist: `references\u002Fmulti-agency-anda-scaffold.md`.\n    1. Empty repo + project `.venv`.\n    2. Copy reusable tools + optional entire `kip_memory\u002F` + Anda docs slice.\n    3. **Rewrite** `agents\u002F__init__.py` light (never copy ai-agency eager imports).\n    4. Retarget identity: OAuth path, Parallel UA, KIP `$self`, `formation(space=)`, skill roots, AgentOS id\u002Fport.\n    5. Unique port (7777 taken by dropshipping → clipping uses **7766**).\n    6. Domain tools + thin agents + personas + profiles + teams + workflows.\n    7. Hermes SOUL wiring (`hermes-project-soul`).\n    8. Gates: structural evals **and** pytest; offline env disables bridge\u002Fbrain\u002Fknowledge.\n    9. Reset `kip_memory\u002Fdata\u002F*.db` after genesis identity retarget if already bootstrapped.\n\n## Pitfalls\n\n- **`Team(mode=\"coordinate\")` breaks AgentOS `\u002Fteams`** — schema does `team.mode.value`. Always `TeamMode.coordinate`.\n- **LocalSkills YAML** — quote `description:` when it contains `:`.\n- **Directory name == skill `name`** — lowercase hyphens only.\n- **Do not load all skills on every agent** — scopes tokens and attention; Creative should not load `supplier-vetting`.\n- **Inline instruction lists do not scale** — move brains to `prompts\u002F\u003Cagent>\u002F*.md`; keep Python thin.\n- **Parallel Search has no `max_results`** — 422 `extra_forbidden`. Use `max_chars_total` if needed.\n- **Search modes** — only `turbo` | `basic` | `advanced` (alias `fast`→`turbo`, `one-shot`→`basic`).\n- **Task ultra is slow** — `wait=True` + timeout ≥ 3600; Hermes MCP server timeout must match.\n- **OAuth HTTP 403 on refresh** — tier gate; use `XAI_API_KEY`; do not loop device-code.\n- **MCP needs `agno[mcp]`\u002Ffastmcp** — without it `mcp_server=True` fails at get_app\u002Fserve.\n- **MCP tools inject at Hermes process start** — restart TUI\u002Fgateway after `hermes mcp add`.\n- **`hermes mcp add` is interactive** — non-interactive: `printf 'n\\nY\\n' | hermes mcp add ...` (n = no auth for local open MCP).\n- **Custom FastMCP + Starlette** — lifespan `session_manager.run()` required; mount at `\u002F` not nested `\u002Fmcp`.\n- **Autonomy L2** — never let agents self-confirm spend\u002Fpublish; launch\u002Fpublish needs HITL tokens.\n- **Tracing deps** — opentelemetry + openinference-instrumentation-agno.\n- **Install into project `.venv`** — never global hermes site-packages.\n- **Hermes skills ≠ Agno skills** — different packages and frontmatter.\n- **DIM shipping** — `billable_g = max(weight_g, L*W*H\u002F5)` grams; no extra ×1000.\n- **Copying `agents\u002F__init__.py` from ai-agency** — eager-imports every dropshipping agent → `ModuleNotFoundError`. Keep `__init__` empty\u002Flight.\n- **Port clash** — second AgentOS must not bind **7777** if dropshipping is live; clipping uses **7766**.\n- **Forked `kip_memory` still says Dropshipping** — retarget nexus `$self` + `formation(space=...)` + domain genesis capsule; delete local `nexus.db` after fix.\n- **skills_loader roots** — new agencies need their own pack dirs (e.g. `skills\u002Fclipping\u002F`), not dead `marketing\u002F`\u002F`ops\u002F` copies.\n- **Structural evals alone** — also ship `tests\u002F` pytest; prefer multi-gate verification over “smoke only”.\n\n## Verification\n\n```bash\nsource .venv\u002Fbin\u002Factivate && export PYTHONPATH=.\nexport XAI_API_KEY=missing-ci-placeholder\nexport AGENCY_DISABLE_HERMES_BRIDGE=1 AGENCY_DISABLE_ANDA_BRAIN=1 AGENCY_DISABLE_ANDA_KNOWLEDGE=1\nruff check agents app tools teams workflows evals scripts kip_memory tests\npytest tests\u002F -q\npython -m evals.run_agent_evals\npython -m tools.xai_oauth_pkce status\n# Ports: ai-agency :7777 · ai-clipping :7766 · drop :7788 · hermes-bridge :7790\ncurl -s localhost:7777\u002Fhealth            # dropshipping\ncurl -s localhost:7766\u002Fhealth            # clipping\ncurl -s localhost:7777\u002Finfo | jq .mcp\ncurl -s localhost:7777\u002Fteams             # TeamMode enum\nhermes mcp test ai-agency\nhermes mcp test ai-clipping              # after mcp add :7766\u002Fmcp\nhermes mcp test drop                     # if Drop registered\n```\n\nLive Parallel smoke: `parallel_search(..., mode=\"basic\")` → `search_id` + results.\n\nAd-hoc verify pattern: `\u002Ftmp\u002Fhermes-verify-*.py` with project venv, delete after (not CI).\n\n## References\n\n- `references\u002Fmulti-agency-anda-scaffold.md` — fork ai-agency → new domain (clipping) with Anda\u002FKIP base\n- `references\u002Fpersona-packs-and-toolbelts.md` — SOTA agent layering (md + skills + schemas)\n- `references\u002Fagentos-mcp-server.md` — MCPServerConfig, built-ins, Hermes register\n- `references\u002Fparallel-search-api-quirks.md` — Search request shape\n- `references\u002Fparallel-task-ultra.md` — Task wait\u002Fultra product-rank pattern\n- `references\u002Fxai-device-code-standalone.md` — OAuth module contract\n- `references\u002Fagno-localskills.md` — LocalSkills validation\n- `references\u002Fagentos-team-mode.md` — TeamMode + `\u002Fteams`\n- `references\u002Fenterprise-lifecycle-tools.md` — lifecycle tool map\n- `references\u002Fhitl-spend-and-ads.md` — spend vault + Meta\u002FTikTok\n- Live dropshipping ops: skill **`ai-agency-enterprise-ops`** + user-owned **`ai-dropshipping-agency-mcp`**\n- Anda\u002FKIP ops: skill **`anda-ecosystem`** · SOUL wiring: **`hermes-project-soul`**\n- Drop hybrid gateway ops: `ai-agency-enterprise-ops` → `references\u002Fdrop-mcp-acp-gateway.md`\n- Offline Agno: `docs-agno` · Parallel umbrella: `parallel-web` (external)\n- SuperGrok protocol: `openhands-llm-auth` → `references\u002Fxai-supergrok-oauth.md`\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":48,"description":7},"Hermes Agent","1.4.0",{"hermes":27},{"tags":28,"related_skills":41},[29,30,31,32,33,34,35,36,37,38,39,40],"agno","agentos","grok","xai","parallel","multi-agent","workflows","skills","localskills","anda","kip","multi-agency",[42,43,44,45,46,47],"openhands-llm-auth","hermes-agent-skill-authoring","ai-dropshipping-agency-mcp","ai-agency-enterprise-ops","anda-ecosystem","hermes-project-soul",[49,50,51],"linux","macos","windows","main","1532f6e28b7d7cc5ae38dfe70c4e886157e8f01e",".aimee\u002Fskills\u002Fagno-agentos-apps",0,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes","https:\u002F\u002Fgithub.com\u002Fswcstudiospace","https:\u002F\u002Fwww.swcstudio.space\u002F","APAC's premier WEB3.ARL Studio for programming advanced best-in-class innovations'","2026-11-11 21:45:42",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add swcstudiospace\u002Faimeecodes --skill agno-agentos-apps",{"tool":67,"command":68},"bunx","bunx skills add swcstudiospace\u002Faimeecodes --skill agno-agentos-apps",{"tool":70,"command":71},"pnpm","pnpm dlx skills add swcstudiospace\u002Faimeecodes --skill agno-agentos-apps","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002FSKILL.md",true,[75,81,85,89,93,97,101,105,109,113,117],{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Fagentos-mcp-server.md","REFERENCE","参考文档",1892,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fagentos-mcp-server.md",{"path":82,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":83,"sourceHtmlUrl":84},"references\u002Fagentos-team-mode.md",997,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fagentos-team-mode.md",{"path":86,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":87,"sourceHtmlUrl":88},"references\u002Fagno-localskills.md",2618,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fagno-localskills.md",{"path":90,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":91,"sourceHtmlUrl":92},"references\u002Fai-agency-ops-from-hermes.md",2525,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fai-agency-ops-from-hermes.md",{"path":94,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":95,"sourceHtmlUrl":96},"references\u002Fenterprise-lifecycle-tools.md",1792,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fenterprise-lifecycle-tools.md",{"path":98,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":99,"sourceHtmlUrl":100},"references\u002Fhitl-spend-and-ads.md",1684,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fhitl-spend-and-ads.md",{"path":102,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":103,"sourceHtmlUrl":104},"references\u002Fmulti-agency-anda-scaffold.md",3554,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fmulti-agency-anda-scaffold.md",{"path":106,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":107,"sourceHtmlUrl":108},"references\u002Fparallel-search-api-quirks.md",1445,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fparallel-search-api-quirks.md",{"path":110,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":111,"sourceHtmlUrl":112},"references\u002Fparallel-task-ultra.md",1329,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fparallel-task-ultra.md",{"path":114,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":115,"sourceHtmlUrl":116},"references\u002Fpersona-packs-and-toolbelts.md",2045,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fpersona-packs-and-toolbelts.md",{"path":118,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":119,"sourceHtmlUrl":120},"references\u002Fxai-device-code-standalone.md",1663,"https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fagno-agentos-apps\u002Freferences\u002Fxai-device-code-standalone.md",[122,129,136,143,150,157],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":19},"01M7AW01SRKZDGAMSENA2KKV1C","xurl","X\u002FTwitter via xurl CLI: raw post search, posting, DM, media.","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fxurl\u002FSKILL.md",[],[],{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":19},"01M7AVZKD3FMV3ZPX50DY7XZZR","weights-and-biases","W&B: log ML experiments, sweeps, model registry, dashboards.","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fweights-and-biases\u002FSKILL.md",[],[],{"skillNo":137,"name":138,"nameZh":6,"description":139,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":140,"categories":141,"keywords":142,"publishedAt":19},"01M7AVZEY5AS893YVWYY4DFQKK","touchdesigner-mcp","Control TouchDesigner via twozero MCP.","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Ftouchdesigner-mcp\u002FSKILL.md",[],[],{"skillNo":144,"name":145,"nameZh":6,"description":146,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":147,"categories":148,"keywords":149,"publishedAt":19},"01M7AVZ4K45X76C09FQQMC9GH0","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":156,"publishedAt":19},"01M7AVZ029D94C9HNET2TYTHNZ","technical-docs-corpora","Use when bulk-crawling public tech docs into agent skills.","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Ftechnical-docs-corpora\u002FSKILL.md",[],[],{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":163,"publishedAt":19},"01M7AVYTXSJWYYD7GZMTTR9BC0","teams-meeting-pipeline","Teams meeting summaries, job replay, Graph subscriptions.","https:\u002F\u002Fgithub.com\u002Fswcstudiospace\u002Faimeecodes\u002Fblob\u002Fmain\u002F.aimee\u002Fskills\u002Fteams-meeting-pipeline\u002FSKILL.md",[],[]]