Serialization

How It Works

Tool results are serialized to strings before being sent back to the LLM as ToolResultMessage:

1. Objects/arrays — JSON.stringify()
2. Strings — passed as-is
3. Numbers/booleans — converted to string
4. Errors — formatted as error messages with isError: true

Input Deserialization

The LLM sends tool inputs as JSON. AgentForge:

1. Parses the JSON from the LLM response
2. Validates against the Zod input schema
3. Passes the typed, validated object to execute()

Output Serialization

After execute() returns:

1. Validates the output against the Zod output schema
2. Serializes to JSON string
3. Includes in the ToolResultMessage.content field

// Tool returns:
{ orderId: 'abc', total: 29.99 }

// LLM receives as ToolResultMessage:
{
  role: 'tool',
  toolCallId: 'call_123',
  name: 'create-order',
  content: '{"orderId":"abc","total":29.99}',
  isError: false
}

Error Serialization

When a tool throws:

{
  role: 'tool',
  toolCallId: 'call_123',
  name: 'create-order',
  content: 'Error: Order service unavailable',
  isError: true
}

The LLM sees the error and can decide to retry, use a different approach, or report the error to the user.

Next Steps

• Agents — use tools in agents
• Testing — test tool behavior