Agent-to-API Communication
When an agent calls an API, it follows a specific flow: the agent produces a tool call, the tool runner makes an HTTP request, the response is processed, and the observation is returned to the agent.
The Communication Flow
Step 1: The agent controller outputs a tool call
Example: {"tool": "get_weather", "args": {"city": "London"}}
Step 2: The tool runner maps the tool call to an API request
GET https://api.weather.com/v1/current?city=London&key=API_KEY
Step 3: The HTTP request is sent
Step 4: The API returns a response
{"temp": 18, "condition": "cloudy", "humidity": 72}
Step 5: The tool runner processes the response
Checks status code, extracts relevant fields, handles errors
Step 6: The tool runner returns an observation to the agent
{"status": "success", "city": "London", "temp_c": 18}
Step 7: The observation is added to the agent state
Step 8: The agent controller reads the observation and decides the next step
HTTP Methods
- GET: retrieve data without changing anything — safest for read actions
- POST: create a new resource or send data to be processed
- PUT: replace an existing resource entirely
- PATCH: update specific fields of an existing resource
- DELETE: remove a resource — irreversible, always require approval
- Rule: agents should prefer GET over POST when reading, and always confirm before DELETE
Key Takeaways
- When an agent calls an API, it follows a specific flow: the agent produces a tool call, the tool runner makes an HTTP request, the response is processed, and the observation is returned to the agent.
- GET: retrieve data without changing anything — safest for read actions
- POST: create a new resource or send data to be processed
- PUT: replace an existing resource entirely