ऐसे OpenAPI agent actions design करें जिन्हें agents सुरक्षित रूप से इस्तेमाल कर सकें

OpenAPI document agent को बता सकता है कि किसी endpoint को कैसे call करना है। लेकिन वह अपने आप यह नहीं बता सकता कि call का अर्थ क्या होना चाहिए, कब इंसान का हस्तक्षेप जरूरी है, या अस्पष्ट failure के बाद agent को कैसे व्यवहार करना चाहिए। हर documented operation को agent action मान लेने पर ऐसे tools बनते हैं जो demo में पूरे लगते हैं, लेकिन रोजमर्रा के इस्तेमाल में खतरनाक हो सकते हैं।

एक उपयोगी action endpoint से छोटा होता है। उसका उद्देश्य सीमित होता है, inputs ऐसे होते हैं जिन्हें agent उचित ठहरा सके, result ऐसा होता है जिस पर agent आगे काम कर सके, approval का फैसला consequence से जुड़ा होता है और failures के लिए स्पष्ट योजना होती है। किसी operation को agent से जोड़ने से पहले यह design work करें। पहली duplicate charge, गलती से हुए production change या leaked token के बाद इसे ठीक करना सीखने का बेहद खराब तरीका है।

Operation अभी agent action नहीं है

HTTP endpoint, OpenAPI operation और agent action अलग-अलग सवालों का जवाब देते हैं। लोग इन्हें इसलिए मिला देते हैं क्योंकि OpenAPI operation एक सुविधाजनक शुरुआत देता है, लेकिन ये अंतर तय करते हैं कि automation समझने योग्य बनी रहेगी या नहीं।

Endpoint /v1/deployments जैसा एक address होता है। Operation इसमें HTTP method जोड़ता है, इसलिए POST /v1/deployments, GET /v1/deployments से अलग होता है। Agent action इसके ऊपर human और operational contract जोड़ता है: यह किस goal के लिए है, कौन-से arguments स्वीकार करता है, क्या effects पैदा कर सकता है, success का evidence क्या होगा और consent किसे देना होगा।

OpenAPI Specification में Operation Object के operationId, parameters, requestBody, responses और security जैसे fields होते हैं। इन fields को evidence की तरह इस्तेमाल करें, automatic publication checklist की तरह नहीं। पूरी तरह specified schema वाला operation भी खराब agent action हो सकता है, अगर उसकी description harmless नाम के पीछे production effect छिपाती हो।

इन दो operations पर ध्यान दें:

GET  /v1/projects/{project_id}/builds/{build_id}
POST /v1/projects/{project_id}/builds/{build_id}/promote

पहला record retrieve करता है। दूसरा traffic बदल सकता है, artifacts publish कर सकता है या release channel बदल सकता है। Route केवल इस अंतर का संकेत देता है। Action design को इसे साफ शब्दों में बताना चाहिए।

मैंने teams को generic request tool expose करते देखा है, क्योंकि उनके API में पहले से साफ OpenAPI file थी। तब agent arbitrary paths, query strings और bodies बनाने की permission पा गया। यह action catalog नहीं है। यह business API के खिलाफ remote code execution है, बस punctuation थोड़ी बेहतर है।

किसी operation को expose करने से पहले यह वाक्य लिख सकें: «यह action [किसी खास काम] को [सीमित object] पर करता है और [resulting state के evidence] लौटाता है।» अगर manage, process या handle जैसे अस्पष्ट verbs के बिना यह वाक्य नहीं लिखा जा सकता, तो action अभी बहुत व्यापक है।

Request schema से नहीं, consequence से शुरुआत करें

Approval call के HTTP verb या उसके JSON body की सरलता के आधार पर नहीं, बल्कि उसके consequence के आधार पर होना चाहिए। छोटा POST भी irreversible obligation बना सकता है। बड़ा GET private data expose कर सकता है। DELETE केवल disposable draft हटा सकता है, जबकि PATCH बाकी सभी लोगों का access revoke कर सकता है।

Fields की समीक्षा से पहले effect को उन शब्दों में लिखें जिन्हें system के लिए जिम्मेदार व्यक्ति समझ सके। सोचें कि server call को दो बार चलाए, गलत object पर चलाए या agent की अपेक्षा से पाँच मिनट देर से चलाए तो क्या बदलेगा। ये सवाल routine retrieval और scrutiny वाले action के बीच अंतर दिखाते हैं।

Candidate operation की समीक्षा करते समय मैं consequence की चार classes इस्तेमाल करता हूँ:

• Observation: सीमित जानकारी fetch करता है और server पर कोई change नहीं करता।
• Reversible change: कुछ create, update या remove करता है और उसके लिए documented तथा व्यावहारिक undo path मौजूद होता है।
• External commitment: message भेजता है, paid job शुरू करता है, material publish करता है या customer-facing state बदलता है।
• Irreversible or broad change: records को स्थायी रूप से delete करता है, access rotate करता है, permissions बदलता है या कई objects को प्रभावित करता है।

ये classes permission model नहीं हैं। ये descriptions को ईमानदार बनाती हैं। create invoice operation external commitment है, भले ही request में केवल दो fields हों। restart environment broad change बन सकता है, जब एक environment में कई services हों।

Method name से safety का अनुमान न लगाएँ। Protocol के अर्थ में HTTP GET safe है, यानी client को इसके जरिए state change request नहीं करनी चाहिए। यह convention है, proof नहीं कि कोई खास server इसका पालन करता है। मुझे ऐसे diagnostic endpoints मिले हैं जो बार-बार call होने पर caches refresh करते थे, report generation शुरू करते थे और सीमित capacity खर्च करते थे। Verb जो संकेत देता है, उसके बजाय वास्तविक behavior test करें।

Action के effect और उसके result की sensitivity को भी अलग रखें। Access token fetch करना read-only हो सकता है, लेकिन वह value agent को लौटाना call control करने के उद्देश्य को खत्म कर देता है। Private customer record fetch करने पर approval जरूरी हो सकता है, भले ही API एक byte भी न बदले।

एक अच्छा action card दोनों dimensions को सरल भाषा में दर्ज करता है:

Action: promote_preview_build
Effect: Changes one named preview build into the staging release channel.
Scope: One project and one build ID.
Result: Release ID, resulting channel, and server timestamp.
Human consent: Required for every call.
Retry: Never retry automatically unless the server accepts the same idempotency token.

ऐसा card agent के code की एक line लिखे जाने से पहले ही missing API semantics दिखा देता है। अगर कोई यह नहीं बता सकता कि retry safe है या नहीं, तो action तैयार नहीं है।

Inputs की ऐसी सीमाएँ रखें जिन्हें agent बहस करके पार न कर सके

Agent action को अक्सर endpoint से छोटा input contract चाहिए। OpenAPI schemas types और structure बताते हैं, लेकिन agent को ऐसी constraints भी चाहिए जो creative arguments के जरिए task को फैलने से रोकें।

Deployment creation operation पर विचार करें। Raw API internal clients के लिए environment, artifact reference, region, replica count, environment variables, feature switches, labels और free-form configuration object जैसे कई options दे सकता है। हर field agent को देने से एक simple request unreviewed administration surface बन जाती है।

ऐसे inputs वाला action बनाएँ जो task से मेल खाता हो। अगर task है «tests पास करने वाले build को preview environment में deploy करो», तो agent को केवल project_id, build_id और छोटा reason चाहिए हो सकता है। Executor permitted environment चुन सकता है और action के scope से बाहर की हर चीज reject कर सकता है।

यह request shape boundary को स्पष्ट बनाता है:

{
  "project_id": "proj_4821",
  "build_id": "build_9017",
  "reason": "Preview requested after integration tests passed"
}

सिर्फ इसलिए target_url, arbitrary headers, raw request body या general options object न जोड़ें कि underlying endpoint इन्हें support करता है। हर escape hatch आपके carefully named action को फिर generic client बना देता है।

जो उपयोगी limits पहले से OpenAPI fields में उपलब्ध हैं, उनका इस्तेमाल करें। जब object में केवल named fields स्वीकार होने चाहिए, तो additionalProperties: false रखें। सचमुच छोटी allowed values की list के लिए enum इस्तेमाल करें। Identifiers का format तय हो तो length और pattern restrictions लगाएँ। जब executor किसी field का सुरक्षित अनुमान नहीं लगा सकता, उसे required करें।

उदाहरण के लिए, यह fragment unreviewed configuration fields को reject करता है और schema में intended scope दिखाता है:

DeployPreviewRequest:
  type: object
  additionalProperties: false
  required:
    - project_id
    - build_id
    - reason
  properties:
    project_id:
      type: string
      pattern: '^proj_[A-Za-z0-9]+$'
    build_id:
      type: string
      pattern: '^build_[A-Za-z0-9]+$'
    reason:
      type: string
      minLength: 8
      maxLength: 240

additionalProperties: false एक आम failure रोकता है: agent किसी दूसरे API example से सीखता है कि environment_variables भेजा जा सकता है, उसमें secrets या unsafe overrides रखता है और server चुपचाप उन्हें मान लेता है। Field को reject करने पर agent को surprise deployment के बजाय उपयोगी error मिलता है।

Schemas object-level authorization की जगह नहीं लेते। Valid project_id फिर भी task से बाहर के project का हो सकता है। Executor को जाँचना होगा कि requested object allowed account, workspace, repository या environment के भीतर है। यह check action executor के पास रखें, जहाँ यह agent की explanation पर निर्भर न हो।

Free text के साथ विशेष सावधानी रखें। Reason field reviewer की मदद कर सकता है, लेकिन उसे executor के लिए instruction channel न बनने दें। उसे audit annotation की तरह store करें। उसे commands, resource selectors या permission exceptions के लिए parse न करें।

Expected results को अगले decision में मदद करनी चाहिए

Agent को raw HTTP response context में डालने के बजाय ऐसा outcome चाहिए जिस पर वह reasoning कर सके। हर header, debug field और nested object लौटाने से confusion बढ़ता है और ऐसा data भी disclose हो सकता है जिसकी task पूरा करने के लिए agent को जरूरत नहीं थी।

Response codes चुनने से पहले success को business terms में define करें। Deployment action के उपयोगी result में deployment, उसकी state और वह location होनी चाहिए जहाँ server बाद की progress report करेगा। Record update में record की पहचान और बदले गए fields की पुष्टि होनी चाहिए। Deletion में target और recovery अभी संभव है या नहीं, यह स्पष्ट होना चाहिए।

Asynchronous operation का compact result ऐसा दिख सकता है:

{
  "status": "accepted",
  "deployment_id": "dep_2388",
  "project_id": "proj_4821",
  "build_id": "build_9017",
  "target": "preview",
  "operation_status": "queued"
}

यह response एक सटीक बात कहता है: server ने काम स्वीकार किया है, लेकिन deployment पूरा नहीं हुआ। इसे पाने के बाद agent को «deployed» नहीं कहना चाहिए। उसे अलग read-only status action इस्तेमाल करना चाहिए या user को बताना चाहिए कि operation queue में है।

यहीं कई OpenAPI documents agents को भ्रमित करते हैं। 202 Accepted का खास अर्थ है: server ने request को processing के लिए स्वीकार किया है, और processing शुरू या पूरी हुई हो, यह जरूरी नहीं। 202 को completed 200 जैसा success मानने से logs और user messages में गलत दावे बनते हैं।

Transport outcome और action outcome को अलग रखें। HTTP 200 के भीतर domain failure हो सकता है, जैसे { "state": "rejected", "reason": "build is not eligible" }। दूसरी ओर 409 Conflict agent को बता सकता है कि desired state पहले से मौजूद है। Action wrapper को ऐसे cases को explicit states के छोटे set में बदलना चाहिए, जैसे completed, pending, already_in_desired_state, rejected और unknown।

Uniformity का झूठा वादा न करें। कुछ APIs केवल opaque job ID लौटाते हैं, और यह ठीक है, अगर आप उसे resolve करने वाला status action expose करते हैं। गलती gap छिपाने में है। साफ-साफ बताएँ कि पहली call क्या स्थापित करती है और क्या स्थापित नहीं करती।

Agent को लौटने से पहले error detail filter करें। Server error में internal URLs, authorization headers, stack traces या किसी दूसरे user का data हो सकता है। Agent को ऐसी वजह चाहिए जिस पर वह काम कर सके, जैसे «build ID project ID से संबंधित नहीं है», साथ में human investigation के लिए safe correlation ID। उसे upstream exception page की जरूरत नहीं है।

Approval commitment के point पर होना चाहिए

जब call meaningful commitment बना सकती हो, तभी approval माँगें और approval screen में object तथा effect साफ दिखाएँ। Future powers के अस्पष्ट bundle के लिए एक बार approval लेना लोगों को ऐसे warning पर click करना सिखाता है जिसका वे मूल्यांकन नहीं कर सकते।

Session approval और call approval अलग समस्याएँ हल करते हैं। Session approval कहता है, «मैं इस agent process को पहचानता हूँ और इसके चलने तक इसे इस action set का इस्तेमाल करने देता हूँ।» Call approval कहता है, «मैं इस खास consequential request को अभी approve करता हूँ।» एक को दूसरे का विकल्प न बनाएँ।

Build status inspect करने वाला agent किसी को परेशान किए बिना एक घंटे चल सकता है। Build promote करने वाले agent को consent माँगते समय project, build ID, release channel और reason दिखाना चाहिए। Reviewer उस request का निर्णय कर सकता है। «Allow deployment tool» से उसे लगभग कुछ पता नहीं चलता।

Approval prompt को input validation का विकल्प न बनाएँ। अगर action agent को arbitrary destination या arbitrary permission scope specify करने देता है, तो reviewer को time pressure में बड़ा और बदलता हुआ payload समझना पड़ेगा। पहले inputs सीमित करें। फिर approval एक bounded action की पुष्टि करेगा।

सही frequency effect पर निर्भर करती है। Publish करने, access बदलने, external payment शुरू करने या broad production scope को छूने वाले actions के लिए हर call पर approval लें। Read-only calls या सीमित reversible changes के group के लिए session consent ठीक हो सकता है, लेकिन तभी जब reviewer के सामने process identity और action catalog स्पष्ट हों।

Sallyport इस अंतर को नए agent process के लिए session authorization और किसी खास credential के हर use पर optional approval के जरिए लागू करता है। इसका vault gate locked होने पर सभी actions को deny करता है, इसलिए approval locked secret store को accidental exception में नहीं बदल सकता।

ऐसी failures पर व्यक्ति से approval न माँगें जिन्हें software रोक सकता है। अगर build promotion के योग्य नहीं है, तो executor को approval request से पहले उसे reject करना चाहिए। Prompts legitimate choices के लिए हैं, malformed state पकड़ने के लिए थके reviewer से मदद माँगने के लिए नहीं।

Timeout unknown state बनाता है, retry instruction नहीं

Mutating request के बाद network timeout वह failure path है जो खराब agent action design को सामने लाता है। Agent ने request भेजी और फिर response खो दिया। Server ने कुछ नहीं किया हो सकता है, change पूरा कर दिया हो सकता है या अभी भी उसे process कर रहा हो सकता है। Agent अपनी पसंद का उत्तर मानकर truth नहीं जान सकता।

एक परिचित failure देखें। Agent customer, amount और request timeout के साथ POST /v1/invoices call करता है। Response आने से पहले connection टूट जाता है, जबकि server invoice commit कर चुका है। Agent timeout देखता है, उसी data के साथ retry करता है और server दूसरा invoice बना देता है। Audit log में लिखा है कि agent ने अपनी retry policy मानी, जो तकनीकी रूप से सही और operationally बेकार है।

Idempotency token तभी मदद करता है जब server उसे वास्तव में implement करता हो। Client intended action के लिए एक बार token बनाता है, initial request के साथ भेजता है और retry पर वही token भेजता है। Server को उस token को original request से bind करना होगा और effect दोहराने के बजाय original result या compatible conflict result लौटाना होगा।

Idempotency-Key: act_01HZX7FQ2Z9K8M6R4T3V1W0Y

Action wrapper को यह token agent की improvisation से दूर रखना चाहिए। इसे execution time पर बनाएँ, action attempt के साथ persist करें और केवल उसी attempt के लिए reuse करें। Agent-provided token collide हो सकता है, unrelated requests में reuse हो सकता है या prompt injection का एक और रास्ता बन सकता है।

अगर API में documented idempotency semantics नहीं हैं, तो timeout के बाद mutating operation को automatically retry न करें। unknown लौटाएँ, साथ में action identifier दें और server state देखने वाला read-only lookup action उपलब्ध कराएँ। अगर lookup नहीं है, तो request दोहराने से पहले human investigation जरूरी है। यह उत्तर असुविधाजनक लगता है क्योंकि स्थिति वास्तव में असुविधाजनक है। झूठी certainty इसे बेहतर नहीं बनाती।

OpenAPI Idempotency-Key नाम का header parameter document कर सकता है, लेकिन documentation server behavior की guarantee नहीं है। इसे जानबूझकर test करें: same token और payload दो बार भेजें, फिर उसी token के साथ बदला हुआ payload भेजें। Server को पहले pair को एक ही result तक पहुँचाना चाहिए और बदली request को reject या स्पष्ट रूप से handle करना चाहिए। अगर वह चुपचाप दोनों changes कर देता है, तो header केवल दिखावा है।

दूसरे failures के लिए अपने rules रखें। 401 और 403 को stop condition मानें, किसी दूसरे credential की तलाश का संकेत नहीं। 429 को केवल तब wait condition मानें जब API retry delay बताती हो या action की bounded backoff policy हो। Validation errors को agent तभी उपयोग कर सकता है जब error किसी permitted correction की पहचान करता हो।

Authentication agent को judgment नहीं देती

OpenAPI security declaration बताती है कि client API के सामने अपनी identity कैसे साबित करता है। यह नहीं बताती कि agent को operation चलाना चाहिए या नहीं, किसी खास object के लिए कौन-सा credential इस्तेमाल करना चाहिए या effect की human review जरूरी है या नहीं।

Specification का Security Requirement Object किसी operation को named security schemes से जोड़ता है। Bearer scheme client को authorization header भेजने के लिए कह सकती है। Basic authentication उसे credential header बनाने के लिए कह सकती है। यह transport authentication है। इससे ज्यादा अर्थ न निकालें।

चार सवालों को अलग रखें:

• इस action को कौन या क्या call करता है?
• Upstream API के साथ executor कौन-सा credential इस्तेमाल करता है?
• वह credential किन objects और effects की अनुमति देता है?
• कौन-से action attempts को कोई व्यक्ति approve करता है?

जब teams इन सवालों को मिला देती हैं, तो वे आमतौर पर agent को token देकर इसे authorization कहती हैं। फिर token tool output, shell history, debug logs, prompts या configuration file में दिखाई देने लगता है। उसे revoke करना एक cleanup project बन जाता है, एक action नहीं।

सुरक्षित design में credential executor के पास रहता है। Agent bounded action inputs देता है। Executor eligible credential चुनता है, उसे HTTP request में inject करता है, response evaluate करता है और filtered result लौटाता है। Action request करने के लिए agent को API key का plaintext जानने की जरूरत नहीं होनी चाहिए।

SSH पर भी यही नियम लागू करें। Agent को named host पर command request करने की जरूरत हो सकती है, लेकिन generic command और broadly trusted private key अधिकांश tasks से कहीं अधिक authority देते हैं। Action के उद्देश्य के अनुसार host identity, account, command form और output handling सीमित करें।

Sallyport HTTP calls और SSH commands के लिए इसी execution model का इस्तेमाल करता है: credentials encrypted vault में रहते हैं और agent को secret के बजाय action result मिलता है। यह design तभी मदद करता है जब आप narrow actions expose करें और उनके effects के अनुरूप approvals चुनें।

Action description को schema की सीमाओं से आगे की बातें बतानी चाहिए

OpenAPI descriptions महत्वपूर्ण हैं क्योंकि agents उन्हें instructions की तरह पढ़ते हैं, लेकिन prose को boundaries स्पष्ट करनी चाहिए, दूसरा और विरोधाभासी API contract छिपाना नहीं चाहिए। Enforceable limits schemas और executors में रखें। Descriptions से intent, consequence और वे conditions समझाएँ जिन्हें type system व्यक्त नहीं कर सकता।

Operations का नाम user के intended outcome के आधार पर रखें। getBuildStatus, getBuildById से अधिक बताता है। createPreviewDeployment, postDeployment से बेहतर है। नाम जरूरत से ज्यादा promise नहीं करना चाहिए। अगर server काम queue करता है, तो operation को deployBuild न कहें, जब तक result acceptance और completion का अंतर न बताए।

Description में वे details लिखें जिनका agent वरना अनुमान लगाता:

operationId: createPreviewDeployment
summary: Queue one tested build for the preview environment
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/DeployPreviewRequest'
responses:
  '202':
    description: Request accepted. Deployment work may still be pending.
  '409':
    description: The build already has a preview deployment or cannot enter preview.

Higher-consequence operations के लिए summary पर्याप्त नहीं है। Intended target, effect class, approval requirement, retry rule और result states को OpenAPI document के साथ रखे गए action metadata में दर्ज करें। अगर tooling आपका है तो x- extensions इस्तेमाल कर सकते हैं, लेकिन उन्हें private conventions की तरह स्पष्ट रूप से label करें। Standard OpenAPI parsers unknown extensions को ignore करेंगे, इसलिए executor को इन्हें enforce करना होगा, केवल display नहीं।

«Use with caution» जैसी description पर निर्भर न रहें। Caution human feeling है, executable rule नहीं। उसकी जगह सीमा लिखें: एक project, केवल preview, arbitrary environment variables नहीं, हर invocation पर approval और unknown result के बाद automatic retry नहीं।

Descriptions में यह भी बताना चाहिए कि agent को action कब refuse करना है। Promotion operation के लिए completed test run जरूरी हो सकता है। Data export के लिए customer-provided case reference जरूरी हो सकता है। Deletion operation से पहले lookup में object के draft होने की पुष्टि जरूरी हो सकती है। ऐसी preconditions बेकार prompts घटाती हैं और audit records को समझना आसान बनाती हैं।

Action को careless लेकिन capable operator के खिलाफ test करें

Happy-path test केवल यह साबित करता है कि हर assumption सही होने पर API काम करती है। Action को ऐसे test करें जैसे तेज और सक्षम operator के पास अधूरी context, stale identifiers हों और error के बाद खुद को दोहराने की आदत हो। Autonomous agents के fail होने का तरीका इतना मिलता-जुलता है कि यह test उपयोगी साबित होता है।

Disposable objects और intended executor जैसी permissions वाले account के साथ छोटा test fixture बनाएँ। फिर ऐसे cases चलाएँ जो boundaries को चुनौती दें:

• Unknown input field भेजें और पुष्टि करें कि executor उसे reject करता है।
• Allowed project या workspace से बाहर के object का request करें।
• Approval deny करें और पुष्टि करें कि upstream request नहीं हुई।
• Server के mutating request receive करने के बाद timeout force करें।
• Sensitive debug material वाला response लौटाएँ और पुष्टि करें कि filtering उसे हटा देती है।

केवल final API state न देखें। Human को दिखने वाला prompt, executor की exact request, agent को मिला result और audit record सभी review करें। Successful request भी action contract में fail हो सकती है, अगर prompt ने target छिपाया हो, result ने बहुत जल्दी completion का दावा किया हो या log denied request और upstream rejection के बीच अंतर न बता सके।

हर-call approval वाले action में ordering test करें। Executor को static constraints validate करनी चाहिए और meaningful request दिखाने के लिए पर्याप्त safe context resolve करना चाहिए, फिर consent माँगना चाहिए। उसे पहले request भेजकर बाद में approval नहीं माँगना चाहिए। साथ ही उसे hidden read calls की लंबी chain से ऐसा extra data expose नहीं करना चाहिए जिसकी final action को जरूरत नहीं है।

Revoked और expired credentials को जानबूझकर test करें। Executor को fail closed करना चाहिए, safe explanation लौटानी चाहिए और उसी unusable credential से बार-बार calls नहीं करनी चाहिए। Rejected credential पर retry loop logs भर सकता है, rate limits trigger कर सकता है और simple access problem को diagnose करना कठिन बना सकता है।

अंत में cancellation test करें। अगर user upstream job चलने के दौरान agent रोक देता है, तो record में पता होना चाहिए कि request भेजी ही नहीं गई, server तक पहुँची या unknown state में चली गई। Local agent process cancel करने से remote side effect जरूरी नहीं कि cancel हो जाए।

कम actions publish करें और हर action को defend करने योग्य बनाएँ

Generic API client के मुकाबले छोटा action catalog बेहतर होता है, क्योंकि हर action के साथ reasoned contract रखा जा सकता है। Operations जोड़ना आसान है। Truthful result semantics, object boundaries, approval prompts और failure behavior को बनाए रखना असली काम है।

सीमित status record retrieve करने वाले operation से शुरुआत करें। उसका नाम object को स्पष्ट करे, identifiers intended scope तक सीमित हों और केवल agent की जरूरत वाले fields लौटें। फिर एक reversible action जोड़ें और implement करने से पहले उसके retry तथा approval rules लिखने के लिए खुद को मजबूर करें।

किसी operation को agent action इसलिए promote न करें कि OpenAPI generator उसे एक दोपहर में expose कर सकता है। उसे तब promote करें जब आप बता सकें कि timeout के बाद क्या होगा, human किस चीज को approve करेगा, agent को क्या दिखाई देगा और बाद में कैसे साबित करेंगे कि कौन-सी request हुई थी। अगर इनमें से किसी उत्तर पर «agent शायद समझदारी से काम करेगा» निर्भर करता है, तो endpoint को catalog से बाहर रखें।