Tiếp theoHướng dẫn tiếp theo
Công cụ thiết kế dành cho đại lý LLM
kỹ thuật
HƯỚNG DẪN KỸ THUẬT
OpenAPI documents describe HTTP operations, parameters, request bodies, responses, and security schemes in a machine-readable format.
Nghe hướng dẫn nàyAI thuật lại · ~3 min
Turning selected operations into LLM tools requires curating a safe surface, translating schemas, and keeping authorization and execution in application code.
OpenAPI (formerly Swagger) is a machine-readable format that describes a REST API's endpoints, parameters, request bodies and responses using version-specific Schema Objects for data shapes; OpenAPI 3.1 and later align these with JSON Schema, while earlier versions differ. Since most LLM tool-calling systems, including MCP and native function-calling APIs, already expect JSON-Schema-shaped parameter definitions, the endpoint and parameter portion of an OpenAPI document maps fairly directly onto a tool definition: the path and method become the tool's identity, the parameters and request body become its input schema, and the summary or description fields become the tool's description. Several open-source converters (such as openapi-to-mcp style generators, or lightweight scripts built on libraries like openapi-schema-validator) automate this mechanical mapping. The harder, non-mechanical part is curation: production OpenAPI specs frequently describe hundreds of endpoints, many overlapping or rarely used, and their descriptions are written for engineers integrating code, not for a model deciding whether to call something. Practitioners typically prune the spec down to the handful of endpoints a given use case needs, rewrite ambiguous parameter descriptions in plain language, add example values, and flag irreversible or sensitive actions explicitly, since OpenAPI has no native concept of 'this deletes data permanently.' A common misconception is that feeding an entire large OpenAPI file to a model as tools works out of the box; in practice, tool count and description clarity both strongly affect whether the model picks the right tool and fills in arguments correctly.
A logistics company runs its shipping API's OpenAPI file through a converter to generate a get_shipment_status tool, then manually rewrites the auto-generated description because the original was written for engineers, not for a model deciding when to call it.
A support team exposes only 6 of their 140 documented endpoints as tools, since including the full spec would overwhelm the model's context and increase the chance it picks the wrong endpoint.
A fintech startup generates a create_payment tool from its OpenAPI spec but adds a manual confirmation step in the tool description, since the spec alone does not convey that this action is irreversible.
A developer converting a weather API notices the OpenAPI spec marks a units parameter as optional with no example, so the model frequently omits it inconsistently, and adds an explicit default and example value to the generated tool schema.
OpenAPI schemas and function-calling interfaces evolve, and the latest OAS version may not match a service’s own document or a model endpoint’s supported schema. Keep the source document versioned, regenerate only curated operations, and run tests against the live contract before release. Human decisions remain necessary for tool exposure, authorization, confirmation, and user-facing descriptions; generation can assist mapping but cannot infer every business rule. Also retest permissions when user roles or API scopes change. Verify pagination, errors, and idempotency in execution.
Bản tin miễn phí
Ba câu chuyện AI đã được xác minh vào mỗi buổi sáng các ngày trong tuần, được viết bằng tiếng Anh đơn giản. Miễn phí mãi mãi, không có quảng cáo.
Một email mỗi ngày trong tuần. Hủy đăng ký trong một cú nhấp chuột. Chúng tôi không bao giờ bán hoặc chia sẻ địa chỉ của bạn.
Tự kiểm tra
Phản hồi tức thì về mọi câu trả lời và chứng chỉ có thể chia sẻ với ID có thể xác minh sau khi bạn vượt qua khóa học.
Hỗ trợ giáo dục AI miễn phí. AI Understanding là tổ chức phi lợi nhuận 501(c)(3) — không bao giờ có quảng cáo, không có tường phí. Hãy quyên góp
OpenAPI documents describe HTTP operations, parameters, request bodies, responses, and security schemes in a machine-readable format. Turning selected operations into LLM tools requires curating a safe surface, translating schemas, and keeping authorization and execution in application code.
The conversion maps REST endpoint structure and parameters onto the tool schema format models expect.
Curating down to a relevant subset reduces the risk of the model selecting an unsuitable or overlapping endpoint.
OpenAPI documents an HTTP interface, but the application must add context-specific confirmation and authorization rules for sensitive side effects.
OpenAPI 3.1 adopted a Schema Object based on JSON Schema 2020-12; OpenAPI 3.0 uses a different, restricted schema dialect, so conversion must account for the source version.
The model should provide arguments, not secrets. Application code should obtain credentials from the authorized user or service context and execute the call securely.
Tiếp tục học hỏi
Đã chọn thêm hướng dẫn cho chủ đề này
Tiếp theoHướng dẫn tiếp theo
Công cụ thiết kế dành cho đại lý LLM
kỹ thuật