LocalStack

LocalStack cấp cho agent quyền truy cập vào môi trường AWS mô phỏng để nó có thể cung cấp và thực hiện các dịch vụ AWS mà không cần chạm vào tài khoản thực. Nó nối dây AWS CLI sang LocalStack đang chạy ví dụ -- đưa điểm cuối, vùng và thông tin xác thực -- và có thể tùy ý bắt đầu và dừng bộ chứa LocalStack Docker cho mỗi lần chạy.

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.

vấn đề

Các agent xây dựng hoặc thử nghiệm cơ sở hạ tầng đám mây cần một nơi nào đó để tạo các nhóm, bảng, hàng đợi và hàm. Việc hướng chúng vào AWS thực sẽ chậm, tốn tiền, có nguy cơ rò rỉ thông tin xác thực và khó thiết lập lại giữa các lần chạy. LocalStack mô phỏng các API AWS cục bộ, nhưng việc kết nối một agent với nó có nghĩa là lặp lại điều tương tự bản tóm tắt: chèn URL điểm cuối, cung cấp thông tin xác thực giả, pháo kích ra AWS CLI và kiểm tra xem dịch vụ nào đang hoạt động.

Cách sử dụng

LocalStack hiển thị công cụ AWS được kết nối với phiên bản LocalStack đang chạy. các agent đưa ra các lệnh AWS CLI đơn giản; khả năng đưa vào điểm cuối, vùng, và thông tin xác thực, đồng thời bổ sung kiểm tra tình trạng cho các dịch vụ được mô phỏng.

from pydantic_ai import Agent
from pydantic_ai_harness import LocalStack

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[LocalStack()],
)

result = agent.run_sync('Create an S3 bucket called reports and list all buckets.')
print(result.output)

Theo mặc định, agent kết nối với phiên bản LocalStack mà bạn đã bắt đầu riêng -- ví dụ với localstack CLI (localstack start). Các giá trị mặc định khớp với quy ước của LocalStack: cạnh điểm cuối http://localhost.localstack.cloud:4566 (giải quyết thành 127.0.0.1) và test / test thông tin xác thực. Đặt manage_container=True có khả năng khởi động và dừng vùng chứa Docker mới mỗi lần chạy.

Công cụ

Các lệnh chạy dưới dạng một vectơ đối số (không có shell), do đó các toán tử shell và chuyển hướng trong chuỗi lệnh không có hiệu lực. Đầu ra được dán nhãn với [stdout] / [stderr] dấu hiệu và một [exit code: N] dòng trên lối ra khác không. Khi nó vượt quá max_output_chars đuôi được giữ nguyên (thả đầu), vì vậy lỗi tồn tại cắt ngắn.

AWS CLI có thể đọc và ghi vào các tệp cục bộ thông qua các đối số như --body, file://, fileb://và s3 cp. Hãy coi khả năng này là cả hai Quyền truy cập của trình mô phỏng AWS và quyền truy cập AWS CLI vào hệ thống tệp của quy trình.

Kiểm soát dịch vụ

allowed_services và denied_services loại trừ lẫn nhau -- đặt một, không phải cả hai. Dịch vụ này là token không gắn cờ đầu tiên của lệnh (s3 trong s3 ls).

!!! cảnh báo "Nỗ lực hết mình, không phải ranh giới an ninh" Những cổng kiểm tra này sẽ ra lệnh cho agent chứ không phải những gì nó có thể tiếp cận. Để đảm bảo cứng nhắc, hãy tự định cấu hình LocalStack với dịch vụ hẹp nhất và hành vi IAM mà hoạt động cần và chạy agent ở mức độ cô lập ở cấp độ hệ điều hành.

Quản lý thùng chứa

Đặt manage_container=True và khả năng khởi động LocalStack Docker container cho mỗi lần chạy và dừng nó khi quá trình chạy kết thúc, do đó agent luôn nhận được môi trường trong lành, biệt lập. Docker phải được cài đặt và chạy.

from pydantic_ai_harness import LocalStack

LocalStack(
    manage_container=True,
    image='localstack/localstack',
    container_env={'DEBUG': '1', 'PERSISTENCE': '1'},
    startup_timeout=120.0,
)

Cổng cạnh của container (4566) được xuất bản trên cổng máy chủ từ endpoint_urlvà khả năng chờ điểm cuối tình trạng trước khi chạy bắt đầu, sau đó dừng vùng chứa khi nó kết thúc (ngay cả khi lượt chạy tăng lên). Mỗi lần chạy có vùng chứa riêng, vì vậy các hoạt động đồng thời của một agent cần có các cổng máy chủ riêng biệt hoặc một phiên bản được quản lý bên ngoài (manage_container=False).

Vì LocalStack 2026.03.0 là mặc định localstack/localstack hình ảnh là một hình ảnh yêu cầu token xác thực để bắt đầu (token Hobby/OSS miễn phí bao gồm cộng đồng sử dụng). Khi LOCALSTACK_AUTH_TOKEN được thiết lập trong quy trình hiện tại nó được tự động chuyển tiếp đến vùng chứa; một di sản LOCALSTACK_API_KEY giá trị được chuyển tiếp khi không có token xác thực nào được đặt. Giá trị xác thực được chuyển tiếp thông qua Môi trường Docker CLI thay vì được nhúng trong docker run lý lẽ. các mặc định localstack/localstack hình ảnh yêu cầu token để bắt đầu, do đó, hoạt động được quản lý cần một cấu hình. Để chạy tokenless, hãy đặt image vào thẻ từ trước yêu cầu về tài khoản, chẳng hạn như localstack/localstack:4.x thả ra.

Các dịch vụ được hỗ trợ bởi Docker như Lambda cần gắn ổ cắm Docker và một số dịch vụ dịch vụ hiển thị các cổng bên ngoài cổng (LocalStack dự trữ 4510-4559). Kích hoạt những điều đó một cách rõ ràng khi dịch vụ bạn kiểm tra yêu cầu chúng:

from pydantic_ai_harness import LocalStack

LocalStack(manage_container=True, service_port_range='4510-4559', mount_docker_socket=True)

Việc gắn ổ cắm Docker sẽ mang lại khả năng kiểm soát Docker cấp máy chủ chứa. Giữ mount_docker_socket=False trừ khi dịch vụ mô phỏng yêu cầu nó và chạy môi trường đã được tin cậy.

Vòng đời tương tự có sẵn độc lập dưới dạng trình quản lý bối cảnh không đồng bộ:

import asyncio

from pydantic_ai_harness.localstack import LocalStackContainer


async def main() -> None:
    async with LocalStackContainer(environment={'DEBUG': '1'}) as localstack:
        ...  # talk to localstack.endpoint_url


asyncio.run(main())

Cấu hình

from pydantic_ai_harness import LocalStack

LocalStack(
    endpoint_url='http://localhost.localstack.cloud:4566',  # edge endpoint (host port reused when managed)
    region='us-east-1',                    # region for the CLI and environment
    access_key_id='test',                  # LocalStack accepts any value
    secret_access_key='test',              # LocalStack accepts any value
    allowed_services=[],                   # allowlist (mutually exclusive with denied)
    denied_services=[],                    # denylist
    default_timeout=60.0,                  # seconds, per command and health check
    max_output_chars=50_000,               # output cap returned to the model
    aws_cli_path='aws',                    # CLI executable (e.g. 'aws' or 'awslocal')
    manage_container=False,                # start/stop a Docker container per run
    image='localstack/localstack',         # image used when managing the container
    host_address='127.0.0.1',              # host address for Docker port publishing
    service_port_range=None,               # e.g. '4510-4559' for non-gateway service ports
    mount_docker_socket=False,             # required by Docker-backed services such as Lambda
    container_name=None,                   # optional name for the managed container
    container_env={},                      # env vars for the managed container
    docker_path='docker',                  # Docker executable
    startup_timeout=120.0,                 # seconds to wait for the container to be ready
    include_instructions=True,             # add usage instructions to the prompt
)

AWS CLI phải được cài đặt và bật PATH (hoặc điểm aws_cli_path vào đó). Nếu nhị phân bị thiếu, aws_cli trả về một lỗi rõ ràng thay vì hủy bỏ chạy. Đặt include_instructions=False để bỏ qua văn bản nhắc nhở của khả năng khi bạn tự cung cấp.

Thông số agent (YAML/JSON)

LocalStack hoạt động với Pydantic AI thông số agent:

# agent.yaml
model: anthropic:claude-sonnet-4-6
capabilities:
  - LocalStack:
      endpoint_url: http://localhost.localstack.cloud:4566
      allowed_services: ['s3', 'dynamodb', 'sqs']

from pydantic_ai import Agent
from pydantic_ai_harness import LocalStack

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

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

Đọc thêm

• Tài liệu LocalStack
• Khả năng AI của Pydantic
• Bộ công cụ

Tham chiếu API

::: pydantic_ai_harness.localstack.LocalStack

::: pydantic_ai_harness.localstack.LocalStackToolset

::: pydantic_ai_harness.localstack.LocalStackContainer