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 Structured Output

by ag2ai in ag2ai/build-with-ag2

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

Apache-2.0Auto-check passedAI & LLM Engineering

Install Ag2 Structured Output

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

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

GitHub CLI
$ gh skill install ag2ai/build-with-ag2 ag2-structured-output --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-structured-output .claude/skills/ag2-structured-output && 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-structured-output
GitHub stars
252
Token cost
~1.8k tokens
SKILL.md length
459 words
Files
2 (incl. assets)
Skills in repo
16
Repo updated
First seen
Licence
Apache-2.0

At a glance

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

  • The user wants validated structured output
  • SKILL.md covers When to use, 60-second recipe, Schema types you can pass and ResponseSchema — name your…, plus 7 more sections
  • Runs Python scripts from its folder
  • Tasks that involve Structured output and tool calling

What it does

Ag2 Structured Output is an agent skill from ag2ai/build-with-ag2. Get a typed Python value back from an AG2 beta Agent instead of free text. Pass responseschema= (a Pydantic model, dataclass, primitive, union, ResponseSchema, or @responseschema validator) and read the parsed result via await reply.content(). Use when the user wants validated structured output, classification, extraction, or scoring. Covers ResponseSchema, @responseschema, PromptedSchema (for providers without native structured output), per-turn override, validation retries, and primitive embedding.

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including assets (for example `assets/recipe_builder.py`).

It sits in AI & LLM Engineering, covering Structured output and tool calling and Embeddings. It works with Pydantic and Python. 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

  • The user wants validated structured output
  • Tasks that involve Structured output and tool calling
  • Tasks that involve Embeddings

Example prompts

  • “/ag2-structured-output”

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

    Ships script files (Python), which the agent can run.

    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 Structured Output loads about 1.8k tokens when it runs. Until then it costs about 137 tokens; SKILL.md has 459 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~137
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k

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). 459 words, ~1,758 tokens.

Download SKILL.mdSave it as .claude/skills/ag2-structured-output/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
ag2-structured-output
description
Get a typed Python value back from an AG2 beta `Agent` instead of free text. Pass `response_schema=` (a Pydantic model, dataclass, primitive, union, `ResponseSchema`, or `@response_schema` validator) and read the parsed result via `await reply.content()`. Use when the user wants validated structured output, classification, extraction, or scoring. Covers `ResponseSchema`, `@response_schema`, `PromptedSchema` (for providers without native structured output), per-turn override, validation retries, and primitive embedding.
license
Apache-2.0

Structured output

When to use

  • The user wants a Pydantic model, dataclass, dict, primitive, or union back — not a string.
  • They're doing classification, extraction, scoring, normalisation, or anything where downstream code parses the reply.
  • They want automatic retry on validation failure.

60-second recipe

python
from pydantic import BaseModel, Field
from typing import Annotated

from autogen.beta import Agent
from autogen.beta.config import OpenAIConfig

class TicketTriage(BaseModel):
    category: Annotated[str, Field(description="e.g. billing, bug, account_access")]
    urgency: Annotated[str, Field(description="low, medium, or high")]
    summary_one_line: Annotated[str, Field(description="Max 120 characters", max_length=120)]

agent = Agent(
    "triage",
    prompt="You triage support messages. Be conservative with urgency.",
    config=OpenAIConfig(model="gpt-4o-mini"),
    response_schema=TicketTriage,
)

reply = await agent.ask("I was charged twice and can't export reports. Quarter close blocked.")
triage = await reply.content()      # → typed TicketTriage
print(triage.category, triage.urgency)

reply.body is still the raw model text; await reply.content() runs validation and returns the parsed value. If validation fails, content() raises (e.g. pydantic.ValidationError).

Schema types you can pass

TypeWhat you get
Primitive (int, float, bool)Bare value, framework wraps in {"data": ...} for the API
dataclassInstance of the dataclass
Pydantic BaseModelInstance of the model
Union (int | str, (int, str))One of the alternatives
dict[K, V], TypedDictValidated dict
ResponseSchema(...)Same as above, with explicit name / description for the provider
@response_schema callableCustom validation/parsing logic
PromptedSchema(inner)Schema injected into the system prompt for providers without native structured output

ResponseSchema — name your payload

Helps the provider treat the structured output as a named contract:

python
from autogen.beta import Agent, ResponseSchema

schema = ResponseSchema(int | str, name="ByteWidth", description="Number of bits in one byte.")
agent = Agent("assistant", config=config, response_schema=schema)

@response_schema — custom validation

For clamping, regex cleanup, decoding wrapped JSON, or combining fields:

python
from autogen.beta import Agent, response_schema

@response_schema
def parse_rating(content: str) -> int:
    """Parse a rating and clamp to 1–5."""
    return max(1, min(5, int(content)))

agent = Agent("assistant", config=config, response_schema=parse_rating)

Multi-parameter form synthesises a JSON object schema from the parameter names:

python
from typing import Annotated
from pydantic import Field
from autogen.beta import response_schema

@response_schema
def extract_listing(
    title: Annotated[str, Field(description="Product name")],
    price_usd: Annotated[float, Field(description="Price in USD", ge=0)],
    in_stock: Annotated[bool, Field(description="True if it ships now")],
) -> dict:
    return {"title": title, "price_usd": price_usd, "in_stock": in_stock}

The function also participates in dependency injection — Context, Variable, Inject, Depends work the same way as in tools (and don't appear in the JSON schema).

Async validators are supported:

python
import json

@response_schema
async def fetch_and_validate(content: str) -> dict:
    data = json.loads(content)
    data["validated"] = True
    return data

PromptedSchema — for providers without native structured output

Injects the JSON schema into the system prompt instead of using response_format:

python
from autogen.beta import Agent, PromptedSchema

agent = Agent("assistant", config=config, response_schema=PromptedSchema(int))

Wraps any inner schema (type, ResponseSchema, @response_schema callable). The validation logic stays the same; only the wire format changes.

Custom prompt template:

python
PromptedSchema(int, prompt_template="Reply with JSON matching this schema:\n{schema}")

Per-turn override

python
agent = Agent("assistant", config=config)

turn = await agent.ask("How many seconds in a minute?", response_schema=int)
print(await turn.content())   # 60

turn2 = await turn.ask("Say hello.")     # back to default (no schema)

Pass response_schema=None to drop a schema set on the agent for one call.

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

Retries

When validation fails, automatically re-ask the model:

python
result = await reply.content(retries=3)   # initial + up to 3 re-asks
result = await reply.content(retries=math.inf)   # interactive only — could loop forever

The validation error is sent back to the model as a follow-up so it can correct itself.

Primitive embedding (embed)

Bare primitives (int, float, bool, list[T], primitive unions) get wrapped in {"data": ...} by default — most structured-output APIs handle objects more reliably than bare values. content() transparently unwraps. Opt out:

python
ResponseSchema(int, name="RawInt", embed=False)              # model must produce a bare 42
@response_schema(embed=False)
def parse_rating(value: int) -> int: ...

Going deeper

  • Working starter: assets/recipe_builder.py (mirrors code_examples/02) — Pydantic model + @tool + response_schema=.
  • Full reference: website/docs/beta/structured_output.mdx — covers every schema type, multi-param @response_schema, Field constraints, PromptedSchema, retries, embedding semantics.

Common pitfalls

  • Reading reply.body when you wanted typed output — reply.body is the raw text. await reply.content() does the parsing.
  • Forgetting await on content() — it's async; you'll get a coroutine, not the value.
  • No description in the Pydantic field — the LLM may guess what to put in each field. Add a Field(description=...) for every non-obvious key.
  • Provider doesn't support native structured output — wrap with PromptedSchema(...) rather than fighting the API.
  • retries=math.inf in production — will loop forever on a model that can't comply. Use a finite count.
  • Per-turn override is single-turn — passing response_schema=int to one ask() doesn't change the agent's default. The next turn returns to whatever was set on the constructor.

© 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 (assets) in .agents/skills/ag2-structured-output of ag2ai/build-with-ag2.

  • SKILL.md
  • assets/recipe_builder.py

Open the folder on GitHubat commit 29eeac3

Compare with similar skills

Ag2 Structured Output 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 Structured Output compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ag2 Structured Output this skillag2ai/build-with-ag2252—~1.8kAutomated safety check: PassApache-2.0
Building Pydantic AI Agentsdocling-project/docling69k—~2.8kAutomated safety check: PassMIT
Prompt Engineering Patternswshobson/agents40k—~1.3kAutomated safety check: PassMIT
Outlines Structured GenerationOrchestra-Research/AI-Research-SKILLs13k9 repos~4kAutomated safety check: PassMIT
Building Pydantic AI Agentspydantic/skills140—~5.4kAutomated safety check: PassMIT
Pydantic AIdavila7/claude-code-templates33k3 repos~2.9kAutomated safety check: PassMIT

Similar skills

  • Building Pydantic AI Agents

    docling-project/docling

    Patterns and tested examples for building agents with Pydantic AI: tools, capabilities, structured output, dependency injection, hooks, YAML specs, streaming and testing.

    69k GitHub stars~2.8k tokensUpdated today
    AI & LLM EngineeringAuto-check passed

  • Prompt Engineering Patterns

    wshobson/agents

    Reference for designing and tuning production LLM prompts: few-shot examples, chain-of-thought, structured outputs, templates and system prompts.

    40k GitHub stars~1.3k tokensUpdated 5 days ago
    AI & LLM EngineeringAuto-check passed

  • Outlines Structured Generation

    Orchestra-Research/AI-Research-SKILLs

    Uses the Outlines library to constrain model output to a JSON schema, Pydantic model, regex or fixed set of choices when running local models.

    13k GitHub starsUsed in 9 repos~4k tokens
    AI & LLM EngineeringAuto-check passed

  • Building Pydantic AI Agents

    pydantic/skills

    Official

    Build AI agents with Pydantic AI — tools, capabilities (including on-demand loading), structured output, streaming, testing, and multi-agent patterns.

    140 GitHub stars~5.4k tokensUpdated 9 days ago
    AI & LLM EngineeringAuto-check passed

  • Pydantic AI

    davila7/claude-code-templates

    Build production-ready AI agents with PydanticAI — type-safe tool use, structured outputs, dependency injection, and multi-model support.

    33k GitHub starsUsed in 3 repos~2.9k tokens
    AI & LLM EngineeringAuto-check passed

  • Langchain Middleware

    langchain-ai/langchain-skills

    Official

    INVOKE THIS SKILL when you need human-in-the-loop approval, custom middleware, or structured output.

    1.3k GitHub stars~2.7k tokensUpdated yesterday
    AI & LLM EngineeringAuto-check passed

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 Middleware

    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).

    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

Works with

Categories

Questions about Ag2 Structured Output

What does Ag2 Structured Output do?

Get a typed Python value back from an AG2 beta Agent instead of free text. Ag2 Structured Output is an agent skill from ag2ai/build-with-ag2. Get a typed Python value back from an AG2 beta Agent instead of free text.

When should I use Ag2 Structured Output?

Ag2 Structured Output fits situations like: the user wants validated structured output; tasks that involve Structured output and tool calling; tasks that involve Embeddings.

How do I install Ag2 Structured Output in Claude Code?

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

How do I install Ag2 Structured Output in Codex?

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

Can I use Ag2 Structured Output 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-structured-output -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-structured-output, .gemini/skills/ag2-structured-output, .github/skills/ag2-structured-output and .opencode/skills/ag2-structured-output in your project.

What does Ag2 Structured Output need to run?

Going by SKILL.md and its folder, Ag2 Structured Output needs Python for the scripts in its folder. Our summary lists: Python 3.

Does Ag2 Structured Output 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 Structured Output 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 Structured Output use?

Ag2 Structured Output 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 Structured Output use?

About 1.8k tokens (SKILL.md is roughly 7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ag2 Structured Output?

Skills that share tags, products or a category with Ag2 Structured Output: Building Pydantic AI Agents (docling-project/docling, 69k stars), Prompt Engineering Patterns (wshobson/agents, 40k stars), Outlines Structured Generation (Orchestra-Research/AI-Research-SKILLs, 13k stars) and Building Pydantic AI Agents (pydantic/skills, 140 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ag2 Structured Output?

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.