Multi Step JSON With Skills#

Source: examples/agents/multi_step_json_with_skills.py

Introduction#

This example shows a tool-capable multi-step agent with Agent Skills enabled. Discovered project-local skills can be activated on demand with skills.activate before the agent selects one of the regular tools.

Technical Implementation#

  1. Build a SkillsConfig rooted at the current project so the agent can discover local .agents/skills definitions.

  2. Construct MultiStepAgent in JSON mode with the public Toolbox facade.

  3. Allow the model to activate a discovered skill before making a regular tool call and explicit final answer.

  4. Print the normalized summary payload for inspection.

        1. Build a ``SkillsConfig`` rooted at the current project so the agent can
   discover local ``.agents/skills`` definitions.
2. Construct ``MultiStepAgent`` in JSON mode with the public ``Toolbox`` facade.
3. Allow the model to activate a discovered skill before making a regular tool
   call and explicit final answer.
4. Print the normalized summary payload for inspection.
    
 1from __future__ import annotations
 2
 3import json
 4from pathlib import Path
 5
 6import design_research_agents as drag
 7
 8
 9def _ensure_example_skill(project_root: Path) -> None:
10    skill_dir = project_root / ".agents" / "skills" / "word_count_helper"
11    skill_dir.mkdir(parents=True, exist_ok=True)
12    skill_dir.joinpath("SKILL.md").write_text(
13        "\n".join(
14            [
15                "---",
16                "name: word_count_helper",
17                "description: Use text.word_count before finalizing numeric answers.",
18                "allowed-tools:",
19                "  - text.word_count",
20                "---",
21                "Activate this skill before calling text.word_count on short phrases.",
22                "",
23            ]
24        ),
25        encoding="utf-8",
26    )
27
28
29def main() -> None:
30    """Run one JSON tool-calling agent with skills discovery enabled."""
31    request_id = "example-multi-step-json-skills-001"
32    project_root = Path("artifacts/examples/multi_step_json_with_skills_project")
33    _ensure_example_skill(project_root)
34    skills = drag.SkillsConfig(project_root=project_root)
35
36    with drag.Toolbox() as tool_runtime, drag.LlamaCppServerLLMClient() as llm_client:
37        agent = drag.MultiStepAgent(
38            mode="json",
39            llm_client=llm_client,
40            tool_runtime=tool_runtime,
41            max_steps=4,
42            allowed_tools=("text.word_count",),
43            skills=skills,
44        )
45        result = agent.run(
46            prompt=(
47                "Activate a relevant skill if one is available, then use text.word_count to count "
48                "the words in 'design research agents'. Return only the word_count."
49            ),
50            request_id=request_id,
51        )
52
53    print(json.dumps(result.summary(), ensure_ascii=True, indent=2, sort_keys=True))
54
55
56if __name__ == "__main__":
57    main()

Expected Results#

Run Command

PYTHONPATH=src python3 examples/agents/multi_step_json_with_skills.py

Example output shape (values vary by run):

{
  "success": true,
  "final_output": "<example-specific payload>",
  "terminated_reason": "<string-or-null>",
  "error": null
}

References#