[FEATURE] Parcel Agent Core - LangGraph + Sentient Foundation Integration

[AGI-Corporation]

Summary

Implement the core ParcelAgent class — the autonomous AI entity at the heart of Sapient.X — using LangGraph for multi-step workflow orchestration and Sentient Foundation's sentient-70b model for reasoning, planning, and decision-making. Each parcel agent operates independently with full lifecycle management: it perceives metaverse environment data via MCP, reasons about optimal actions, executes trades and contract signings, and reflects on outcomes to improve future performance.

Roadmap Position: This is the foundational feature — all other features (#2 Wallet, #3 MCP Server, #4 Frontend) depend on the ParcelAgent being stable and testable.

---

Background & Motivation

Sapient.X is a platform where autonomous AI agents manage virtual parcels in a metaverse economy. Each agent must:

• Perceive its environment (parcel state, market prices, other agents)
• Reason about actions using a powerful LLM (Sentient Foundation sentient-70b)
• Execute multi-step workflows (trade → sign contract → update state)
• Remember past decisions and learn from outcomes

LangGraph provides the stateful, cyclical graph execution model needed for this agentic loop. The perceive → analyze → plan → execute → reflect cycle maps directly to LangGraph nodes with conditional edges for dynamic routing.

---

Objectives

• Create ParcelAgent class with full lifecycle management
• Integrate Sentient Foundation sentient-70b model
• Build LangGraph workflow: perceive → analyze → plan → execute → reflect
• Implement agent state management with dataclasses
• Add agent memory persistence using Redis
• Write comprehensive unit tests

---

Technical Architecture

LangGraph Workflow Design

[START]
   ↓
[perceive]  ← Fetches parcel data, market prices, agent messages via MCP tools
   ↓
[analyze]   ← Sentient-70b analyzes current state vs. objectives
   ↓
[plan]      ← Generates action plan (trade, hold, negotiate, sign contract)
   ↓
[execute]   ← Calls MCP tools: initiate_trade, sign_contract, broadcast_message
   ↓
[reflect]   ← Evaluates outcome, updates memory, logs reasoning
   ↓
[END] or back to [perceive] (loop)

Conditional edges:

• analyze → plan (if action needed) or analyze → reflect (if hold/wait)
• execute → reflect (always) or execute → perceive (if immediate re-evaluation needed)
• reflect → END (if max iterations reached) or reflect → perceive (continue loop)

Agent State Dataclass

@dataclass
class AgentState:
    parcel_id: str
    agent_id: str
    iteration: int
    
    # Environment perception
    parcel_data: dict
    market_prices: dict
    pending_messages: list[dict]
    
    # Reasoning
    analysis: str
    action_plan: dict
    
    # Execution results
    executed_actions: list[dict]
    trade_results: list[dict]
    contract_signatures: list[str]
    
    # Memory
    short_term_memory: list[dict]  # Last N decisions
    long_term_summary: str         # Redis-persisted summary
    
    # Control
    should_continue: bool
    error_state: Optional[str]

Sentient Foundation Integration

from langchain.chat_models import ChatOpenAI

sentient_llm = ChatOpenAI(
    base_url="https://api.sentient.xyz/v1",
    api_key=os.environ["SENTIENT_API_KEY"],
    model="sentient-70b",
    temperature=0.1,  # Low temp for consistent agent decisions
    max_tokens=2048,
)

System prompt strategy:

• Role definition: autonomous parcel agent in metaverse economy
• Available tools description (MCP tool schema)
• Current state injection (parcel data, wallet balance, market conditions)
• Structured output enforcement (JSON action plan)

---

Implementation Plan

Phase 1: Core Agent Structure (Days 1-2)

• Define AgentState dataclass in src/agents/agent_state.py
• Create ParcelAgent.__init__() with config validation
• Implement ParcelAgent.start() / stop() / reset() lifecycle methods
• Add agent registry for multi-agent coordination

Phase 2: LangGraph Workflow (Days 3-4)

• Build perceive_node() — calls MCP get_parcel_data, get_market_price, get_world_state
• Build analyze_node() — Sentient-70b reasoning with structured output
• Build plan_node() — action sequencing and priority ranking
• Build execute_node() — MCP tool calls with retry logic
• Build reflect_node() — outcome evaluation and memory update
• Wire nodes into LangGraph with conditional edges

Phase 3: Memory & Persistence (Day 5)

• Implement Redis-backed short-term memory (last 50 decisions)
• Add long-term memory summarization (call LLM to compress old memories)
• Implement state checkpointing (crash recovery)
• Add memory.py with AgentMemory class

Phase 4: Testing & Integration (Days 6-7)

• Write unit tests (mock LangGraph and Sentient LLM)
• Write integration tests with live MCP server (see [FEATURE] Route.X MCP Server - Parcel Plugin Implementation #3)
• Performance test: agent decision loop latency < 5s per cycle

---

Technical Requirements

Dependency	Version	Purpose
Python	3.10+	Runtime
langgraph	>=0.0.40	Workflow orchestration
langchain	>=0.1.0	LLM abstraction
langchain-openai	>=0.0.5	Sentient endpoint
redis	>=5.0.0	Agent memory persistence
pydantic	>=2.0.0	State validation
pytest-asyncio	>=0.23.0	Async test support

Environment Variables:

SENTIENT_API_KEY=      # Sentient Foundation API key
SENTIENT_BASE_URL=https://api.sentient.xyz/v1
REDIS_URL=redis://localhost:6379
MCP_SERVER_URL=http://localhost:8000
MAX_AGENT_ITERATIONS=10
AGENT_DECISION_TIMEOUT=30

---

Acceptance Criteria

• Agent can perceive environment data via MCP tools (get_parcel_data, get_market_price)
• Agent makes decisions using Sentient Foundation sentient-70b model
• LangGraph workflow completes a full perceive → analyze → plan → execute → reflect cycle
• All state transitions are logged with timestamps and reasoning
• Agent memory persists across restarts via Redis
• Agent handles errors gracefully (LLM timeout, MCP tool failure) without crashing
• 90%+ test coverage on parcel_agent.py, agent_state.py, memory.py
• Single agent decision cycle completes in < 5 seconds (p95)
• 10+ concurrent agents can run without resource contention

---

Files to Create / Modify

src/agents/
├── __init__.py          # Export ParcelAgent, AgentState
├── parcel_agent.py      # Main ParcelAgent class + LangGraph workflow
├── agent_state.py       # AgentState dataclass + state helpers
├── memory.py            # AgentMemory class (Redis-backed)
└── registry.py          # NEW: Multi-agent registry and coordination

tests/unit/
├── test_parcel_agent.py # Agent lifecycle, workflow nodes, error handling
├── test_agent_state.py  # NEW: State transitions and validation
└── test_memory.py       # NEW: Redis memory persistence (mock Redis)

---

Estimated Effort

Task	Estimate
Agent state + lifecycle	1 day
LangGraph workflow nodes	2 days
Sentient Foundation integration	0.5 days
Redis memory persistence	1 day
Unit tests (90% coverage)	1.5 days
Integration testing with MCP	1 day
Total	~7 days

---

Related Issues & Dependencies

• Depends on: [FEATURE] Route.X MCP Server - Parcel Plugin Implementation #3 (MCP Server must be running for perceive_node MCP tool calls)
• Blocks: [FEATURE] x402 Wallet + USDC Stablecoin Trading System #2 (Wallet trading requires execute_node in ParcelAgent)
• Blocks: [FEATURE] Frontend Dashboard - Next.js + 3D Parcel Visualization #4 (Frontend visualizes agent state from AgentState dataclass)
• Blocks: [TESTING] Complete End-to-End Test Suite & CI/CD Pipeline #5 (Test suite requires ParcelAgent to be stable)

---

References

• LangGraph Documentation
• Sentient Foundation API
• MCP Python SDK
• See Wiki: [[Agent-Architecture]] [[LangGraph-Workflow]]