Skip to main content
This guide walks you through building a custom Python agent that interacts with the CRM Data Pipeline Environment from scratch. You will use the typed CRMDataPipelineEnvClient, the Pydantic action and observation models, and the REST API’s step-response cycle to clean, standardize, and merge messy CRM datasets. By the end you will have a working agent capable of scoring 0.99 (the maximum grader award) on Task 1 and the structural vocabulary to tackle Tasks 2 and 3.

Section 1: The CRMDataPipelineEnvClient

The client.py module exports CRMDataPipelineEnvClient, a typed wrapper around the environment’s REST API. It extends openenv.core.EnvClient and handles request serialisation, response parsing, and connection lifecycle for you. You never call the HTTP endpoints directly.
The client exposes two primary methods: A StepResult has three attributes:
The client is used as a context manager via .sync() to ensure the underlying connection is closed cleanly at the end of each episode:
CRMDataPipelineEnvClient includes a graceful ImportError fallback for openenv.core. If openenv-core is not installed, the client stubs out EnvClient and StepResult so the file still imports. Always install openenv-core for production use: pip install openenv-core.

Section 2: The Episode Loop Pattern

Every agent interaction with the environment follows the same canonical pattern: reset → observe → decide → step → repeat until done=True or you exceed the step budget.
Set TASK_ID as an environment variable before calling reset(). The server reads it at reset time to load the correct dataset. You cannot change the task mid-episode.

Section 3: Complete Task 1 Agent

Task 1 (t1) presents a single source table named web_forms containing customer records with inconsistent email casing, mixed date formats, dirty phone strings, and duplicate rows. The full cleaning sequence is:
  1. Profile the source to get null counts and type info
  2. Standardize email → lowercase and strip whitespace
  3. Standardize signup_date → ISO-8601 (YYYY-MM-DD)
  4. Standardize phone → digits only (EXTRACT_NUMBERS) or E.164 format
  5. Deduplicate by email (exact match)
  6. Drop rows with null emails
  7. Submit
Wire it into the episode loop by replacing decide_action with t1_agent:

Section 4: Reading the Observation Effectively

CRMPipelineObservation carries every signal your agent needs to decide its next action. Here is how to access each field:

Interpreting feedback strings

The last_action_feedback field is the fastest way to understand what the server did. Common patterns:

Section 5: The Full Action Type Reference

Every action is a CRMPipelineAction Pydantic object. Fields not relevant to a given action_type should be left as None (the default). The server serialises actions via model_dump_json(exclude_none=True).
EXECUTE_SQL is your most powerful action but also the riskiest. The server blocks DROP and DELETE keywords, but a SELECT that produces zero rows will result in a very low grader score. Always verify your SQL logic on a VIEW_SOURCE sample first.

Section 6: LLM-Based Agent Pattern

You can replace the rule-based decide_action function with an LLM call to make the agent generalize across unknown data distributions. The pattern below mirrors what inference.py does internally.
Combine with a rule-based fallback for resilience:

Section 7: Task 2 and Task 3 Patterns

Task 2 — Two-source merge

Task 2 requires you to clean both web_forms and legacy_db independently, then union them into a single merged_output table and deduplicate.

Task 3 — Three-source enterprise merge with conflict rules

Task 3 adds a third source (salesforce) and requires you to check obs.conflict_rules to understand how the grader expects conflicting column values to be resolved. The legacy_db source uses different column names (contact_email, home_phone, legacy_id) that must be aliased in SQL.

Section 8: Error Handling

Agents should be defensive. The server is lenient about bad actions (it returns a negative reward and an error feedback string rather than crashing), but your agent needs to recover gracefully.

Common error patterns and fixes

The server rejected your action. This usually means:
  • Wrong source name: Double-check obs.available_sources. SQL-created tables (e.g., web_forms_clean) only appear in available_sources after the EXECUTE_SQL that created them.
  • Wrong column name: Use PROFILE_SOURCE first to see exact column names. Legacy DB often uses contact_email instead of email.
  • Invalid strategy: Confirm the strategy string exactly matches the enum values in models.py (TO_DATETIME_ISO, not ISO_DATE).
The server accepted your submission but returned done=False. This happens when you call SUBMIT_PIPELINE before completing at least 3 meaningful cleaning steps. The server enforces a minimum pipeline depth to prevent trivially submitting raw data.Check obs.last_action_feedback for a hint like "Pipeline too shallow — apply at least 3 transformations before submitting." Then continue cleaning before retrying SUBMIT_PIPELINE.
Your WHERE clause is too restrictive or uses wrong column names. Use VIEW_SOURCE after the SQL to inspect the resulting table:
If the view is empty, revise your SQL and run EXECUTE_SQL again with a different output_table name. Old table names remain valid in memory — you can overwrite them.
A score of 0.01 is the grader’s minimum — it means the grader could not match any rows. The most common causes:
  • You submitted the wrong final_source name (e.g., web_forms instead of merged_output for t2/t3).
  • Dates are still in MM/DD/YYYY format instead of YYYY-MM-DD — apply TO_DATETIME_ISO before submitting.
  • Phone numbers contain non-digit characters — apply EXTRACT_NUMBERS or PHONE_E164.
  • customer_id values contain '???' placeholders — filter them with EXECUTE_SQL.