New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Ag2 Middleware

by ag2ai in ag2ai/build-with-ag2

Intercept the AG2 beta agent loop with BaseMiddleware — wrap full turns (onturn), each LLM call (onllmcall), each tool execution (ontoolexecution), or each human-input request (onhumaninput).

Apache-2.0Auto-check passedBackend & APIs

Install Ag2 Middleware

skills CLI
$ npx skills add ag2ai/build-with-ag2 --skill ag2-middleware -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ag2ai/build-with-ag2 ag2-middleware --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ag2ai/build-with-ag2.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/ag2-middleware .claude/skills/ag2-middleware && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ag2-middleware
GitHub stars
252
Token cost
~1.9k tokens
SKILL.md length
586 words
Files
2 (incl. references)
Skills in repo
16
Repo updated
First seen
Licence
Apache-2.0

At a glance

Intercept the AG2 beta agent loop with BaseMiddleware — wrap full turns (onturn), each LLM call (onllmcall), each tool execution (ontoolexecution), or each human-input request (onhumaninput).

  • History trimming
  • SKILL.md covers When to use, Four hooks, Built-in middleware and Registration — agent-level, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Request mutation

What it does

Ag2 Middleware is an agent skill from ag2ai/build-with-ag2. Intercept the AG2 beta agent loop with BaseMiddleware — wrap full turns (onturn), each LLM call (onllmcall), each tool execution (ontoolexecution), or each human-input request (onhumaninput). Use for retry, logging, history trimming, request mutation, tool auditing, guardrails, or rate limiting. Built-ins: LoggingMiddleware, RetryMiddleware, HistoryLimiter, TokenLimiter, TelemetryMiddleware (see ag2-telemetry). For per-tool hooks see also ag2-add-custom-tool tool-middleware section.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/builtin_middleware.md`).

It sits in Backend & APIs, covering Rate limiting and Autonomous loops. The repository describes itself as: Sample code and application showcases to get you going with AG2 (formally AutoGen). The licence is Apache-2.0.

When your agent uses it

  • History trimming
  • Request mutation

Example prompts

  • “/ag2-middleware”

Requirements

  • Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit 29eeac3. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are python).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Ag2 Middleware loads about 1.9k tokens when it runs, and up to ~2.9k if it reads all its reference files. Until then it costs about 133 tokens; SKILL.md has 586 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~133
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ag2ai/build-with-ag2 at commit 29eeac3, republished under its Apache-2.0 licence (© ag2ai). 586 words, ~1,912 tokens.

Download SKILL.mdSave it as .claude/skills/ag2-middleware/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
ag2-middleware
description
Intercept the AG2 beta agent loop with `BaseMiddleware` — wrap full turns (`on_turn`), each LLM call (`on_llm_call`), each tool execution (`on_tool_execution`), or each human-input request (`on_human_input`). Use for retry, logging, history trimming, request mutation, tool auditing, guardrails, or rate limiting. Built-ins: `LoggingMiddleware`, `RetryMiddleware`, `HistoryLimiter`, `TokenLimiter`, `TelemetryMiddleware` (see `ag2-telemetry`). For per-tool hooks see also `ag2-add-custom-tool` tool-middleware section.
license
Apache-2.0

Middleware

When to use

Middleware is for cross-cutting behaviour that should apply consistently across many runs without changing the agent, model client, or tools themselves. Common use cases:

  • Logging, tracing, timing
  • Retry on transient failures
  • Trim history before it reaches the model
  • Cap or estimate token usage
  • Rewrite tool arguments / results
  • Enforce policies before a tool runs
  • Audit human-input requests

Four hooks

BaseMiddleware exposes four async hooks. Implement only the ones you need:

HookWrapsUse for
on_turn(call_next, event, context) → ModelResponseThe whole agent turnTotal latency, request/response inspection, turn-level policies
on_llm_call(call_next, events, context) → ModelResponseEach LLM API callRetry, logging, history trim, request mutation, caching
on_tool_execution(call_next, event, context) → ToolResultTypeEach tool invocationValidate args, redact results, fallback on failure, access control
on_human_input(call_next, event, context) → HumanMessageEach context.input()Audit, rewrite prompts, automated short-circuit, rate limit

Each instance is created once per turn and can hold per-turn state on self. The same instance can implement multiple hooks.

Built-in middleware

Importable from autogen.beta.middleware:

MiddlewarePurposeConstructor
LoggingMiddlewareLogs turn start/end, each LLM call, each tool executionno args
RetryMiddlewareRetries failed LLM callsmax_retries=N, retry_on=ExceptionClass
HistoryLimiterCap event count before LLM callmax_events=N
TokenLimiterChar-based token-budget cap before LLM callmax_tokens=N, chars_per_token=4
TelemetryMiddlewareOpenTelemetry GenAI spans (see ag2-telemetry)see telemetry skill

Registration — agent-level

Apply to every turn:

python
from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig
from autogen.beta.middleware import LoggingMiddleware, RetryMiddleware

agent = Agent(
    "assistant",
    config=OpenAIConfig(model="gpt-4o-mini"),
    middleware=[
        LoggingMiddleware(),
        RetryMiddleware(max_retries=2),
    ],
)

Registration — call-level

Add temporary middleware for one turn. Both agent.ask(...) and reply.ask(...) accept it:

python
from autogen.beta.middleware import TokenLimiter

reply = await agent.ask("Summarise the latest messages.", middleware=[LoggingMiddleware()])
next_turn = await reply.ask("Now answer in one paragraph.", middleware=[TokenLimiter(max_tokens=4000)])

Call-level middleware is appended after the agent's middleware list.

Ordering

Middleware runs in registration order, like nested with blocks. Registering [A, B, C] enters A → B → C and unwinds C → B → A:

enter A
  enter B
    enter C
      <LLM call>
    exit C
  exit B
exit A

This matters when you mix logging, mutation, retry. If RetryMiddleware should retry mutated requests, mutation goes inside retry; if you want each retry attempt logged separately, logging goes inside retry.

Writing your own

Subclass BaseMiddleware, implement the hooks you need:

python
import logging
from collections.abc import Sequence
from autogen.beta import Agent, Context
from autogen.beta.config import OpenAIConfig
from autogen.beta.events import BaseEvent, ModelResponse, ToolCallEvent
from autogen.beta.middleware import BaseMiddleware, LLMCall, Middleware, ToolExecution

class AuditMiddleware(BaseMiddleware):
    def __init__(self, event: BaseEvent, context: Context, logger: logging.Logger) -> None:
        super().__init__(event, context)
        self.logger = logger

    async def on_llm_call(self, call_next: LLMCall, events: Sequence[BaseEvent], context: Context) -> ModelResponse:
        self.logger.info("Calling model with %d events", len(events))
        response = await call_next(events, context)
        self.logger.info("Model returned: %s", response)
        return response

    async def on_tool_execution(self, call_next: ToolExecution, event: ToolCallEvent, context: Context):
        self.logger.info("Executing tool: %s", event.name)
        return await call_next(event, context)

agent = Agent(
    "assistant",
    config=OpenAIConfig(model="gpt-4o-mini"),
    middleware=[
        Middleware(AuditMiddleware, logger=logging.getLogger("ag2.audit")),
    ],
)

If your middleware needs constructor args beyond event and context, wrap with Middleware(YourClass, ...) when registering. Zero-config middleware can be passed bare (middleware=[LoggingMiddleware()]).

Tool-scoped vs agent-scoped

For behaviour that applies to one tool only (validation, redaction for that tool's output, approval gates), use tool middleware instead — middleware=[hook] on @tool, @agent.tool, or Toolkit. See ag2-add-custom-tool for the syntax. The approval_required() built-in (see ag2-hitl) is a tool middleware.

Agent middleware runs outside tool middleware: BaseMiddleware.on_tool_execution() sees the full execution including tool-scoped hooks.

Show full SKILL.md (206 more words)Show less

Picking the right hook

  • on_turn → behaviour about the whole request/response lifecycle.
  • on_llm_call → behaviour about what goes into / comes out of the model.
  • on_tool_execution → tool safety / auditing / result shaping across many tools.
  • Tool-scoped middleware (not BaseMiddleware) → behaviour for a single tool's definition.
  • on_human_input → intercept HITL requests/responses.

Going deeper

  • references/builtin_middleware.md — every built-in's params, common-case recipes, when each fits.
  • website/docs/beta/middleware.mdx — full reference, ordering examples, custom-middleware guidelines.
  • website/docs/beta/tools/tool_middleware.mdx — per-tool hooks (different mental model — plain async callables, not BaseMiddleware).
  • For OpenTelemetry instrumentation specifically, see ag2-telemetry.

Common pitfalls

  • Forgetting Middleware(...) for constructor args — middleware=[AuditMiddleware] (no wrapper) only works if the class needs only event and context. Otherwise wrap: middleware=[Middleware(AuditMiddleware, logger=...)].
  • Mutation order surprises — middleware runs in registration order. If middleware A trims history and middleware B logs it, register [A, B] so B sees the trimmed view.
  • Per-call middleware doesn't replace agent middleware — it's appended. Agent middleware still runs.
  • One big middleware doing five things — keep hooks focused. Logging + retry + mutation + policy in one class is hard to reason about and order. Split into multiple instances.
  • on_tool_execution branching on event.name for a single tool — that's a smell; use tool-scoped middleware for one-tool behaviour and reserve on_tool_execution for cross-cutting policies.
  • Putting OpenTelemetry instrumentation in custom code — there's a TelemetryMiddleware for that; see ag2-telemetry.

© ag2ai, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in .agents/skills/ag2-middleware of ag2ai/build-with-ag2.

  • SKILL.md
  • references/builtin_middleware.md

Open the folder on GitHubat commit 29eeac3

Compare with similar skills

Ag2 Middleware next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ag2 Middleware compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ag2 Middleware this skillag2ai/build-with-ag2252—~1.9kAutomated safety check: PassApache-2.0
Inngest AgentsAsymmetric-al/core381—~2.6kAutomated safety check: PassAGPL-3.0
Venice API Overviewveniceai/skills143—~3.5kAutomated safety check: PassMIT
Fastllm Principalsazrtydxb/Fastllm-proxy108—~865Automated safety check: PassApache-2.0
LLM Gatewaysickn33/agentic-awesome-skills47k1 repos~2.1kAutomated safety check: PassMIT
Langfuse Rate Limitsjeremylongshore/tons-of-skills-marketplace2.8k1 repos~1.8kAutomated safety check: PassMIT

Similar skills

  • Inngest Agents

    Asymmetric-al/core

    A skill your agent uses when building durable AI agents or agentic workflows with Inngest and AgentKit, including model calls, tool calls, multi-agent networks, human approval, realtime progress…

    381 GitHub stars~2.6k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Venice API Overview

    veniceai/skills

    High-level map of the Venice.ai API: base URL, auth modes per endpoint, endpoint categories, response headers, pricing model, error shape and versioning.

    143 GitHub stars~3.5k tokensUpdated 3 days ago
    Backend & APIsAuto-check passed

  • Fastllm Principals

    azrtydxb/Fastllm-proxy

    Manage FastLLM principals (API clients and users) and their API keys — create or delete principals, issue and revoke keys, attach roles, and set per-principal budgets and rate limits.

    108 GitHub stars~865 tokensUpdated 3 days ago
    Backend & APIsAuto-check passed

  • LLM Gateway

    sickn33/agentic-awesome-skills

    Deploy an API gateway for LLM traffic with load balancing, rate limiting, key management, semantic caching, fallback routing, and cost tracking.

    47k GitHub starsUsed in 1 repo~2.1k tokens
    Backend & APIsAuto-check passed

  • Langfuse Rate Limits

    jeremylongshore/tons-of-skills-marketplace

    Implement Langfuse rate limiting, batching, and backoff patterns.

    2.8k GitHub starsUsed in 1 repo~1.8k tokens
    Backend & APIsAuto-check passed

  • AWS Harness

    hoodini/ai-agents-skills

    Build a new AI agent on AWS and deploy it easily, OR wrap and deploy an agent you already have, using the Amazon Bedrock AgentCore harness.

    281 GitHub stars~4.2k tokensUpdated 2 mo ago
    Backend & APIsAuto-check: notes

More from ag2ai/build-with-ag2

All 16 skills in this repo

  • Ag2 Add Custom Tool

    ag2ai/build-with-ag2

    Add a custom Python tool to an AG2 beta Agent using the @tool decorator.

    252 GitHub stars~1.9k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Use Builtin Tools

    ag2ai/build-with-ag2

    Wire AG2 beta's shipped tools into an Agent — both provider-native server-side tools (web search, web fetch, code execution, MCP, image generation, memory) and locally-executed common toolkits…

    252 GitHub stars~1.3k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Knowledge And Memory

    ag2ai/build-with-ag2

    Persist agent state across runs, shape what the LLM sees per turn, and cap history to fit a context window.

    252 GitHub stars~2.9k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Observers And Alerts

    ag2ai/build-with-ag2

    Monitor an AG2 beta agent's stream — log events, detect repeated tool calls, track token spend, build trigger-driven observers, route observer alerts to the model, and halt on FATAL conditions.

    252 GitHub stars~2.5k tokensUpdated 1 mo ago
    Auto-check passed

  • Ag2 Quickstart

    ag2ai/build-with-ag2

    Build a minimal AG2 beta Agent end to end — pick a model provider, set a prompt, call agent.ask(), then continue the conversation with reply.ask() (multi-turn).

    252 GitHub stars~1.7k tokensUpdated 1 mo ago
    Auto-check: notes

  • Ag2 Structured Output

    ag2ai/build-with-ag2

    Get a typed Python value back from an AG2 beta Agent instead of free text.

    252 GitHub stars~1.8k tokensUpdated 1 mo ago
    Auto-check passed

Categories

Questions about Ag2 Middleware

What does Ag2 Middleware do?

Intercept the AG2 beta agent loop with BaseMiddleware — wrap full turns (onturn), each LLM call (onllmcall), each tool execution (ontoolexecution), or each human-input request (onhumaninput). Ag2 Middleware is an agent skill from ag2ai/build-with-ag2. Intercept the AG2 beta agent loop with BaseMiddleware — wrap full turns (onturn), each LLM call (onllmcall), each tool execution (ontoolexecution), or each human-input request (onhumaninput).

When should I use Ag2 Middleware?

Ag2 Middleware fits situations like: history trimming; request mutation.

How do I install Ag2 Middleware in Claude Code?

Run `npx skills add ag2ai/build-with-ag2 --skill ag2-middleware -a claude-code`. Or copy the skill folder (.agents/skills/ag2-middleware in ag2ai/build-with-ag2) into .claude/skills/ag2-middleware in your project. Claude Code loads it when a task matches its description.

How do I install Ag2 Middleware in Codex?

Run `npx skills add ag2ai/build-with-ag2 --skill ag2-middleware -a codex`. Or copy the skill folder (.agents/skills/ag2-middleware in ag2ai/build-with-ag2) into .agents/skills/ag2-middleware in your project. Codex loads it when a task matches its description.

Can I use Ag2 Middleware in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ag2ai/build-with-ag2 --skill ag2-middleware -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ag2-middleware, .gemini/skills/ag2-middleware, .github/skills/ag2-middleware and .opencode/skills/ag2-middleware in your project.

What does Ag2 Middleware need to run?

SKILL.md names no scripts, command-line tools or credentials: Ag2 Middleware is instructions for the agent only. Our summary lists: Python 3.

Does Ag2 Middleware access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Ag2 Middleware safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Ag2 Middleware use?

Ag2 Middleware is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ag2 Middleware use?

About 1.9k tokens (SKILL.md is roughly 7.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 998 tokens, read only when the agent opens those files.

What are the alternatives to Ag2 Middleware?

Skills that share tags, products or a category with Ag2 Middleware: Inngest Agents (Asymmetric-al/core, 381 stars), Venice API Overview (veniceai/skills, 143 stars), Fastllm Principals (azrtydxb/Fastllm-proxy, 108 stars) and LLM Gateway (sickn33/agentic-awesome-skills, 47k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ag2 Middleware?

ag2ai (a GitHub organization) maintains it in ag2ai/build-with-ag2, which has 252 GitHub stars. The repository holds 16 skills in this directory. The repository was last updated on September 6, 2026.

Source: ag2ai/build-with-ag2 on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.