observation

name	observation
description	Fetch the current world observation for this tick.

Observation

Purpose

You are a situated agent in a simulated world. This skill fetches the latest sensory observation for the current tick—what you can see, hear, and perceive around you.

Internal Logic (One Sentence)

Call the environment observation action for the current agent, then write natural-language perception to state/observation.txt and structured context to state/observation_ctx.json when available.

Research basis: references/research_basis.md.

Use When

Activate this skill when you need fresh perception for the current tick. Other skills may read state/observation.txt / state/observation_ctx.json if those files exist—there is no hard activation order.

Procedure

1. Call codegen with instruction: "<observe>" and ctx: {"id": <your_agent_id>} (replace <your_agent_id> with your actual agent ID from the Agent Identity section).
2. Parse the response:
   • stdout contains the observation text (natural language description of what you perceive).
   • ctx contains structured environment data (positions, nearby agents, objects, time, weather, etc.).
3. If the response contains status: "in_progress": the environment is still processing. Call done and resume next tick.
4. Write the observation to workspace for downstream skills:

workspace_write("state/observation.txt", <stdout text>)

5. If ctx contains useful structured data, also write it:

workspace_write("state/observation_ctx.json", <ctx as JSON string>)

Persisting perception

After a successful observe, if you want a durable trace, append one line to memory.jsonl with type: "observation" (or event) and a short factual summary. Skip if this tick’s perception duplicates the latest entry.

What Observation Contains

The observation text typically includes:

Location Information

• Where you are (building, street, park, etc.)
• Your current coordinates or position
• Available exits or directions

Nearby Entities

• Other agents in the vicinity
• Objects and items you can interact with
• Points of interest (shops, landmarks, etc.)

Environmental Context

• Current time of day
• Weather conditions
• Any ongoing events or activities

Available Actions

• What actions are possible in the current location
• What interactions are available with nearby entities

Re-observation After Actions

After performing any action via codegen, always re-observe to get the updated environment state:

1. Execute action via codegen
2. Check the response status
3. Call codegen with "<observe>" again
4. Update state/observation.txt and state/observation_ctx.json

This ensures the agent's internal state matches the environment state.

Observation Context Structure

The state/observation_ctx.json typically contains:

{
  "agent_id": 1,
  "position": {"x": 100, "y": 200},
  "location": "park_entrance",
  "nearby_agents": [
    {"id": 2, "name": "Alice", "distance": 5.2}
  ],
  "nearby_objects": [
    {"id": "bench_01", "type": "bench", "distance": 2.0}
  ],
  "time": {"hour": 10, "minute": 30},
  "weather": "sunny",
  "available_actions": ["move", "interact", "wait"]
}

Important Notes

• Prefer writing state/observation.txt every time you observe so the workspace stays self-consistent.
• If you skip observation, other skills have less grounding—work from profile + whatever files already exist.
• The ctx JSON may be large; you don't need to memorize it all—write it to state/observation_ctx.json and let readers pull fields as needed.
• If codegen returns an error, write a short note into state/observation.txt so later reads see what failed.

Write

Write state/observation.txt and, when structured context exists, state/observation_ctx.json.

Notes

This skill only produces observation artifacts (state/observation.txt, optional state/observation_ctx.json). Higher-level “agent state snapshot / replay logging” is considered system functionality rather than a human-like capability skill, and should be handled by the runtime/framework if needed.