API Documentation

Agent State

Overview

Agent State provides short-term, task-scoped storage for agentic workflows. Unlike memories (long-term facts), state tracks the agent's current working context: task progress, pending actions, and session variables.

Use cases: Multi-step task automation, workflow position tracking, pending tool call results, session variables, and resumable conversations.

PUT /state/:key

Create or update agent state for a given key.

Required Headers

  • X-Subject-ID: Subject/user identifier
  • value: JSON state to store (required)
  • ttl_seconds: Time-to-live in seconds (optional)
curl -X PUT "https://www.mnexium.com/api/v1/state/current_task" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Subject-ID: user_123" \
  -d '{\n    "value": {\n      "status": "in_progress",\n      "task": "Plan trip to Tokyo",\n      "steps_completed": ["research", "book_flights"],\n      "next_step": "book_hotels"\n    },\n    "ttl_seconds": 3600\n  }'

GET /state/:key

Retrieve agent state for a given key.

Required Headers

  • X-Subject-ID: Subject/user identifier
curl "https://www.mnexium.com/api/v1/state/current_task" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "X-Subject-ID: user_123"

Example Response

{
  "key": "current_task",
  "value": {
    "status": "in_progress",
    "task": "Plan trip to Tokyo",
    "next_step": "book_hotels"
  },
  "ttl": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-01T11:00:00Z"
}

DELETE /state/:key

Delete agent state (soft delete via TTL expiration).

Required Headers

  • X-Subject-ID: Subject/user identifier

State Injection in Proxy

Load and inject agent state into LLM context via the mnx.state config:

curl -X POST "https://www.mnexium.com/api/v1/chat/completions" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "x-openai-key: $OPENAI_KEY" \
  -d '{\n    "model": "gpt-4o-mini",\n    "messages": [{ "role": "user", "content": "What should I do next?" }],\n    "mnx": {\n      "subject_id": "user_123",\n      "state": {\n        "load": true,\n        "key": "current_task"\n      }\n    }  }

When state.load: true, the agent's current state is injected as a system message, allowing the LLM to resume tasks and avoid repeating completed work.

Key Naming Conventions

Recommended patterns for state keys:

  • current_task: Default key for general task state
  • task:onboarding: Named workflow state
  • tool:weather:tc_123: Pending tool call result
  • flow:checkout: Multi-step flow position