Back to Docs

Protocol

filepath Agent Protocol (FAP): how agents communicate.

Overview

FAP is NDJSON (newline-delimited JSON) over stdin/stdout. Simple, debuggable, language-agnostic.

  • Agent reads from stdin
  • Agent writes to stdout
  • Each line is a JSON event
  • No HTTP, no gRPC—just pipes

Event Types

text

Agent sends text to the user

{"type":"text","content":"Hello from the agent"}

tool

Agent wants to call a tool

{"type":"tool","tool":"writeFile","args":{"path":"/workspace/readme.md","content":"# Hello"}}

command

Agent wants to run a shell command

{"type":"command","command":"npm install","timeout":60000}

spawn

Agent wants to spawn a child agent

{"type":"spawn","name":"Worker","agentType":"pi","task":"Research this topic"}

commit

Agent made changes, wants to commit

{"type":"commit","message":"Add feature X","files":["src/feature.ts"]}

done

Agent finished its task

{"type":"done"}

status

Agent status update

{"type":"status","state":"running"}

Input Events (to agent)

What the agent receives from filepath:

message

User sent a message

{"type":"message","content":"Write a function to...","id":"msg-123"}

Environment Variables

filepath sets these env vars for the agent:

  • FILEPATH_TASK — Initial task description
  • FILEPATH_API_KEY — API key for LLM calls
  • FILEPATH_MODEL — Model to use (e.g., claude-sonnet-4)
  • FILEPATH_AGENT_ID — Unique agent node ID
  • FILEPATH_SESSION_ID — Session ID
  • FILEPATH_PARENT_ID — Parent agent ID (if any)

WebSocket Protocol

For browser-to-agent communication, filepath uses Cloudflare's AIChatAgent protocol:

  • cf_agent_chat_messages — Full message list sync
  • cf_agent_use_chat_request — Send a message
  • cf_agent_use_chat_response — Streaming response chunks
  • cf_agent_stream_resuming — Resume interrupted streams
  • cf_agent_chat_request_cancel — Cancel current request

Connect to: wss://api.myfilepath.com/agents/chat-agent/{nodeId}