การรวมตัวแทนภายนอก

Edison Watch ให้ API และ SDK เพื่อรวมตัวแทน AI ภายนอก ช่วยให้คุณสามารถติดตามการเรียกใช้เครื่องมือ บังคับใช้นโยบายความปลอดภัย และตรวจสอบกิจกรรมของตัวแทนแบบเรียลไทม์

ข้อกำหนดเบื้องต้น

ก่อนรวมตัวแทนของคุณ:

1. เซิร์ฟเวอร์ Edison Watch ต้องกำลังทำงานและเข้าถึงได้
2. คีย์ API จากแดชบอร์ด (Settings → API Keys)
3. Python 3.8+ (สำหรับ Python SDK) หรือไคลเอนต์ HTTP (สำหรับ API โดยตรง)

เริ่มต้นอย่างรวดเร็ว (Python/LangGraph)

วิธีที่เร็วที่สุดในการรวมคือการใช้ Python SDK edison-watch พร้อมด้วยตัวตกแต่ง @edison.track()

การติดตั้ง

pip install edison-watch langgraph langchain-openai

ตัวแปรสภาพแวดล้อม

ตั้งค่าตัวแปรสภาพแวดล้อมเหล่านี้ (หรือส่งผ่านไปยังตัวสร้าง Edison):

export EDISON_WATCH_API_BASE="https://dashboard.edison.watch"  # URL เซิร์ฟเวอร์ Edison Watch ของคุณ
export EDISON_WATCH_API_KEY="your_api_key_here"
export OPENAI_API_KEY="your_openai_key"  # สำหรับตัวอย่าง LangChain

การรวมขั้นต่ำ

เพิ่มเพียง 4 บรรทัดเพื่อติดตามการเรียกใช้เครื่องมือของตัวแทนของคุณ:

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from edison_watch import Edison
 
# เริ่มต้น Edison (อ่าน EDISON_WATCH_API_KEY จาก env)
edison = Edison()
 
@tool
@edison.track()  # ตั้งชื่ออัตโนมัติ: agent_web_search
def web_search(query: str, max_results: int = 3) -> str:
    """Return up to N result URLs."""
    return "https://docs.python.org/3/"
 
@tool
@edison.track()  # ตั้งชื่ออัตโนมัติ: agent_fetch_url
def fetch_url(url: str, max_chars: int = 1000) -> str:
    """Fetch and return the first max_chars of the page."""
    import httpx
    return httpx.get(url, follow_redirects=True, timeout=10).text[:max_chars]
 
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agent = create_react_agent(model=llm, tools=[web_search, fetch_url])
 
result = agent.invoke({
    "messages": [("user", "Fetch the first 1000 chars of the CPython docs homepage.")]
})
print(result["messages"][-1].content)

ตัวตกแต่ง @edison.track() จะดำเนินการโดยอัตโนมัติ:

• ส่งข้อมูลเมตาการเรียกใช้เครื่องมือไปยัง Edison Watch ก่อนการทำงาน
• รอการอนุมัติหากการเรียกใช้กระตุ้นนโยบายความปลอดภัย
• บันทึกระยะเวลาและผลลัพธ์หลังการทำงาน
• ปรากฏในไทม์ไลน์ของแดชบอร์ด

การลงทะเบียนตัวแทน (ทางเลือก)

คุณสามารถเลือกที่จะลงทะเบียนตัวแทนที่มีชื่อใน Edison Watch เพื่อการจัดระเบียบและการติดตามที่ดีขึ้น สิ่งนี้มีประโยชน์เมื่อจัดการตัวแทนหลายประเภทหรือหลายบทบาท

สร้างตัวแทน

curl -X POST https://dashboard.edison.watch/api/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "name": "hr_assistant",
    "agent_type": "hr"
  }'

การตอบกลับ:

{
  "ok": true,
  "agent": {
    "id": 1,
    "name": "hr_assistant",
    "agent_id": "agent:a1b2c3d4e5f6...",
    "agent_type": "hr",
    "user_id": "user-uuid",
    "created_at": "2025-01-15T10:30:00",
    "updated_at": "2025-01-15T10:30:00"
  }
}

agent_id จะถูกสร้างขึ้นโดยอัตโนมัติในรูปแบบ agent:HEX (32 ตัวอักษรฐานสิบหก)

แสดงรายการตัวแทน

curl -X GET https://dashboard.edison.watch/api/agents \
  -H "Authorization: Bearer your_api_key"

การตอบกลับ:

{
  "agents": [
    {
      "name": "hr_assistant",
      "agent_id": "agent:a1b2c3d4e5f6...",
      "agent_type": "hr",
      "created_at": "2025-01-15T10:30:00"
    }
  ]
}

ลบตัวแทน

curl -X DELETE https://dashboard.edison.watch/api/agents/hr_assistant \
  -H "Authorization: Bearer your_api_key"

การตอบกลับ:

{
  "ok": true,
  "message": "Agent 'hr_assistant' deleted successfully"
}

อ้างอิง Edison SDK

คลาส Edison ให้ Python SDK สำหรับติดตามกิจกรรมของตัวแทน

ตัวสร้าง

from edison_watch import Edison
 
edison = Edison(
    api_base: str | None = None,           # อ่านจากตัวแปรสภาพแวดล้อม EDISON_WATCH_API_BASE หากไม่ได้ระบุ
    api_key: str | None = None,             # อ่านจากตัวแปรสภาพแวดล้อม EDISON_WATCH_API_KEY หากไม่ได้ระบุ
    timeout_s: float = 30.0,                 # หมดเวลาการรออนุมัติ
    healthcheck: bool = True,                # ตรวจสอบสุขภาพพื้นหลัง
    healthcheck_timeout_s: float = 3.0,      # หมดเวลาการตรวจสอบสุขภาพ
    agent_name: str | None = None,          # ข้อมูลประจำตัวของตัวแทน (เช่น 'hr_assistant')
    agent_type: str | None = None,           # ประเภท/บทบาทของตัวแทน (เช่น 'hr', 'engineering')
    session_id: str | None = None            # ID เซสชันคงที่ (สร้างอัตโนมัติหากเป็น None)
)

ตัวแปรสภาพแวดล้อม:

• EDISON_WATCH_API_BASE: URL เซิร์ฟเวอร์ (จำเป็น - ตั้งค่านี้เป็นเซิร์ฟเวอร์ Edison Watch ของคุณ)
• EDISON_WATCH_API_KEY: คีย์ API สำหรับการตรวจสอบสิทธิ์ (จำเป็น)

หากไม่ได้ระบุเป็นอาร์กิวเมนต์ของตัวสร้าง ค่าเหล่านี้จะถูกอ่านจากตัวแปรสภาพแวดล้อม

ตัวตกแต่งการติดตาม

ตัวตกแต่ง @edison.track() จะห่อฟังก์ชันเพื่อติดตามการทำงานของมัน:

@edison.track()
def my_tool(arg1: str, arg2: int) -> str:
    """Tool description."""
    return "result"

พารามิเตอร์:

• session_id: แทนที่ ID เซสชันสำหรับการเรียกนี้
• name: แทนที่ชื่อเครื่องมือ (ค่าเริ่มต้นคือชื่อฟังก์ชัน)

พฤติกรรม:

• เรียก /agent/begin ก่อนการทำงาน (การควบคุม + รอการอนุมัติ)
• ดำเนินการฟังก์ชัน
• เรียก /agent/end หลังการทำงานพร้อมสถานะ ระยะเวลา และสรุปผลลัพธ์
• ทำให้เกิด PermissionError หากถูกบล็อกและไม่ได้รับการอนุมัติ

การห่อเครื่องมือ LangChain

สำหรับเครื่องมือ LangChain ใช้ wrap_tools():

from langchain_core.tools import tool
 
@tool
def search_codebase(query: str) -> str:
    """Search the codebase."""
    return "results..."
 
tools = [search_codebase]
tracked_tools = edison.wrap_tools(tools)

หรือใช้ bind_tools() เพื่อห่อและผูกในขั้นตอนเดียว:

llm = ChatOpenAI()
llm_with_tools = edison.bind_tools(llm, tools)

การจัดการเซสชัน

เซสชันจัดกลุ่มการเรียกใช้เครื่องมือที่เกี่ยวข้องเข้าด้วยกัน โดยค่าเริ่มต้น อินสแตนซ์ Edison แต่ละตัวจะสร้าง ID เซสชันที่ไม่ซ้ำกัน แต่คุณสามารถแบ่งปันเซสชันได้:

# แบ่งปันเซสชันผ่านอินสแตนซ์ Edison หลายตัว
shared_session = str(uuid.uuid4())
 
edison1 = Edison(session_id=shared_session, agent_name="agent1")
edison2 = Edison(session_id=shared_session, agent_name="agent2")

คุณยังสามารถแทนที่เซสชันต่อการเรียก:

@edison.track(session_id="custom-session-id")
def my_tool():
    pass

HTTP API โดยตรง (ไม่ใช่ Python)

หากคุณไม่ได้ใช้ Python คุณสามารถรวมโดยตรงผ่านจุดสิ้นสุด HTTP

เริ่มติดตามการเรียกใช้เครื่องมือ

curl -X POST https://dashboard.edison.watch/agent/begin \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "session_id": "optional-session-id",
    "name": "web_search",
    "args_summary": "query: '\''python docs'\''",
    "timeout_s": 30.0,
    "agent_name": "hr_assistant",
    "agent_type": "hr"
  }'

การตอบกลับ:

{
  "ok": true,
  "session_id": "uuid-here",
  "call_id": "call-uuid-here",
  "approved": true,                         # false หากถูกบล็อก, null หากมีข้อผิดพลาด
  "error": null                             # ข้อความแสดงข้อผิดพลาดหาก ok=false
}

รหัสสถานะ:

• 200 OK: คำขอได้รับการดำเนินการ (ตรวจสอบฟิลด์ approved)
• 400 Bad Request: เนื้อหาคำขอไม่ถูกต้อง
• 401 Unauthorized: คีย์ API หายไปหรือไม่ถูกต้อง

สำคัญ: หาก approved เป็น false แสดงว่าการเรียกใช้เครื่องมือถูกบล็อกโดยนโยบายความปลอดภัย รอการอนุมัติด้วยตนเองในแดชบอร์ด หรือจัดการข้อผิดพลาดอย่างเหมาะสม

เสร็จสิ้นการติดตาม

หลังจากดำเนินการเครื่องมือ ให้เรียก /agent/end:

curl -X POST https://dashboard.edison.watch/agent/end \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "session_id": "uuid-from-begin",
    "call_id": "call-uuid-from-begin",
    "status": "ok",
    "duration_ms": 125.5,
    "result_summary": "Found 3 results..."
  }'

การตอบกลับ:

{
  "ok": true
}

การทำชื่อเครื่องมือให้เป็นมาตรฐาน

ชื่อเครื่องมือจะถูกนำหน้าโดยอัตโนมัติด้วย agent_ หากไม่ได้เริ่มต้นด้วย builtin_ หรือ agent_:

• web_search → agent_web_search
• agent_my_tool → agent_my_tool (ไม่เปลี่ยนแปลง)
• builtin_system → builtin_system (ไม่เปลี่ยนแปลง)

ตัวอย่าง: การรวมที่สมบูรณ์

async function trackToolCall(toolName, args, executeFn) {
  // EDISON_WATCH_API_BASE ต้องถูกตั้งค่าในสภาพแวดล้อมของคุณ
  const apiBase = process.env.EDISON_WATCH_API_BASE;
  if (!apiBase) {
    throw new Error('EDISON_WATCH_API_BASE environment variable is required');
  }
  const apiKey = process.env.EDISON_WATCH_API_KEY;
 
  // Begin tracking
  const beginResponse = await fetch(`${apiBase}/agent/begin`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      name: toolName,
      args_summary: JSON.stringify(args),
      agent_name: 'my_agent',
      agent_type: 'custom'
    })
  });
 
  const beginData = await beginResponse.json();
 
  if (!beginData.ok || !beginData.approved) {
    throw new Error(`Tool call blocked: ${beginData.error}`);
  }
 
  const startTime = performance.now();
  let status = 'ok';
  let result;
 
  try {
    // Execute the tool
    result = await executeFn();
  } catch (error) {
    status = 'error';
    throw error;
  } finally {
    const duration = performance.now() - startTime;
 
    // End tracking
    await fetch(`${apiBase}/agent/end`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        session_id: beginData.session_id,
        call_id: beginData.call_id,
        status: status,
        duration_ms: duration,
        result_summary: JSON.stringify(result).substring(0, 1000)
      })
    });
  }
 
  return result;
}
 
// Usage
const result = await trackToolCall(
  'web_search',
  { query: 'python docs' },
  async () => {
    // Your tool implementation
    return 'search results...';
  }
);

การตั้งค่าหลายตัวแทน

เมื่อเรียกใช้ตัวแทนหลายตัวที่มีบทบาทหรือสิทธิ์ต่างกัน ให้สร้างอินสแตนซ์ Edison แยกต่างหากที่มี agent_name และ agent_type ที่แตกต่างกัน:

from edison_watch import Edison
import uuid
 
# HR Assistant
edison_hr = Edison(
    agent_name="hr_assistant",
    agent_type="hr",
    session_id=str(uuid.uuid4()),
    api_key=api_key,
    api_base=api_base
)
 
# Engineering Copilot
edison_eng = Edison(
    agent_name="eng_copilot",
    agent_type="engineering",
    session_id=str(uuid.uuid4()),
    api_key=api_key,
    api_base=api_base
)
 
# ใช้ตัวอย่างที่แตกต่างกันสำหรับตัวแทนที่แตกต่างกัน
@edison_hr.track()
def hr_get_employee_profile(employee_id: str) -> str:
    """HR tool."""
    return f"Profile for {employee_id}"
 
@edison_eng.track()
def eng_search_codebase(query: str) -> str:
    """Engineering tool."""
    return f"Code search results for {query}"

กิจกรรมของตัวแทนแต่ละตัวจะถูกติดตามแยกต่างหากในแดชบอร์ด และคุณสามารถกำหนดสิทธิ์ที่แตกต่างกันต่อประเภทตัวแทนผ่านการตั้งค่าสิทธิ์ของแดชบอร์ด

การกำหนดค่าสิทธิ์

เครื่องมือที่ติดตามจะถูกตั้งชื่อด้วยคำนำหน้า agent_ ในระบบสิทธิ์ กำหนดค่าผ่านแดชบอร์ด Edison Watch:

1. ไปที่ Servers ในแดชบอร์ด
2. ค้นหาหรือสร้างเซิร์ฟเวอร์ agent (เครื่องมือที่ติดตามผ่าน SDK จะปรากฏภายใต้เซิร์ฟเวอร์นี้)
3. คลิกที่เครื่องมือแต่ละรายการเพื่อกำหนดค่าสิทธิ์

การตั้งค่าสิทธิ์:

สำหรับแต่ละเครื่องมือ คุณสามารถกำหนดค่า:

• Enabled: อนุญาตให้เครื่องมือทำงานหรือไม่
• Write Operation: เครื่องมือสามารถแก้ไขข้อมูลได้ (เช่น ส่งอีเมล สร้างไฟล์)
• Read Private Data: เครื่องมือเข้าถึงข้อมูลภายในที่ละเอียดอ่อน
• Read Untrusted Public Data: เครื่องมือประมวลผลเนื้อหาภายนอก/ไม่น่าเชื่อถือ
• ACL: ระดับการควบคุมการเข้าถึง (PUBLIC, PRIVATE, SECRET, TOP_SECRET)

ตัวอย่างการกำหนดค่า:

สำหรับเครื่องมือ web_search ที่ติดตามเป็น agent_web_search:

• Enabled: ✓
• Write Operation: ✗
• Read Private Data: ✗
• Read Untrusted Public Data: ✓
• ACL: PUBLIC

สำหรับเครื่องมือ send_email ที่ติดตามเป็น agent_send_email:

• Enabled: ✓
• Write Operation: ✓
• Read Private Data: ✗
• Read Untrusted Public Data: ✗
• ACL: SECRET

ธงความปลอดภัย:

• write_operation: เครื่องมือสามารถแก้ไขข้อมูลได้ (เช่น ส่งอีเมล สร้างไฟล์)
• read_private_data: เครื่องมือเข้าถึงข้อมูลภายในที่ละเอียดอ่อน
• read_untrusted_public_data: เครื่องมือประมวลผลเนื้อหาภายนอก/ไม่น่าเชื่อถือ

Lethal Trifecta: หากการเรียกใช้เครื่องมือรวมธงทั้งสาม (ข้อมูลส่วนตัว + เนื้อหาที่ไม่น่าเชื่อถือ + การเขียน) Edison Watch จะหยุดรอการอนุมัติด้วยตนเอง

ระดับ ACL:

• PUBLIC: ข้อมูลที่ไม่ละเอียดอ่อน
• PRIVATE: ข้อมูลความลับหรือภายใน
• SECRET: ข้อมูลละเอียดอ่อนสูง

การบังคับใช้: ข้อมูลไม่สามารถไหลจาก ACL ที่สูงกว่าไปยัง ACL ที่ต่ำกว่า (เช่น SECRET → PUBLIC)

ดู การตั้งค่าสิทธิ์ สำหรับคำแนะนำการกำหนดค่าโดยละเอียด

การจัดการข้อผิดพลาด

การเรียกใช้เครื่องมือที่ถูกบล็อก

หากการเรียกใช้เครื่องมือถูกบล็อกโดยนโยบายความปลอดภัย:

try:
    result = my_tracked_tool()
except PermissionError as e:
    # Tool was blocked and not approved
    print(f"Blocked: {e}")
    # Wait for approval in dashboard, or handle gracefully

ข้อผิดพลาดของเครือข่าย

SDK จัดการข้อผิดพลาดของเครือข่ายอย่างนุ่มนวลและบันทึกไว้ หาก Edison Watch ไม่สามารถเข้าถึงได้:

• การทำงานของเครื่องมือจะดำเนินต่อไป (การติดตามที่ดีที่สุดเท่าที่จะทำได้)
• ข้อผิดพลาดจะถูกบันทึกแต่จะไม่ทำให้เกิดข้อยกเว้น
• การตรวจสอบสุขภาพจะทำงานในพื้นหลังเพื่อตรวจจับการเชื่อมต่อ

การจัดการการหมดเวลา

หากการอนุมัติด้วยตนเองเกินเวลาที่กำหนด (ค่าเริ่มต้น: 30 วินาที):

edison = Edison(timeout_s=60.0)  # Increase timeout to 60 seconds

พารามิเตอร์ timeout_s ควบคุมระยะเวลาที่จะรอการอนุมัติก่อนที่จะเกิด PermissionError

แนวทางปฏิบัติที่ดีที่สุด

1. ใช้ชื่อตัวแทนที่สื่อความหมาย: hr_assistant, eng_copilot, finance_analyst
2. ตั้งค่าประเภทตัวแทน: จัดกลุ่มตัวแทนตามบทบาทเพื่อให้จัดการได้ง่ายขึ้น
3. แบ่งปันเซสชันอย่างเหมาะสม: ใช้ session_id เดียวกันสำหรับการเรียกใช้เครื่องมือที่เกี่ยวข้องในการสนทนา
4. จัดการการอนุมัติอย่างนุ่มนวล: การเรียกที่ถูกบล็อกควรรอการอนุมัติหรือล้มเหลวอย่างนุ่มนวล
5. กำหนดค่าสิทธิ์ล่วงหน้า: ตั้งค่าสิทธิ์เครื่องมือในแดชบอร์ดก่อนปรับใช้ตัวแทน
6. ตรวจสอบแดชบอร์ด: ตรวจสอบกิจกรรมของตัวแทนและปรับสิทธิ์ตามความจำเป็น

การแก้ไขปัญหา

401 Unauthorized

• ตรวจสอบว่า EDISON_WATCH_API_KEY ถูกตั้งค่าอย่างถูกต้อง
• ตรวจสอบว่าคีย์ API ใช้งานได้ในแดชบอร์ด

การเรียกใช้เครื่องมือถูกบล็อก

• ตรวจสอบสิทธิ์เครื่องมือในแดชบอร์ด (Servers → agent → Tools)
• ตรวจสอบว่าชื่อเครื่องมือตรงกัน (มีคำนำหน้า agent_)
• อนุมัติการเรียกที่ถูกบล็อกในแดชบอร์ดหากจำเป็น

การเรียกใช้เครื่องมือไม่ปรากฏในแดชบอร์ด

• ตรวจสอบว่าเซิร์ฟเวอร์ Edison Watch กำลังทำงานอยู่
• ตรวจสอบการเชื่อมต่อเครือข่ายไปยัง api_base
• ตรวจสอบบันทึกของเซิร์ฟเวอร์เพื่อหาข้อผิดพลาด

ความล้มเหลวในการตรวจสอบสุขภาพ

• ตรวจสอบให้แน่ใจว่า Edison Watch สามารถเข้าถึงได้ที่ api_base
• ตรวจสอบการตั้งค่าไฟร์วอลล์/เครือข่าย
• ตรวจสอบว่าเซิร์ฟเวอร์กำลังทำงาน: curl https://dashboard.edison.watch/health