Python for AI Agents: APIs, Tool Calling, Validation and Error Handling Basics

What this project should demonstrate

A Python agent application must connect model requests to controlled functions and verifiable results. Start with a fictional order lookup and demonstrate the boundaries before adding more tools. The examples below distinguish model suggestions, application permissions and evidence from actual execution.

Core concepts to learn

Build a practice scenario

1. Define one read-only tool: use a fictional order-status lookup with a fixed input such as an order identifier. Return only the fields the task needs.
2. Validate before dispatch: check the requested tool name, required fields, types and allowed values. Reject an unknown tool or malformed arguments before calling the function.
3. Handle external failures: set a timeout and bound retries. Distinguish a missing record from an unavailable service; avoid retrying a state-changing operation unless duplicate execution is controlled.
4. Make approval explicit: keep the initial exercise read-only. If a later exercise adds updates, show the intended action for approval and test both approval and rejection paths.

Use sample, authorised or fictional data. Do not publish credentials, business data, account numbers or customer information in a portfolio. If a task has financial, security or production impact, include a review or approval step before any change.

Understand the tool-call loop before adding autonomy

In a typical client-tool workflow, the application describes available tools to the model. The model may return a structured request naming a tool and supplying arguments. Your Python application checks that request, executes an allowed function and returns a result associated with the original call. The model can then use the result to answer or request another step. Provider-specific message formats differ; use the SDK documentation for the provider and version you actually run.

For the order-status exercise, let the model request one lookup, while Python owns the allowed tool list and data access. Do not resolve arbitrary function names from model text or run a generated expression. The response saying that a lookup should happen is different from evidence that it happened. Keep the actual tool result and distinguish a successful lookup, no matching order, denied access and an unavailable service. Those outcomes should remain distinct in the final answer.

Validate meaning as well as JSON structure

Define an order identifier format and reject unexpected fields. Pydantic provides validation controls, including strict mode, but default validation may convert some compatible input values. Decide where conversion is useful and test the boundary explicitly. Strictness also depends on the type and whether input is validated from Python objects or JSON. A schema should document the contract; application rules must still check whether the signed-in user is permitted to access the requested order.

Validate the result returned by the lookup too. An upstream response may be valid JSON yet omit the status field or use an unfamiliar status value. Return a controlled error instead of asking the model to guess what the missing data meant. For a test fixture, include one ordinary order, one unknown identifier and one malformed upstream response. A complete run should demonstrate that only the ordinary order produces a confirmed status, with no fabricated delivery date in the other cases.

Separate service failures from retry decisions

Configure network timeouts deliberately. HTTPX distinguishes connection, read, write and connection-pool timeouts; a single timeout value should not be described as a complete wall-clock limit for the entire agent run. Add an overall application deadline and a maximum number of tool steps. Otherwise, repeated individually bounded requests can still make the total run unexpectedly long. Record which limit stopped a failed attempt so it can be diagnosed.

Retry only failures that your policy identifies as temporary. HTTPX’s transport retry setting handles connection errors and connection timeouts; it is not a universal retry mechanism for every response or failure. If an operation can change data, a lost response creates uncertainty: the change may have succeeded even though the client did not receive confirmation. Use an idempotency mechanism supported by the service, or check the operation’s state before another attempt. An order-status lookup avoids that complication in the beginner exercise.

Treat retrieved text as data, not permission

An order note might contain a sentence asking the agent to send a spreadsheet or reveal a key. The note is part of the retrieved record, not an instruction from the application owner. The Python permission checks and tool allowlist should remain authoritative. For the initial exercise, expose only the read-only lookup and return a narrow set of fields. Removing unnecessary capabilities is easier to test than relying on a long prompt to prevent their use.

Use a synthetic note containing an unrelated instruction as a regression case. The expected outcome is that the application reports the order information without executing the instruction. If a later project adds an update tool, show the exact target and proposed values to the user before the application’s approval gate permits execution. Test rejection and expired approval as carefully as approval. The model must not be able to approve its own proposal by including an approval flag in the arguments.

Measure reliable outcomes with a small evaluation set

Create ten fixed cases before changing the prompt: normal lookup, missing identifier, malformed identifier, unknown tool, inaccessible record, missing record, bad service output, timeout, unrelated instruction in a note and exhausted step budget. Record the expected decision and whether an external call should occur. Run these cases after each meaningful change and compare results. A more fluent final answer is not an improvement if it causes a forbidden call or turns an unknown status into a confident answer.

What should the logs contain? Keep a run identifier, tool name, sanitized outcome, duration and retry count. Record enough to reconstruct the decision without copying secrets or unnecessary personal data. When is the exercise complete? Another learner can reproduce the expected cases, identify the failed boundary and explain why the application stopped. That evidence demonstrates a dependable Python integration more clearly than describing it as a fully autonomous agent.

Official references

• Anthropic client-tool lifecycle
• Pydantic strict validation
• HTTPX timeout types
• HTTPX transport retries

What good work looks like

Keep a small regression set containing a valid request, an unknown tool, a missing identifier, malformed output and a timed-out call. Record the expected decision for each case. A model response proposing a tool call is a request for your application to validate; it should not bypass the application’s permissions or input checks.

Frequently asked question

What should a beginner practise after learning Python for AI agents?

Build one small, documented exercise that uses the concepts safely, validate the result, and explain the decisions and limitations. Repeating this cycle makes learning more reliable than collecting disconnected tutorials.