Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/agno

<!--
CIANCHOSAINT wholesale-copy of cianfhoghlaim/cianfhoghlaim @ main branch.

Original: cianfhoghlaim/cianfhoghlaim (per the openspec/changes/cianchosaint-repo-bootstrap-v2/specs/cianchosaint-bootstrap-v2/spec.md).
Migrated to cianchosaint: 2026-08-23
Licence: BUSL-1.1 (per LICENSE.md)

Wholesale-copied from cianfhoghlaim/cianfhoghlaim@agno/SKILL.md.
-->
---
name: agno
description: Expert assistance for building AI agent systems with Agno (formerly PhiData) v2.0+. Use when users need multi-agent orchestration via the A2A Protocol, AgentOS production hosting, Z.ai GLM-4.6 via OpenAILike, agentic chunking, native Browserbase MCP integration, or Dagster+DLT+Agno Cianfhoghlaim integration.
---

# Agno - AI Agent Framework

**Version:** >=2.0.0 | **Last Updated:** 2026-06

## Overview

Agno (formerly PhiData) is a high-performance framework for
building AI agents with a unique architecture:

- **Agent Orchestration** — single agents, multi-agent teams,
  and explicit workflows. Fully stateless design.
- **AgentOS** — a production-ready API for hosting agents,
  teams, and workflows. OpenAPI at
  `https://raw.githubusercontent.com/agno-agi/agno-docs/main/reference-api/openapi.json`.
- **AGUIInterface** — built-in AG-UI SSE adapter for
  CopilotKit integration.
- **A2A Protocol** — agent-to-agent communication (route /
  coordinate / collaborate team modes).
- **Tool Calling** — any Python function becomes a tool with
  auto-generated schema (signature + docstring).
- **Unified Media** — images, audio, video, files all
  handled the same way.
- **Memory Systems** — persistent agent memory across sessions
  via unified DB structure (Postgres / SQLite).
- **Knowledge Bases** — RAG with `async` insert / fetch;
  **agentic chunking** pattern.
- **Multi-Model Support** — OpenAI, Anthropic, Google, local
  models, **Z.ai GLM-4.6 via `OpenAILike`**.
- **Knowledge Graphs** — native support for graph-based
  knowledge representation.

**Documentation:** <https://docs.agno.com>

## When to Use This Skill

Activate when users need:

- "Build an AI agent with tools and memory"
- "Create a multi-agent team with route / coordinate / collaborate
  modes"
- "Host agents in production with AgentOS + OpenAPI"
- "Wire the AG-UI SSE protocol to a CopilotKit UI"
- "Use Z.ai GLM-4.6 (or any OpenAI-compatible model)"
- "Add agentic chunking to a knowledge base"
- "Integrate with Browserbase for browser automation"
- "Build the Cianfhoghlaim 5-stage Dagster+DLT+Agno pipeline"

## Cianfhoghlaim context (PRESERVED + extended)

- LLM backend: **LiteLLM gateway** (routes to OpenAI, Anthropic,
  Google, Z.ai, etc.)
- Tracing: **Langfuse** (project tracing)
- Memory: **Postgres** (unified DB structure) or **SQLite**
  for dev
- Knowledge base: **LanceDB** (BGE-M3 embeddings) or
  **PgVector** for Postgres-native
- Knowledge graph: **FalkorDB** (the Cianfhoghlaim primary) or
  **Memgraph** for Cypher
- The Cianfhoghlaim agent chain: **OCR → BAML → embedding → Graphiti
  → RAGAS** (5 SequentialAgents in a Dagster asset)
- Dagster wiring: `cianfhoghlaim-curriculum-extraction` runs the
  agent chain against NCCA PDFs
- DLT wiring: `@dlt.destination` writes the BAML output to
  DuckLake

## Domain-specific agent teams (Cianfhoghlaim)

For the Cianfhoghlaim platform, the standard agent team is:

```python
from agno.team import Team
from agno.models.openai.like import OpenAILike

# Cianfhoghlaim uses Z.ai GLM-4.6 for cost + speed, with OpenAI as fallback
model = OpenAILike(
    id="glm-4.6",
    base_url="https://api.z.ai/v1",
    api_key=os.environ["Z_AI_API_KEY"],
)

team = Team(
    name="curriculum_team",
    mode="coordinate",  # coordinator routes to specialists
    members=[
        curriculum_agent,   # NCCA + SEC + DES specialist
        translation_agent,  # EN → GA translation
        corpus_agent,       # leabharlann corpus specialist
        geospatial_agent,   # Gaeltacht + heritage site specialist
        statistics_agent,   # CSO + DES education statistics
        research_agent,     # Zotero + Gemini deep research
    ],
    model=kcg_model,
)
```

The 6 domain agents correspond to the 6 "Domain Agent" surfaces
in the `meaisínfhoghlaim-platform` spec.

## Core Agent

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    name="curriculum_extractor",
    model=OpenAIChat(id="gpt-4o-mini"),
    instructions=[
        "Extract the curriculum area, strands, and learning outcomes.",
        "Always return a CurriculumArea object, not free text.",
    ],
    tools=[pdf_extractor, schema_validator],
    markdown=True,
    # Memory + knowledge base
    db=postgres_db,
    knowledge=lancedb_kb,
    # Stream intermediate results
    stream=True,
)

response = agent.run("Extract from this NCCA Primary PDF...")
```

**Key parameters:**

- `name` — required; used in observability
- `model` — `OpenAIChat`, `AnthropicChat`, `Gemini`, `OpenAILike`
  (for any OpenAI-compatible API like Z.ai, vLLM, llama.cpp)
- `instructions` (list) — preferred over `system_prompt` (which
  is also supported for backward compatibility)
- `tools` (list) — Python functions, MCP servers, or
  pre-built tools
- `db` — session memory store
- `knowledge` — RAG knowledge base
- `markdown` — render output as markdown (for CopilotKit UI)
- `stream` — return `AsyncIterator` of intermediate events

## Tools (Python functions)

Any Python function with a type-annotated signature and
docstring becomes a tool:

```python
from agno.tools import tool

@tool
def get_weather(city: str) -> dict:
    """Get the current weather for a city.

    Args:
        city: The city name, e.g. "Dublin" or "Galway".

    Returns:
        A dict with 'temperature', 'conditions', 'humidity' keys.
    """
    response = fetch(f"https://api.weather.com/{city}")
    return response.json()

agent = Agent(tools=[get_weather])
```

The function's signature + docstring are auto-extracted into
the tool schema (name, description, parameters, types).

## Browserbase MCP Integration

```python
from agno.tools.mcp import MCPTools

browserbase = MCPTools(
    command="npx",
    args=["@browserbasehq/mcp-server-browserbase"],
    env={
        "BROWSERBASE_API_KEY": os.environ["BROWSERBASE_API_KEY"],
    },
)

agent = Agent(
    name="scraper",
    model=OpenAIChat(id="gpt-4o"),
    tools=[browserbase, stagehand],
    instructions=["Scrape the SEC EDGAR filings and extract the 10-K summary."],
)
```

The MCP server runs as a subprocess; Agno handles the JSON-RPC
transport.

## Z.ai GLM-4.6 via `OpenAILike`

```python
from agno.models.openai.like import OpenAILike

z_ai = OpenAILike(
    id="glm-4.6",
    base_url="https://api.z.ai/v1",
    api_key=os.environ["Z_AI_API_KEY"],
)

agent = Agent(name="kcg_translator", model=z_ai)
```

Z.ai's GLM-4.6 is a fast, cheap Chinese model that performs
well on translation + structured extraction. Cianfhoghlaim uses it as
the cost-effective default, with OpenAI / Anthropic as
fallback for high-stakes calls.

## Multi-Agent Teams

Agno teams have 3 modes (all using the A2A Protocol internally
for inter-agent communication):

| Mode | When |
|:--|:--|
| `route` | Coordinator routes to ONE sub-agent based on the request |
| `coordinate` | Coordinator routes to multiple sub-agents and combines |
| `collaborate` | All sub-agents work on the task together, with shared state |

```python
from agno.team import Team

team = Team(
    name="multi_perspective",
    mode="coordinate",
    members=[linguistic_agent, cultural_agent, historical_agent],
    model=OpenAIChat(id="gpt-4o"),
    instructions=[
        "Coordinate the team to analyze this poem.",
        "Each member contributes their perspective.",
    ],
)

response = team.run("Analyze the poem 'An Cailín Rua' by Ó Rathaille.")
```

## A2A Protocol

For cross-agent / cross-vendor communication, the A2A Protocol
is built in:

```python
from agno.os.a2a import A2AInterface

# Expose this agent as an A2A server
a2a = A2AInterface(
    agent=my_agent,
    agent_card_url="https://my-agent.example.com/.well-known/agent.json",
)

# Or consume a remote A2A agent
from agno.os.a2a import A2AClient

client = A2AClient("https://remote-agent.example.com")
result = client.call("extract_curriculum", {"pdf_url": "..."})
```

## AgentOS (production hosting)

```python
from agno.os import AgentOS

agent_os = AgentOS(
    agents=[kcg_team, curriculum_agent, translation_agent],
    # The OpenAPI spec is auto-generated
)

# Serve via FastAPI
app = agent_os.get_app()
# Or via Uvicorn directly
agent_os.serve("agent_os:app", host="0.0.0.0", port=8000)
```

The OpenAPI spec is at
`https://raw.githubusercontent.com/agno-agi/agno-docs/main/reference-api/openapi.json`
— use it to generate client SDKs (Python, TS, Go, etc.).

## AG-UI Interface (CopilotKit SSE)

```python
from agno.os.agui import AGUIInterface

agui = AGUIInterface(agent=kcg_team)

# Mount under any FastAPI app
from fastapi import FastAPI
app = FastAPI()
app.mount("/agui", agui.app)
```

The CopilotKit frontend auto-detects the AG-UI protocol and
consumes the SSE stream. See `.agents/skills/ag-ui/SKILL.md` for
the full protocol.

## Agentic Chunking

The canonical pattern for adding LLM-aware chunking to a
knowledge base:

```python
from agno.knowledge.chunking import AgenticChunker

chunker = AgenticChunker(
    model=OpenAIChat(id="gpt-4o-mini"),
    # The LLM reads the document and decides how to split
    # (respects headers, sections, code blocks, etc.)
    max_chunk_size=2000,
)

agent = Agent(
    knowledge=lancedb_kb,
    knowledge_chunking=chunker,
)
```

`AgenticChunker` is better than fixed-size chunking for
documents with semantic structure (e.g. NCCA syllabi,
Zotero papers, leabharlann books).

## Hybrid Search SQL

For knowledge base queries, the canonical pattern is hybrid
(vector + full-text + RRF reranking) via SQL:

```python
from agno.knowledge.search import HybridSearch

search = HybridSearch(
    vector=lancedb_vector,
    full_text=tantivy_fts,
    reranker=RRFReranker(k=60),  # Reciprocal Rank Fusion
)

agent = Agent(knowledge_search=search)
```

Or use the SQL-level pattern:

```sql
SELECT filename, text,
    (1.0 - (embedding <=> $1)) AS vector_score,
    ts_rank(fts, plainto_tsquery('english', $2)) AS fts_score,
    (1.0 - (embedding <=> $1)) * 0.7 + ts_rank(fts, plainto_tsquery('english', $2)) * 0.3 AS combined_score
FROM chunks
ORDER BY combined_score DESC
LIMIT 10
```

## DynamicKnowledge (extending the KB at runtime)

```python
from agno.knowledge import DynamicKnowledge

# A knowledge base that can be updated at runtime
class CurriculumDynamicKnowledge(DynamicKnowledge):
    def update(self, source_path: str):
        """Re-index the source directory."""
        for pdf in Path(source_path).glob("**/*.pdf"):
            doc = self.load(pdf)
            self.add(doc)
```

## Memory and Context

```python
from agno.memory import PostgresMemory

memory = PostgresMemory(
    db_url="postgresql://user:pass@localhost:5432/agno",
    table_name="agent_memory",
)

agent = Agent(
    name="tutor",
    model=OpenAIChat(id="gpt-4o"),
    memory=memory,
    add_history_to_messages=True,  # include past messages in context
    num_history_messages=10,
)
```

For production, use Postgres. For dev, SQLite is fine.

## Cianfhoghlaim integration: Dagster + DLT + Agno

The Cianfhoghlaim 5-stage pipeline is a Dagster asset that orchestrates
5 Agno agents:

```python
# orchestration/defs/curriculum_assets.py
from dagster import asset, AssetExecutionContext
from agno.os import AgentOS
from cianfhoghlaim.agents.agno import (
    ocr_agent, baml_extractor, embedder, graphiti_agent, ragas_evaluator
)

@asset(group_name="curriculum")
def ireland_curriculum_extraction(context: AssetExecutionContext):
    """Run the 5-stage Cianfhoghlaim agent chain against an NCCA PDF."""
    pipeline = AgentOS(agents=[
        ocr_agent, baml_extractor, embedder, graphiti_agent, ragas_evaluator,
    ])
    result = pipeline.run_agent("ocr_to_kg_pipeline", {
        "pdf_path": "stedding/ingest_queue/ncca/primary_math_2024.pdf",
    })
    return result
```

The asset writes to DuckLake via a custom `@dlt.destination`.

## GitHub repo analyzer example

```python
from agno.tools.github import GitHubTools

agent = Agent(
    name="github_analyzer",
    model=OpenAIChat(id="gpt-4o"),
    tools=[GitHubTools(token=os.environ["GITHUB_TOKEN"])],
    instructions=[
        "Analyze the GitHub repository.",
        "Return a summary of the README, the top 5 files by commit count, "
        "and any open issues with 'help wanted' label.",
    ],
)

result = agent.run("https://github.com/agno-agi/agno")
```

## Best practices

1. **Use `OpenAILike` for any OpenAI-compatible API** (Z.ai,
   vLLM, llama.cpp, Ollama) — `OpenAIChat` is OpenAI-specific
2. **Use `team.mode="coordinate"` for multi-perspective tasks**
3. **Use `AgentOS` for production hosting** — never
   `uvicorn agent:app` directly
4. **Use `AGUIInterface` for CopilotKit UI integration** —
   auto-handles SSE + event protocol
5. **Use `AgenticChunker` for documents with semantic
   structure** — fixed-size chunking is a last resort
6. **Use `HybridSearch` with `RRFReranker`** for knowledge
   base queries — pure vector search misses keyword matches
7. **Always add memory to long-running agents** — stateless
   agents forget everything between turns
8. **Stream intermediate events to the UI** — don't wait for
   the full response

## Common issues

### Agent not using tools
- Verify the function has a docstring
- Verify the parameters have type annotations
- Check the model is multi-modal-capable (some cheap models
  are text-only)

### Memory not persisting
- Verify the DB connection
- Check `add_history_to_messages=True`
- Ensure `session_id` is consistent across calls

### Knowledge base empty
- Run `agent.knowledge.load()` first
- Check vector DB connection
- Verify documents are in the correct path

## Resources

- **Documentation:** <https://docs.agno.com>
- **OpenAPI spec:**
  <https://raw.githubusercontent.com/agno-agi/agno-docs/main/reference-api/openapi.json>
- **GitHub:** <https://github.com/agno-agi/agno>
- **Examples:** <https://github.com/agno-agi/agno/tree/main/cookbook>
- **Z.ai GLM-4.6:** <https://docs.z.ai/guides/llm/glm-4.6>
- **A2A Protocol:** <https://a2a.dev/>
- **AG-UI Protocol:** <https://ag-ui.com/>
- **Cianfhoghlaim Dagster asset:** `orchestration/defs/curriculum_assets.py`
- **Related skills:** `.agents/skills/google-adk/`,
  `.agents/skills/pydantic-ai/`, `.agents/skills/litellm/`,
  `.agents/skills/langfuse/`, `.agents/skills/cognee/`,
  `.agents/skills/falkordb/`

## Framework comparison (when to use Agno vs Google ADK / Pydantic AI)

| Use case | Agno | Google ADK | Pydantic AI |
|:--|:--|:--|:--|
| Multi-agent teams (route / coordinate / collaborate) | ✅ first-class | ✅ | ⚠️ via DBOS |
| AgentOS production hosting | ✅ | ✅ Agent Engine | ⚠️ self-host |
| Z.ai GLM-4.6 (cost-effective) | ✅ `OpenAILike` | ⚠️ | ✅ `OpenAICompatibleModel` |
| A2A Protocol | ✅ built-in | ✅ built-in | ⚠️ via adapter |
| AG-UI SSE | ✅ `AGUIInterface` | ⚠️ via adapter | ✅ first-class |
| Tools (any Python function) | ✅ | ✅ | ✅ |
| Knowledge bases (RAG) | ✅ | ⚠️ via Vertex AI | ✅ via `pydantic_ai_agents` |
| Memory (Postgres) | ✅ | ✅ via Memory Bank | ✅ |
| Knowledge graphs (FalkorDB) | ✅ | ⚠️ | ⚠️ |
| Type-safe I/O (Pydantic) | ✅ | ✅ | ✅ first-class |
| MCP server | ✅ via adapter | ✅ built-in | ✅ via adapter |
| Modal H100 burst | ✅ | ✅ | ✅ |

**Rule of thumb**: use **Agno** for multi-agent teams with
Z.ai GLM-4.6 (cost-effective, the Cianfhoghlaim default); use
**Google ADK** for Gemini-heavy workflows (Live API, A2A,
Agent Engine); use **Pydantic AI** for type-safe I/O with
Pydantic models (the Cianfhoghlaim standard).
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall