Agent Tool Forge

Compile safer agent-service scaffolds from idea to reviewable package.

Agent Tool Forge is a safety-first compiler for A2MCP agent-service packages. Give it an OpenAPI 3.x document or a service idea and it returns a downloadable package containing structured contracts, a non-executing handler scaffold, security controls, provenance, and conformance-test specifications.

Status: the public endpoint is live and free. OKX.AI Agent #5820 is under review; this is not a claim of listing approval. x402 is an opt-in deployment adapter and has not collected payment on the current free endpoint.

30-second Judge Path

1. Open the live Judge Console.
2. Run the Weather API path: verify allow, imported-operation evidence, and a downloadable ZIP.
3. Compare the safety paths: Token Risk returns allow_with_review; Prompt Injection returns block and withholds the artifact.
4. Verify the API directly: /health, /openapi.json, and POST /forge remain available for agents and automation.
5. Verify locally: python3 -m unittest discover -v — the current suite contains 33 tests. Latest published CI run: #29648761573.

Agent Tool Forge's validation, redaction, prompt-injection block, review findings, artifact lifecycle, HTTP controls, and optional billing adapter are implemented product logic. The generated target handler.py is deliberately a non-executing scaffold, not finished business logic; imported write operations remain contract metadata and are never executed by the scaffold. Users must connect verified data sources, implement and authorize domain behavior, review it, and test it before production.

Architecture

See the reproducible golden examples for real, sanitized public-endpoint captures. No generated ZIPs are committed with those examples.

Live API

• Judge Console: https://hermes-agent.tail3ab78.ts.net/
• Forge endpoint: https://hermes-agent.tail3ab78.ts.net/forge
• Health: https://hermes-agent.tail3ab78.ts.net/health
• Readiness: https://hermes-agent.tail3ab78.ts.net/ready
• OpenAPI: https://hermes-agent.tail3ab78.ts.net/openapi.json

The public endpoint is free and does not require an LLM provider or expose model-provider credentials.

Features

• POST /forge — compile a service idea or OpenAPI document.
• GET or HEAD /forge — fast, free service discovery for marketplace availability probes.
• GET /openapi.json — retrieve the OpenAPI 3.1 contract.
• GET /artifacts/{package_id}.zip — download a generated package.
• GET /health — retrieve service health and version information.
• GET /ready — check artifact-storage readiness.
• Local CLI for offline generation.
• OpenAPI 3.x import and operation extraction.
• Structured safety findings and generation decisions.
• Ephemeral artifact storage with opaque identifiers and bounded retention.

Each generated ZIP contains:

manifest.json
openapi.json
handler.py
schemas/input.schema.json
schemas/output.schema.json
tests/conformance.json
SECURITY.md
README.md
forge-report.json

Safety model

Safety controls are enforced in the request-processing path:

• All user-controlled fields are inspected, including service descriptions, sample inputs, dependencies, jurisdiction notes, and imported OpenAPI documents.
• Secret-like API keys, bearer tokens, URL credentials, passwords, and private-key blocks are redacted before generation.
• Prompt-injection patterns produce decision=block; blocked requests do not produce a downloadable ZIP or publication assets.
• Wallet/signature, transaction, financial, PII, and security-sensitive capabilities produce allow_with_review findings; unlike prompt injection, they do not automatically block scaffold generation.
• Raw request content and raw secrets are not written to audit records or request logs.
• The HTTP service enforces JSON content type, a 128 KiB body limit, schema validation, rate limits, concurrency limits, hardened response headers, and generic internal-error responses.
• Artifacts use opaque 128-bit identifiers, bounded disk-backed TTL storage, atomic writes, and cross-process locks.
• Every response includes an X-Request-ID; application logs contain request metadata but omit bodies and query strings.

Runtime and scaffold boundaries:

• No collection of private keys, seed phrases, passwords, or credentials.
• The Forge and generated scaffold do not sign wallets or execute imported operations or transactions.
• The Forge performs no swaps, bridges, transfers, staking, lending, betting, or gas spending.
• No bypass of KYC, AML, sanctions, or geographic controls.
• Security-sensitive or potentially harmful requests are surfaced for human review; the generated scaffold contains no connected execution logic.

See SECURITY.md for vulnerability reporting and runtime boundaries.

Requirements

• Python 3.10 or newer
• Gunicorn for production serving
• Docker is optional

The compiler core uses the Python standard library. Gunicorn is provided through the production optional dependency.

Paid deployments additionally install the official x402 Python SDK through the payments extra. Free mode neither imports the SDK nor contacts a facilitator.

Local development

Run the development server:

python3 -m agent_tool_forge.server

The server listens on 127.0.0.1:8787 by default.

Submit a request:

curl -s http://127.0.0.1:8787/forge \
  -H 'content-type: application/json' \
  -d '{
    "service_idea": "Create a read-only weather lookup utility for AI agents.",
    "preferred_type": "A2MCP"
  }'

Marketplace and uptime probes can call the same endpoint without a body:

curl -i https://hermes-agent.tail3ab78.ts.net/forge
curl -i -X POST https://hermes-agent.tail3ab78.ts.net/forge

Both return HTTP 200 immediately with the free A2MCP invocation contract. A real compilation request remains a JSON POST with service_idea.

Agent Tool Forge is currently registered as a free A2MCP endpoint (fee=0), so production requests return HTTP 200 directly. The server also includes an opt-in x402 v2 payment adapter for a later paid launch; paid mode is disabled until an explicit network, asset, price, recipient, and facilitator are configured.

CLI

python3 -m agent_tool_forge.cli \
  --idea "Convert a public weather API into a read-only agent service." \
  --output outputs/weather-tool-package.json

Use --file to read a service idea from a UTF-8 text file.

OpenAPI import

{
  "service_idea": "Convert this weather API into a read-only A2MCP service.",
  "openapi_document": {
    "openapi": "3.1.0",
    "info": {
      "title": "Weather API",
      "version": "1.0.0"
    },
    "paths": {
      "/weather": {
        "get": {
          "operationId": "getWeather",
          "summary": "Get current weather"
        }
      }
    }
  }
}

The response includes imported operations, generated schemas, safety findings, provenance, a content digest, and an opaque download URL.

Production deployment

Install the production dependency:

python3 -m pip install '.[production]'

Run Gunicorn:

gunicorn \
  --bind 127.0.0.1:8787 \
  --workers 2 \
  --threads 4 \
  --timeout 30 \
  agent_tool_forge.wsgi:application

Or use Docker:

docker build -t agent-tool-forge:1.0.0 .
docker run \
  --read-only \
  --tmpfs /tmp \
  --mount type=volume,src=atf-artifacts,dst=/var/lib/agent-tool-forge/artifacts \
  -p 8787:8787 \
  agent-tool-forge:1.0.0

The container runs as a non-root user and includes a readiness health check.

Runtime configuration

• ATF_BIND — Gunicorn bind address used by the container.
• ATF_ARTIFACT_DIR — artifact-storage directory.
• ATF_ARTIFACT_TTL_SECONDS — artifact retention period; default 3600.
• ATF_MAX_ARTIFACTS — maximum retained artifacts; default 500.
• ATF_MAX_ARTIFACT_BYTES — total artifact-storage limit.
• ATF_MAX_SINGLE_ARTIFACT_BYTES — per-artifact size limit.
• ATF_MAX_BODY_BYTES — maximum HTTP request-body size; default 128 KiB.
• ATF_MAX_CONCURRENT — in-process request concurrency limit.
• ATF_RATE_LIMIT_REQUESTS — requests allowed per rate-limit window.
• ATF_RATE_LIMIT_WINDOW_SECONDS — rate-limit window duration.
• ATF_TRUST_PROXY — trust the first X-Forwarded-For value when set to 1.
• ATF_PUBLIC_BASE_URL — public base URL used in API responses and OpenAPI metadata.
• ATF_BILLING_MODE — free (default) or x402; paid mode fails closed when incomplete.
• ATF_X402_PAY_TO — paid-mode recipient address.
• ATF_X402_NETWORK — paid-mode CAIP-2 network, currently an EVM network such as eip155:<chain-id>.
• ATF_X402_ASSET — paid-mode token contract address.
• ATF_X402_AMOUNT — positive token amount in atomic units; never a floating-point amount.
• ATF_X402_FACILITATOR_URL — HTTP(S) facilitator URL.
• ATF_X402_SCHEME — currently exact.
• ATF_X402_MAX_TIMEOUT_SECONDS — payment timeout, default 300.
• ATF_X402_ASSET_EXTRA_JSON — optional SDK asset metadata JSON.

Only enable ATF_TRUST_PROXY=1 behind a trusted proxy that overwrites forwarded headers.

Future paid mode (x402 v2)

Install the payment integration with python3 -m pip install '.[production,payments]', set every ATF_X402_* value above, then set ATF_BILLING_MODE=x402. No recipient, network, token, amount, or facilitator is hard-coded, and incomplete paid configuration stops startup rather than silently serving the protected operation for free.

Only a bodyful POST /forge is protected. GET/HEAD /forge, empty marketplace probes, health, readiness, OpenAPI, and artifact downloads remain free. The adapter uses the standard PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE headers, verifies and settles through the official SDK/facilitator, and withholds the business response if settlement fails. A reverse proxy must preserve HTTP 402 and these headers and must not cache payment responses.

Testing

Run the unit, security, and HTTP integration tests:

python3 -m unittest discover -v

Build a wheel:

python3 -m pip wheel . --no-deps -w dist

The latest test suite contains 31 tests. CI tests Python 3.10 and 3.12, runs static and dependency security scans, builds the production container, and probes its readiness endpoint. The latest CI workflow execution is run #29643626018; the badge above reflects the current default-branch workflow status.

Repository layout

agent_tool_forge/
  api_schema.py    # OpenAPI contract
  artifacts.py     # bounded cross-process ZIP artifact store
  billing.py       # free mode and optional fail-closed x402 adapter
  cli.py           # local CLI
  generator.py     # compiler, importer, and safety engine
  models.py        # validated request and response models
  server.py        # local development server
  wsgi.py          # production WSGI application
tests/
  test_billing.py  # free/x402 configuration and middleware tests
  test_forge.py    # unit, security, and HTTP integration tests
examples/
  README.md         # replay instructions and evidence scope
  weather/          # OpenAPI import allow path
  token-risk/       # security-sensitive review path
  prompt-injection/ # blocked safety path
docs/
  architecture.svg  # runtime and generated-artifact architecture

License

MIT