StackOne

sử dụng StackOne khi một agent cần làm việc với một trong các ứng dụng kinh doanh được liên kết của người dùng, chẳng hạn như BambooHR, Lực lượng bán hàng hoặc Zendesk. Mỗi phiên bản nằm trong phạm vi một tài khoản được liên kết, đây là một kết nối được xác thực giữa StackOne và một nhà cung cấp.

Nguồn

Mặc dù Pydantic AI Harness có trên các bản phát hành 0.x nhưng API có thể thay đổi giữa các bản phát hành nhỏ; khi đó, cảnh báo ngừng sử dụng và hướng dẫn di chuyển ghi chú phát hành sẽ cho bạn (hoặc người đại diện của bạn) biết chính xác cách nâng cấp. Xem chính sách phiên bản.

Trước khi bạn bắt đầu

Thực hiện theo tài liệu StackOne tới:

1. Định cấu hình trình kết nối và liên kết tài khoản. Đối với thử nghiệm đầu tiên của bạn, chỉ kích hoạt các hành động đọc mà bạn cần.
2. Sao chép ID tài khoản được liên kết từ bảng điều khiển StackOne.
3. Tạo khóa API StackOne có thể thực thi các hành động.

Bạn cũng cần có khóa API cho mô hình mà nhân viên hỗ trợ của bạn sử dụng.

Cài đặt

uv add "pydantic-ai-harness[stackone]" "pydantic-ai-slim[openai,spec]"

các openai và spec các tính năng bổ sung hỗ trợ các ví dụ về mô hình và đặc điểm agent bên dưới. Cài đặt thêm nhà cung cấp cho một thay vào đó là nhà cung cấp mô hình khác.

Đặt thông tin xác thực trong shell nơi bạn sẽ chạy ví dụ:

export STACKONE_API_KEY='your-stackone-api-key'
export STACKONE_ACCOUNT_ID='your-linked-account-id'
export OPENAI_API_KEY='your-openai-api-key'

StackOne đọc STACKONE_API_KEY tự động. Ví dụ đọc STACKONE_ACCOUNT_ID rõ ràng là tài khoản ID không được mã hóa cứng. Bạn có thể vượt qua api_key= thay vào đó, hãy giữ bí mật ngoài tầm kiểm soát của nguồn.

Chạy agent đầu tiên của bạn

import os

from pydantic_ai import Agent
from pydantic_ai_harness import StackOne

agent = Agent(
    'openai:gpt-5',
    capabilities=[
        StackOne(account_id=os.environ['STACKONE_ACCOUNT_ID']),
    ],
)
result = agent.run_sync('List the first 5 employees')
print(result.output)

Theo mặc định, mô hình nhận được hai công cụ. Nó tìm kiếm một hành động phù hợp với yêu cầu, sau đó thực hiện ID hành động được trả về. Đầu ra cuối cùng phụ thuộc vào nhà cung cấp được liên kết và dữ liệu của nó.

Kiểm soát các hành động có sẵn

StackOne kiểm soát hành động nào được kích hoạt cho tài khoản được liên kết. Hãy coi cấu hình đó là quyền truy cập chính kiểm soát.

sử dụng actions khi bạn cũng muốn giới hạn những công cụ mà mô hình nhìn thấy. Các mẫu sử dụng Python fnmatch cú pháp, ở đâu * là một ký tự đại diện. Họ bỏ qua trường hợp và trận đấu đầy đủ {connector}_{action}_{entity} tên công cụ:

from pydantic_ai_harness import StackOne

StackOne(account_id='your-linked-account-id', actions=['*_list_*'])            # All matching list tools
StackOne(account_id='your-linked-account-id', actions=['workday_get_worker'])  # One exact tool

Vượt qua actions chọn lọc individual chế độ tự động. Kết hợp rõ ràng actions với tool_mode='search_execute' gây ra lỗi vì chế độ đó chỉ đăng ký các công cụ tìm kiếm và thực thi.

Chọn chế độ công cụ

trong search_execute chế độ, ID hành động được công cụ tìm kiếm trả về trong runtime và không nên đoán. trong individual chế độ này, tất cả các lược đồ công cụ đã chọn sẽ được gửi đến mô hình, vì vậy hãy lọc các bộ hành động lớn bằng actions.

Để loại bỏ các công cụ StackOne khỏi bối cảnh mô hình cho đến khi cần đến chúng, hãy chuyển defer_loading=True. Khả năng sử dụng id='stackone' theo mặc định để nó có thể được tải theo yêu cầu. Cung cấp cho mỗi trường hợp một sự khác biệt id khi một agent sử dụng nhiều tài khoản StackOne:

from pydantic_ai_harness import StackOne

StackOne(account_id='your-linked-account-id', defer_loading=True)

Kết quả công cụ lớn bị ràng buộc

Hành động của nhà cung cấp có thể trả lại lượng xuất khẩu lớn. Kết hợp StackOne với Giới hạn đầu ra công cụ khả năng giảm việc trả lại công cụ quá khổ trên toàn agent:

from pydantic_ai import Agent
from pydantic_ai_harness import StackOne, ToolOutputLimits

agent = Agent(
    'openai:gpt-5',
    capabilities=[
        StackOne(account_id='your-linked-account-id'),
        ToolOutputLimits(),
    ],
)

Yêu cầu phê duyệt

Phê duyệt không được kích hoạt tự động. Đối với các hoạt động cần xác nhận của con người, hãy sử dụng công khai StackOneToolset với phê duyệt công cụ của Pydantic AI:

import os

from pydantic_ai import Agent
from pydantic_ai_harness.stackone import StackOneToolset

stackone_tools = StackOneToolset(
    account_id=os.environ['STACKONE_ACCOUNT_ID'],
    actions=['workday_create_worker'],
).approval_required()

agent = Agent('openai:gpt-5', toolsets=[stackone_tools])

Xử lý các yêu cầu phê duyệt bị trì hoãn như được mô tả trong hướng dẫn được liên kết.

Xác định agent trong YAML hoặc JSON

Khả năng này cũng hoạt động với thông số agent của Pydantic AI cho YAML hoặc JSON. Giữ khóa API trong STACKONE_API_KEY thay vì lưu trữ nó trong tệp:

# agent.yaml
model: openai:gpt-5
capabilities:
  - StackOne:
      account_id: 'your-linked-account-id'
      actions: ['*_list_*']

from pydantic_ai import Agent
from pydantic_ai_harness import StackOne

agent = Agent.from_file('agent.yaml', custom_capability_types=[StackOne])

Vượt qua custom_capability_types để trình tải thông số kỹ thuật biết cách khởi tạo StackOne.

Sử dụng cấp độ thấp hơn StackOneToolset trực tiếp khi bạn cần Agent(toolsets=[...]) hoặc các trình bao bọc bộ công cụ khác.

tùy chỉnh base_url và có giá trị URL client các giá trị phải sử dụng HTTPS. Bộ công cụ thêm các tiêu đề xác thực và nối thêm tool-mode tham số truy vấn cho các giá trị URL khi nó vắng mặt. Nó gây ra lỗi khi URL tool-mode xung đột với chế độ đã định cấu hình vì việc viết lại sẽ làm mất hiệu lực các URL đã ký. Khi sử dụng search_execute với một chữ ký URL, bao gồm tool-mode=search_execute trước khi ký. Các máy khách dựng sẵn được sử dụng nguyên trạng; định cấu hình HTTPS của họ vận chuyển, xác thực, lựa chọn tài khoản và chế độ công cụ.

Tham chiếu API

::: pydantic_ai_harness.stackone.StackOne

::: pydantic_ai_harness.stackone.StackOneToolset