বাহ্যিক Agent MCP ইন্টিগ্রেশন

বিশ্বস্ত server-side অ্যাপ্লিকেশন থেকে Manager AGI Agents-কে MCP tool হিসেবে ব্যবহার করুন। এই নির্দেশিকায় setup, authentication, downstream authorization, call, recovery এবং স্থিতিশীল ত্রুটি contract রয়েছে।

দ্রুত শুরু

1. Web Admin-এ সক্রিয় third-party অ্যাপ্লিকেশন তৈরি করে company যুক্ত করুন এবং App ID ও App Secret নিন।
2. company-তে সক্রিয় Agent এবং কার্যকর published Skills assign করুন।
3. MCP Streamable HTTP client-কে Engine HTTPS host-এর POST|GET|DELETE /openapi/v1/agents/mcp endpoint-এ যুক্ত করুন।
4. initialize করে notifications/initialized, tools/list, তারপর agent_{id} পাঠান।

সাধারণ assistant প্রকাশিত হয় না। Secret শুধু server-এ রাখুন।

Authentication ও authority scope

API environment:

• Test: https://aim-api-test.proton-system.com
• Production: https://aim-api.proton-system.com

প্রতিটি অনুরোধে নিচের headers দিন:

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

কাস্টম রিকোয়েস্ট হেডার সমর্থনকারী রিমোট MCP ক্লায়েন্ট নিচের কনফিগারেশন ব্যবহার করতে পারে:

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

সক্রিয় অ্যাপ্লিকেশন company scope-এ স্থায়ী অনুমোদন পায়। এখন বা পরে assigned Agents এবং নতুন published Skills, write বা high-risk operation-সহ, human approval ছাড়াই পাওয়া যায়। CompanyRole এই authority কমায় না। Engine তবু status, assignment, publication, downstream authorization, schema/risk drift, validation, rate limit, idempotency এবং audit যাচাই করে।

Initialization ও session

initialize করে response header Mcp-Session-Id সংরক্ষণ করুন:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

পরের POST, GET ও DELETE-এ Mcp-Session-Id পাঠান। INVALID_MCP_SESSION এলে আবার initialize করুন।

Agent tools ও metadata

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

tool name হলো agent_{id} এবং prefix-এর পরে সম্পূর্ণ Agent ID থাকে। top-level title হলো Agent name; description-এ Agent description বা সেটি খালি হলে name থাকে। _meta.easyposAgent শুধু public id, name, description, iconUrl দেয়। authorizationRequirements-এ mcpHubId, mcpHubName, authType, status, expiresAt, authorized এবং authorization দরকার হলে Engine তৈরি authorizationUrl থাকে। Prompt, quick questions, Skill definitions, internal schemas বা credentials প্রকাশ পায় না।

Downstream authorization

status যখন MISSING বা REAUTH_REQUIRED, তখন Engine তৈরি authorizationUrl খুলুন; এর path /openapi/v1/mcp/authorization/start দিয়ে শুরু হয়। ব্যবহারকারী authorization শেষ করলে app আবার tools/list বা আগের tools/call চালায়; ACTIVE মানে Engine app-scoped সংরক্ষিত authorization দিয়ে execute করতে পারে। মেয়াদ শেষ হলে বা downstream 401 এলে একই flow আবার করতে হবে। token refresh, downstream header পাঠানো বা failed business call automatic replay করা যাবে না।

Agent call

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"আজকের খোলা অর্ডারের সারাংশ দিন","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId required, trimmed এবং সর্বোচ্চ 128 UTF-8 bytes; message required এবং সর্বোচ্চ 16 KiB; conversationId optional এবং একই অ্যাপ্লিকেশন, company ও Agent-ই reuse করতে পারে। _meta.progressToken standard MCP progress চালু করে।

সফল result-এ "status":"COMPLETED", "answer", requestId, conversationId, metadata এবং authorizationRequirements থাকে। downstream credential না থাকলে isError:true, status:"authorization_required", errorCode:"MCP_AUTHORIZATION_REQUIRED" ফেরে এবং execution তৈরি হয় না।

SSE, resume, cancellation ও close

MCP progress এবং একটি final result গ্রহণ করুন। stream recovery-তে Basic-এর সঙ্গে Mcp-Session-Id, opaque Last-Event-ID, EasyPOS-Agent-Request-Id, EasyPOS-Agent-Id এবং Accept: text/event-stream দিয়ে GET করুন। replay Agent আবার চালায় না; event বাকি থাকলে নতুন cursor দিয়ে GET করুন।

explicit MCP cancellation শুধু cancel অনুরোধ করে; dispatched side effects rollback হয় না। transport disconnect accepted work cancel করে না। Basic ও Mcp-Session-Id সহ DELETE দিয়ে session বন্ধ করুন।

Limits ও idempotency

requestId প্রতি অ্যাপ্লিকেশনে 90 দিন idempotent। একই input নতুন execution unit ছাড়া result replay করে; ভিন্ন input IDEMPOTENCY_CONFLICT, চলমান অনুরোধ REQUEST_IN_PROGRESS দিতে পারে।

ত্রুটি contract

transport ত্রুটি HTTP এবং {"code":"COMPANY_INACTIVE","description":"The company is inactive."} ধরনের JSON দেয়। MCP/domain ত্রুটি isError:true, errorCode ও errorDescription দেয়। Description স্থিতিশীল, non-sensitive English text; program logic code-এর উপর রাখুন।

নিরাপত্তা ও troubleshooting

TLS ও secret manager ব্যবহার করুন, log থেকে authorization header সরান। browser, mobile, URL বা repository-তে App Secret রাখবেন না। server client-এ Origin বাদ দিন; দিলে সেটি অনুমোদিত HTTPS origin হতে হবে। leak হলে অ্যাপ্লিকেশন disable বা Secret reset করুন।

tools/list খালি হলে company, Agent, assignment ও published Skills দেখুন। authorization প্রয়োজন হলে authorizationUrl খুলুন এবং শেষ হলে discovery বা call আবার চেষ্টা করুন; invalid session আবার initialize করুন। notification callbackUrl Agent result channel নয়; MCP/SSE থেকে result পড়ুন।