Building a Python Client for an Existing Agent

A Python application that invokes an existing agent has a different job from the code or configuration that defines the agent itself. This episode explains how a client identifies the intended Foundry project and agent, submits a user request, receives the response, and verifies…

A Python application needs to send a user’s question to an agent that already exists, receive the agent’s response, and display it. The application isn’t supposed to redesign the agent. It’s supposed to use it. That distinction sounds simple, but it affects which interface the application needs, what information it must provide, and what you should verify before calling the integration successful.

In Microsoft Foundry, Agent Service is a managed platform for building, deploying, and scaling artificial intelligence agents. An agent can combine a model with instructions and tools so that it performs a defined kind of work. The preceding design decisions still matter.

Instructions shape the agent’s behavior. Tools extend what it can do. Boundaries limit what it should be allowed to access or change. Once that agent has been created, a client application gives a person or another system a way to interact with it.

The client might be a Python program, a web application, or part of a larger business system. Its immediate job is to connect to the appropriate Foundry project interface, identify the intended agent, submit input, and handle the returned output. An agent reference supplies the identifying information needed to target that agent, including the applicable name or version in an implementation that uses those values.

The client and the agent therefore have different responsibilities. The agent definition contains the behavior being offered. The client supplies requests to that behavior and presents or processes the results.

This also separates an agent client from a direct model call. A direct model call asks a model to process supplied input. An agent interaction targets an agent whose instructions, model, and tools have already been assembled for a purpose. If your requirement is merely to generate text from a prompt, a direct model interface may be enough. If the requirement says to use an already-created agent with its established instructions and tools, bypassing that agent and calling a model directly fails to preserve the intended capability.

Foundry supports different agent approaches. A prompt agent is primarily defined through instructions, a model, and tools. A hosted agent is intended for situations that require custom code and greater control over the runtime. Choosing between those approaches concerns how the agent itself is built and operated.

It isn’t the same decision as writing a client that invokes an existing agent. A lightweight Python client doesn’t become a hosted agent merely because it contains Python code. Ask what the code is doing. If it’s sending a request to an existing agent and handling the reply, it’s acting as the client.

Start the implementation decision with the requirement rather than a product name. In this case, the input is a user’s question. The desired processing is the behavior of a particular existing agent. The output is the agent’s response in a form the Python application can display. The constraints include selecting the correct Foundry project, authenticating through an appropriate identity, targeting the intended agent, and preserving the safety boundaries that were chosen when the agent was designed.

That gives you a repeatable chain. First, state what the application receives. Second, identify the capability that must process it.

Third, select the interface that exposes that capability. Fourth, decide what observable result would demonstrate success. This is the four-stage decision pattern that applies across AI-901 scenarios. It keeps you from treating a familiar service name as an answer when the service’s actual behavior doesn’t match the workload.

For the Python application, the required capability is an interaction with a managed agent. Before choosing the implementation path, confirm that the agent exists in the intended Foundry environment and that you have a usable reference to it. You also need the project connection information and an identity that can use the relevant resources.

Foundry provides a unified project endpoint and a project client for working with project resources. It also provides an OpenAI-compatible client for supported model and response interactions. The right choice depends on which resource and operation the application must reach, not on which client name sounds more familiar.

Suppose the application receives the question, “Which support requests need attention today?” The agent has already been configured with instructions that define how to interpret support requests, along with any permitted tools. The Python client establishes access to the Foundry project, supplies the reference for that agent, and submits the user’s request through the supported project interfaces.

When a response comes back, the application extracts the returned content and displays it. That is the central flow. Connect, target, submit, receive, and handle.

Notice what the client does not need to decide during each request. It doesn’t need to invent a new set of agent instructions, select a different model, or attach tools again just to ask the existing agent a question. Those choices belong to the agent definition unless the intended design explicitly makes some part of them configurable. Repeating them in the client can create a second, competing source of truth. The application might claim to invoke the support agent while quietly sending different instructions to a model, producing behavior that only resembles the intended agent.

You should also account for operational constraints before treating the path as complete. Agent Service includes capabilities involving identity, networking, observability, and safety controls. A client that targets the right agent but can’t authenticate won’t complete the request.

A client that uses an endpoint outside the permitted network path may also fail. A response that arrives successfully may still violate the workload’s expectations if the wrong agent, wrong version, or wrong input was used. Technical connectivity is necessary, but it isn’t the whole definition of success.

Define the evidence before you run the client. You expect the request to reach the named or versioned agent that the workload specifies. You expect that agent to process the supplied question.

You expect the application to receive a response and display the relevant content. You may also expect observable request information through the platform’s monitoring or tracing capabilities, depending on what has been configured. If the application prints some text but you can’t establish which capability produced it, the text alone is weak evidence.

A first successful response should begin validation, not end it. Compare what happened with the input and output contract. Was the exact test question submitted? Did the application target the intended Foundry project?

Did it use the expected agent reference? Was a response returned without the client substituting a direct model call? Did the output fit the agent’s defined role and the purpose of the workload? These checks distinguish “the program printed something” from “the intended agent interaction worked.”

Imagine that the output is fluent but unrelated to support requests. Several explanations remain possible. The application may have targeted the wrong agent. It may have used an outdated or unintended version reference.

The request content may have been changed before submission. The agent’s configuration or permitted data may not support the expected task. The code may even have called a model directly while the developer assumed it was invoking the agent. A plausible sentence doesn’t tell you which explanation is correct.

Use the lowest-complexity check that can separate those possibilities. Confirm the project and agent reference used by the client. Compare the submitted input with the test question.

Inspect the returned status and available diagnostic evidence rather than relying only on the displayed text. If the application can issue a controlled request whose expected behavior is well understood, compare the result with that expectation. The goal isn’t to prove that every possible request will work. It’s to test the specific claim that the client reached the intended agent and handled its response correctly.

Now consider the common assumption that a client application must re-create the agent definition before every request. Under that design, the Python program would repeatedly specify the agent’s instructions, model, and tools, then submit the user’s question. That may produce plausible output, which makes the mistake easy to miss. But it doesn’t satisfy the stated requirement to invoke an already-created agent. It replaces reuse of the managed agent with repeated construction or imitation of its definition.

The more defensible rule is this: when the required agent already exists, the client should connect to the appropriate Foundry interfaces and target that existing agent through its supported reference. Agent creation and agent invocation are different operations. You might create or revise an agent as part of a separate management or deployment process. The ordinary request path doesn’t need to rebuild the definition merely because a new user message has arrived.

You can expose the mistaken assumption with a controlled change to the existing agent. Suppose its maintained instructions are updated through the intended lifecycle so that responses follow a revised support policy. If the client truly targets that agent and applicable version, its behavior should correspond to the referenced definition.

If the client keeps reconstructing an older copy of the instructions inside its own code, its output may continue following the old behavior. That discrepancy is evidence that the client and managed agent have drifted apart. It doesn’t by itself identify every cause, but it tells you that the claimed integration needs investigation.

The correction isn’t simply to delete configuration until the program runs. Reconnect the implementation to the requirement. Preserve a stable reference to the intended agent, use the project interface that supports the required interaction, and send the user’s input as the request.

Then repeat the controlled validation. Record which project, agent reference, input, and observed result were involved. If the evidence remains ambiguous, state that uncertainty rather than declaring the integration production-ready.

This matters because Agent Service manages more than a block of prompt text. The selected agent may rely on particular instructions, tools, identity arrangements, safety controls, or runtime behavior. Recreating only the visible instructions in an application doesn’t necessarily recreate the agent. It can omit the very boundaries and capabilities that made the managed agent appropriate. The result may look similar during a simple demonstration while behaving differently on requests that need a tool, encounter a safety boundary, or depend on the configured runtime.

Keep the scope of the client clear as the application grows. The client gathers or receives input, invokes the intended capability, and handles output. It may also manage application concerns such as presenting an error or recording an approved diagnostic detail.

Foundry manages the agent capability and provides the project interfaces used to reach it. The distinction helps you decide where to investigate. A malformed user request is an input problem.

An incorrect agent reference is an integration problem. An unavailable permission or network path is an access problem. Behavior caused by the agent’s maintained instructions is part of the agent configuration.

That classification prevents random troubleshooting. If no response returns, begin with the request path, endpoint, identity, permissions, and returned error evidence. If a response returns from the wrong agent, inspect project selection and the agent reference.

If the intended agent responds but the content doesn’t meet the workload requirement, compare the request with the agent’s supported capability, instructions, tools, data access, and boundaries. Don’t immediately rebuild the agent in every case. Match the symptom to the layer that could produce it.

The same discipline helps when selecting between a prompt agent and a hosted agent. If established instructions, a model, and supported tools meet the agent requirement, a prompt agent may fit. If the agent requires custom code and greater runtime control, a hosted agent may be appropriate.

But after that agent choice has been made and the agent is available, the client’s role remains interaction. A Python front end invoking a hosted agent is still a client. A Python front end invoking a prompt agent is also a client. The implementation language doesn’t determine the type of agent.

For an AI-901 scenario, build your explanation from the clues. The requirement says that an existing agent must answer a user’s question. That points to an agent client interaction. The capability is the managed agent in Foundry.

The implementation uses the appropriate project connection and agent reference to submit the request. A direct model call is rejected because it bypasses the established agent behavior. Re-creating the agent on every request is rejected because it confuses definition with invocation. Verification confirms which project and agent were targeted, what input was sent, and what response was observed.

This approach also carries forward the earlier concern with tools, instructions, and boundaries. A client shouldn’t silently broaden what the agent can do. If the established agent has limited permissions or a defined tool set, the client’s job is to use that design, not work around it. Identity, networking, safety, and observability remain relevant because the client is crossing a managed service boundary. A successful integration respects those controls while making the capability usable from application code.

Be precise about what a test proves. One controlled response can show that a particular request reached a capability and produced an observed result under those conditions. It cannot prove that every future input will be correct, that every safety risk has been addressed, or that the workload is ready for production. Broader assurance requires broader evidence. Within this lesson, the defensible conclusion is narrower: the client can target the intended agent, submit a request, receive output, and provide enough evidence to compare that behavior with the requirement.

The next application decision becomes much easier once these responsibilities are separated. You don’t begin by copying an agent definition into Python. You begin with the existing managed capability, identify how the project exposes it, provide the correct agent reference and input, and decide how you’ll recognize the expected response. If the evidence doesn’t match, you investigate the relevant layer and revise the decision before trusting the result.

An agent client application connects application code to an agent that has already been defined for a purpose. The sound decision starts with the required input and output, targets the intended agent through the appropriate Foundry project interface, and preserves the instructions, tools, and boundaries associated with that managed capability. It doesn’t rebuild the agent merely because another request arrives, and it doesn’t substitute a direct model call when the requirement depends on the agent.

Most importantly, success means more than displaying fluent text. Confirm the project, agent reference, submitted input, and observed response. When those pieces agree with the workload requirement, you have evidence that the client is using the intended capability rather than only producing a plausible result.

Before moving on, ask yourself: How does an agent client use an existing agent without recreating or bypassing its definition? Use the companion episode reference for Foundry project interface, agent reference, input submission, output handling, and agent-client responsibility boundaries. This lesson was produced by Bare Metal Cyber dot com.

Building a Python Client for an Existing Agent
Broadcast by