This release is a pre-release and may not be stable for production use.
AgentField Python SDK
The AgentField SDK provides a production-ready Python interface for registering agents, executing workflows, and integrating with the AgentField control plane.
Installation
pip install agentfield
To work on the SDK locally:
git clone https://github.com/Agent-Field/agentfield.git
cd agentfield/sdk/python
python -m pip install -e .[dev]
Quick Start
from agentfield import Agent
agent = Agent(
node_id="example-agent",
agentfield_server="http://localhost:8080",
dev_mode=True,
)
@agent.reasoner()
async def summarize(text: str) -> dict:
result = await agent.ai(
prompt=f"Summarize: {text}",
response_model={"summary": "string", "tone": "string"},
)
return result
if __name__ == "__main__":
agent.serve(port=8001)
AI Tool Calling
Let LLMs automatically discover and invoke agent capabilities across your system:
from agentfield import Agent, AIConfig, ToolCallConfig
app = Agent(
node_id="orchestrator",
agentfield_server="http://localhost:8080",
ai_config=AIConfig(model="openai/gpt-4o-mini"),
)
@app.reasoner()
async def ask_with_tools(question: str) -> dict:
# Auto-discover all tools and let the LLM use them
result = await app.ai(
system="You are a helpful assistant.",
user=question,
tools="discover",
)
return {"answer": str(result), "trace": result.trace}
# Filter by tags, limit turns, use lazy hydration
result = await app.ai(
user="Get weather for Tokyo",
tools=ToolCallConfig(
tags=["weather"],
schema_hydration="lazy", # Reduces token usage for large catalogs
max_turns=5,
max_tool_calls=10,
),
)
Key features:
tools="discover"— Auto-discover all capabilities from the control planeToolCallConfig— Filter by tags, agent IDs, health status- Lazy hydration — Send only tool names/descriptions first, hydrate schemas on demand
- Guardrails —
max_turnsandmax_tool_callsprevent runaway loops - Observability —
result.tracetracks every tool call with latency
See examples/python_agent_nodes/tool_calling/ for a complete orchestrator + worker example.
MiniMax Video Generation
Set an API key and choose a video model from the MiniMax video API documentation:
export MINIMAX_API_KEY="..."
export MINIMAX_VIDEO_MODEL="..."
The global API base is used by default. Set MINIMAX_BASE_URL to select a region:
export MINIMAX_BASE_URL="https://api.minimax.io/v1"
# China: https://api.minimaxi.com/v1
Use the minimax/ model prefix to route the request to the MiniMax media provider:
import os
from agentfield import Agent, AIConfig
app = Agent(
node_id="video-agent",
agentfield_server="http://localhost:8080",
ai_config=AIConfig(
video_model=f"minimax/{os.environ['MINIMAX_VIDEO_MODEL']}",
),
)
result = await app.ai_generate_video(
"A camera moves through a futuristic city",
duration=6,
resolution="1080p",
)
result.videos[0].save("video.mp4")
Note: AIConfig(minimax_api_key=..., minimax_base_url=...) takes precedence over
the MINIMAX_API_KEY / MINIMAX_BASE_URL environment variables when both are set.
Human-in-the-Loop Approvals
The Python SDK provides a first-class waiting state for pausing agent execution mid-reasoner and waiting for human approval:
from agentfield import Agent, ApprovalResult
app = Agent(node_id="reviewer", agentfield_server="http://localhost:8080")
@app.reasoner()
async def deploy(environment: str) -> dict:
plan = await app.ai(f"Create deployment plan for {environment}")
# Pause execution and wait for human approval
result: ApprovalResult = await app.pause(
approval_request_id="req-abc123",
expires_in_hours=24,
timeout=3600,
)
if result.approved:
return {"status": "deploying", "plan": str(plan)}
elif result.changes_requested:
return {"status": "revising", "feedback": result.feedback}
else:
return {"status": result.decision}
Two API levels:
- High-level:
app.pause()blocks the reasoner until approval resolves, with automatic webhook registration - Low-level:
client.request_approval(),client.get_approval_status(),client.wait_for_approval()for fine-grained control
See examples/python_agent_nodes/waiting_state/ for a complete working example.
See docs/DEVELOPMENT.md for instructions on wiring agents to the control plane.
Running several agents in one process (AgentMesh)
from agentfield import Agent, AgentMesh
writer = Agent(node_id="writer")
editor = Agent(node_id="editor")
@editor.reasoner()
async def revise(text: str) -> dict:
return {"text": text.strip()}
@writer.reasoner()
async def draft(topic: str) -> dict:
return await writer.call("editor.revise", text=f"Draft about {topic}")
AgentMesh([writer, editor]).run(port=8000)
AgentMesh v1 is offline-only. See the AgentMesh guide
for mount layout, call_local, error behavior, and limitations.
Logging
AGENTFIELD_LOG_STDOUTcontrols the on-by-default structured JSON mirror. Set it to0,false,no, oroffto disable the mirror; execution-scoped records still dispatch to the control plane.AGENTFIELD_LOG_MAX_LINE_BYTESdefaults to 16384 bytes and clamps any integer below 256 to 256. It limits both captured stdout/stderr lines and structured-mirror records; non-integers use the default.AGENTFIELD_LOGS_ENABLEDcontrols stdout/stderr capture and the node logs endpoint only, not control-plane execution-log dispatch.AGENTFIELD_LOG_LEVELcontrols human-readable Python SDK logging and defaults toWARNING.
See the environment-variable reference and agent-node logs API for details.
Testing
./scripts/run_pytest.sh
To run coverage locally:
./scripts/run_pytest.sh --cov=agentfield --cov-report=term-missing
The wrapper sets a private PYTEST_DEBUG_TEMPROOT automatically so local runs
and CI do not rely on pytest's predictable default temp directory layout.
License
Distributed under the Apache 2.0 License. See the project root LICENSE for details.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file agentfield-0.1.139rc1.tar.gz.
File metadata
- Download URL: agentfield-0.1.139rc1.tar.gz
- Upload date:
- Size: 334.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a025062b6e3d5fba0bf94d41aca5d96425fb3ea59e869436ad32846a7a7c64ea
|
|
| MD5 |
56c773eb03ef0eb6912b9b0393b62eb6
|
|
| BLAKE2b-256 |
0bd6e4f40ee69f833be31addafb45b4e0a043cd002ac9e03e62f440c29b49766
|
File details
Details for the file agentfield-0.1.139rc1-py3-none-any.whl.
File metadata
- Download URL: agentfield-0.1.139rc1-py3-none-any.whl
- Upload date:
- Size: 369.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cf5d59fb5e3d9a09323e88da824f216c1c91327f6b95cfb9ee080baba5b93a11
|
|
| MD5 |
bb54158df4769213187c724100abd1db
|
|
| BLAKE2b-256 |
36e49f2378b71d26db55eb4f395fe3f36aca00235d4a525b58da1ad2b96e9599
|
