Skip to content
BranchesTags

Repository files navigation

Tool-Using Agent Builder

License: MIT Validate skill GitHub release

Agent Skill đa nền tảng chuyên xây dựng, nâng cấp và production-hardening Tool-Using Agent theo quy trình end-to-end có kiểm soát. Một core duy nhất phục vụ Codex, Claude Code và Antigravity; adapter chỉ ánh xạ capability của host, không nhân bản workflow, security rules hoặc quality gates.

Phiên bản hiện tại: v1.1.0

Mục Tiêu

  • Xây agent dùng API, DB, MCP server, browser, filesystem, CLI hoặc công cụ nội bộ.
  • Tách reasoning của model khỏi deterministic runtime thực thi.
  • Kiểm soát quyền, side effect, approval, retry, timeout, idempotency và audit.
  • Thiết kế theo delivery mode, risk tier và quality gate cụ thể.
  • Kiểm thử contract, integration, security, recovery và hành vi agent.
  • Chỉ tuyên bố readiness khi có bằng chứng kiểm chứng được.

Hỗ Trợ Nền Tảng

Host Discovery path cá nhân Discovery path dự án Invocation
Codex ~/.codex/skills/tool-using-agent-builder <project>/.codex/skills/tool-using-agent-builder $tool-using-agent-builder
Claude Code ~/.claude/skills/tool-using-agent-builder <project>/.claude/skills/tool-using-agent-builder /tool-using-agent-builder hoặc auto-discovery
Antigravity ~/.gemini/antigravity/skills/tool-using-agent-builder <project>/.agents/skills/tool-using-agent-builder Auto-discovery hoặc yêu cầu theo tên

SKILL.md, references, scripts và quality rules là core dùng chung. agents/openai.yaml chỉ là metadata UI của Codex; Claude Code và Antigravity bỏ qua file này.

Kiến Trúc Multi-Platform

flowchart TD
    H["Codex / Claude Code / Antigravity"] --> C["Core SKILL.md"]
    C --> R["Platform Adapter Contract"]
    R --> D{"Detect active host"}
    D --> A1["adapters/codex.md"]
    D --> A2["adapters/claude-code.md"]
    D --> A3["adapters/antigravity.md"]
    A1 --> L["Shared Phase 0-8 lifecycle"]
    A2 --> L
    A3 --> L
    L --> Q["Shared security + quality gates + evidence"]
Loading

Core sử dụng các semantic capability:

  • plan: quản lý milestone và kế hoạch phụ thuộc.
  • ask: chỉ hỏi input chặn tiến độ.
  • approve: xác nhận chính xác side effect và payload.
  • delegate: giao bounded sidecar work khi được phép.
  • scan_security: dùng workflow security của host hoặc local fallback.
  • execute_tool: gọi tool với least privilege, validation và budget.
  • verify: chạy fresh executable evidence trước completion claim.

Contract: skills/tool-using-agent-builder/references/platform-adapter-contract.md.

Adapter:

Adapter không được thay đổi delivery mode, readiness state, security invariant hoặc evidence threshold. Capability thiếu phải dùng fallback an toàn hoặc báo blocker/proof gap; không được tự giảm kiểm soát.

Kiến Trúc Tool-Using Agent

flowchart LR
    U["Người dùng / Hệ thống gọi"] --> I["Input normalization"]
    I --> O["Agent orchestrator"]
    O --> M["Model / Planner"]
    M --> V["Proposal validator"]
    V --> P["Policy engine"]
    P --> A["Approval manager"]
    A --> G["Tool gateway"]
    G --> T["API / DB / MCP / Browser / CLI"]
    T --> R["Result normalization"]
    R --> S["Durable state + audit log"]
    S --> O
    O --> X["Final response / handoff"]
Loading

Nguyên tắc lõi:

  • Model tạo đề xuất, không sở hữu quyền thực thi.
  • Runtime xác thực schema, authorization, policy, budget và trạng thái.
  • Tool gateway là ranh giới duy nhất cho side effect.
  • Mọi thao tác ghi có precondition, idempotency key và audit trail.
  • Tool output, web, file và user input đều là untrusted input.
  • Hệ thống fail closed khi policy, approval hoặc trạng thái không đủ chắc chắn.

Chi tiết: skills/tool-using-agent-builder/references/architecture-blueprint.md.

Security Và Side Effects

Hạng mục Yêu cầu
Contract Input/output schema, semantic invariant, error taxonomy, version
Authorization Least privilege, scope nhỏ, deny by default
Side effect Phân loại read/write/destructive/financial/external communication
Approval Actor, target, amount, recipient, expiry và payload digest
Idempotency Stable key, replay safety, deduplication và commit record
Concurrency Version check, optimistic locking hoặc serialization
Recovery Timeout, retry, compensation, reconciliation và dead-letter path
Secrets Không đưa secret vào prompt, log, trace hoặc report
Audit Actor, decision, policy/tool version, resource và result

Side effect quan trọng dùng prepare → authorize → approve → commit → verify. Trước commit, runtime kiểm tra lại quyền, resource version, policy, target, amount, recipient, expiry và approval digest để chặn TOCTOU hoặc payload mutation.

Checklist: skills/tool-using-agent-builder/references/security-checklist.md.

Quy Trình End-to-End

Phase Kết quả bắt buộc
0. Initialize Host adapter, delivery mode và machine-readable evidence state
1. Discovery Repo, runtime, tool surface, trust boundary, dependency và unknowns
2. Architecture Components, state, tool gateway, policy, approval và observability
3. Threat Model Injection, poisoning, exfiltration, replay, race và kill switch
4. Plan Milestone, file-level steps, acceptance criteria và validation strategy
5. Build Contract, adapter, policy, orchestrator, state, audit và reporting
6. Verify Unit, contract, integration, security, recovery và regression checks
7. Behavioral Evidence Representative tasks, hidden holdout và critical failure review
8. Deliver Readiness, limitations, evidence index, runbook và handoff

Mỗi thời điểm chỉ có một milestone hoạt động. Mở rộng phạm vi đáng kể cần milestone mới và user approval.

Delivery Modes

  • targeted-change: thay đổi hẹp trong agent hiện có.
  • prototype: chứng minh luồng chính; chưa production-ready.
  • production-candidate: đủ control và evidence để đánh giá triển khai.
  • production-hardening: tăng an toàn, reliability và operability.
  • architecture-only: kiến trúc và kế hoạch; không tạo runtime evidence giả.

Chi tiết: skills/tool-using-agent-builder/references/delivery-modes.md.

Quality Gates

  1. Scope gate: mục tiêu, non-goal, owner và acceptance criteria rõ.
  2. Architecture gate: trust boundary, state ownership và failure modes đầy đủ.
  3. Tool contract gate: schema, permission, side effect, timeout, retry, idempotency.
  4. Security gate: least privilege, approval integrity, injection defense, secret handling.
  5. Verification gate: targeted test và regression pass; lỗi ngoài phạm vi tách rõ.
  6. Behavioral gate: representative tasks, hidden holdout, adversarial cases, zero critical failure.
  7. Operability gate: logs, metrics, traces, alerts, reconciliation và runbook.
  8. Delivery gate: readiness claim khớp evidence; limitation và proof gap công khai.

Định nghĩa: skills/tool-using-agent-builder/references/quality-gates.md.

Cài Đặt Đa Nền Tảng

Clone repository:

git clone https://github.com/buithanhninh/tool-using-agent-builder.git
Set-Location .\tool-using-agent-builder

Codex

python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
  --host codex --scope user

Claude Code

python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
  --host claude-code --scope user

Antigravity

python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
  --host antigravity --scope user

Cài theo project:

python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
  --host claude-code `
  --scope project `
  --project-root C:\path\to\project

Xem trước không ghi filesystem:

python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
  --host antigravity --scope user --dry-run

Nâng cấp destination đã tồn tại:

python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
  --host codex --scope user --force

Installer copy transactional, bỏ .git, __pycache__, .pytest_cache, .pyc và dừng khi destination tồn tại nếu không có --force.

Cách Sử Dụng

$tool-using-agent-builder

Hãy xây một agent xử lý hoàn tiền qua API và PostgreSQL.
Yêu cầu:
- Chỉ hoàn tiền cho giao dịch hợp lệ.
- Trên 5 triệu đồng phải xin approval.
- Mọi thao tác ghi phải idempotent và audit được.
- Có timeout, retry, reconciliation và dashboard metric.
- Thực hiện thiết kế, kế hoạch, code, test nhiều vòng và báo cáo readiness.

Trên Claude Code, thay dòng đầu bằng:

/tool-using-agent-builder

Trên Antigravity, yêu cầu dùng skill theo tên hoặc để host tự discovery từ description.

Validation

python -m unittest discover `
  -s .\skills\tool-using-agent-builder\scripts\tests `
  -v

python .\skills\tool-using-agent-builder\scripts\validate_skill_package.py `
  .\skills\tool-using-agent-builder

Dry-run sáu destination:

$hosts = 'codex','claude-code','antigravity'
foreach ($hostName in $hosts) {
  python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
    --host $hostName --scope user --dry-run
  python .\skills\tool-using-agent-builder\scripts\install_multi_platform.py `
    --host $hostName --scope project --project-root . --dry-run
}

Bằng Chứng Chất Lượng

v1.1.0 có:

  • 16 unit tests cho core, adapters, installer, validators và evidence rules.
  • Package validator kiểm tra đủ ba adapter, contract, anti-duplication và process mapping.
  • Installer tests cho sáu discovery paths, dry-run, conflict và cache exclusion.
  • GitHub Actions chạy tests và package validator trên mỗi push/PR.

Behavioral campaign 40 runs của v1.0.0 vẫn là bằng chứng lịch sử cho lifecycle core: skilled mean 0.9349, hidden holdout 0.9534, 20/20 skilled pass và 0 critical failure. v1.1.0 chưa tuyên bố có behavioral execution native trên cả ba host; đó là proof gap được giữ công khai thay vì suy diễn từ structural tests.

Protocol: skills/tool-using-agent-builder/references/behavioral-eval-protocol.md.

Cấu Trúc Repository

.
├── README.md
├── LICENSE
├── CHANGELOG.md
├── SECURITY.md
├── .github/workflows/validate.yml
└── skills/tool-using-agent-builder/
    ├── SKILL.md
    ├── agents/openai.yaml
    ├── adapters/
    │   ├── codex.md
    │   ├── claude-code.md
    │   └── antigravity.md
    ├── references/
    └── scripts/
        ├── install_multi_platform.py
        ├── init_agent_build.py
        ├── validate_agent_build.py
        ├── validate_behavioral_results.py
        ├── validate_skill_package.py
        └── tests/

Báo Cáo Và Operability

Báo cáo cuối phải nêu release identity, host adapter, tool inventory, trust boundary, side-effect controls, test matrix, behavioral metrics, proof gaps, readiness, dashboard, alert, rollback, reconciliation và ownership.

Template: skills/tool-using-agent-builder/references/delivery-report-template.md.

Giới Hạn

  • Skill không thay security review độc lập cho hệ thống rủi ro cao.
  • Không tuyên bố production-ready khi thiếu integration test, behavioral holdout hoặc operability evidence.
  • Native trace và approval phụ thuộc capability của host. Khi host thiếu, báo proof gap hoặc blocker.
  • Tác vụ financial, destructive, external communication hoặc dữ liệu nhạy cảm cần policy và approval của môi trường thực.

Đóng Góp

Mở issue hoặc pull request kèm mục tiêu, risk, platform impact và test evidence. Thay đổi core contract, security boundary hoặc readiness rule cần regression test tương ứng.

Lỗ hổng bảo mật: xem SECURITY.md.

Giấy Phép

Phát hành theo giấy phép MIT. Copyright © 2026 Bùi Thành Ninh.

About

Skill Codex xây dựng Tool-Using Agent end-to-end: kiến trúc, security, quality gates, kiểm thử behavioral và operability.

Topics

agent-skillsagentic-aiai-agentantigravityclaude-codecodexmcpsecuritytool-use

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages