A perception module is an agent’s first contact with reality: it transforms a raw query into a structured task representation before any action occurs. It classifies the problem, extracts entities, flags ambiguities, and estimates complexity. section 10.2.3
A useful perception pass records:
- Task type, such as simple lookup, multi-step, contradictory, ambiguous, or compositional. section 10.2.3
- Extracted entities, including important nouns, concepts, and identifiers. section 10.2.3
- Ambiguities that could support multiple interpretations. section 10.2.3
- A complexity estimate from 0.0 to 1.0 that routes the query toward a fast path or the full cognitive cycle. section 10.2.3
Diagnosing an intermittent deployment failure
For a deployment pipeline that fails intermittently during high traffic despite increased timeouts, perception can classify the task as contradictory, estimate complexity at 0.75, extract deployment, intermittent failure, high traffic, and timeout thresholds, and flag the meaning of “intermittent.” This representation sends the query toward memory retrieval and hypothesis-based planning instead of a flat timeout search. section 10.3.3
Listing 10.2 02_perception_module.py
from agents import Agent
perception_agent = Agent(
name="Perception",
instructions="""You are the perception module of a cognitive agent.
Your job is to analyze a user query and produce a structured
understanding of the task BEFORE any action is taken.
For each query, determine:
1. task_type: Is this a simple_lookup, multi_step, contradictory,
ambiguous, or compositional problem?
2. extracted_entities: What are the key nouns, concepts, or
identifiers in the query?
3. complexity_estimate: From 0.0 (trivial) to 1.0 (highly complex).
Consider: number of steps needed, whether information must be
combined from multiple sources, whether the query contains
contradictions or ambiguity.
4. ambiguities: List anything in the query that could be
interpreted multiple ways.
Be honest about complexity. A question that looks simple but
requires cross-referencing is at least 0.5. A question containing
"but" or "however" or "already tried" is likely contradictory
and should be at least 0.6.
You do NOT answer the user's question. You only analyze it.""",
output_type=TaskRepresentation, #1
)
Inspect a typed implementation prompt that defines the perception module’s output fields and classification rules. section 10.2.3
