Building a custom component

I'd write a Python class on Langflow's Component base with a display name, description and typed inputs, such as customer ID, a region dropdown, a timeout and a secret input for the key that is bound to a global variable. I'd declare outputs that each map to a method. One returns structured Data for downstream components and one returns a Message for chat or Agent use. Inside, I'd make the HTTP call with a timeout and bounded retries on 5xx responses, and raise clear errors on 4xx. Before sharing it, I'd unit-test the methods with pytest against mocked responses, then test it on a canvas in the Playground. Finally I'd commit it to the shared components folder so every instance loads the same version.

A generic HTTP call puts the URL, headers, auth and parsing into every flow, so each team ends up with its own slightly different copy. A custom component holds that logic once. It has typed inputs, a secret input for the key, one timeout and retry policy, and clear error handling. It returns structured Data or a Message, so downstream components get a stable shape. It can be unit-tested with pytest and loaded from one version-controlled folder, so every flow and Agent runs the same code. You can switch it to tool mode for Agents. A fix or schema update ships in one place instead of being hunted down across dozens of flows.

The output method has to treat every failure path explicitly. I check the status code. A 4xx raises an error that says what was wrong with the request, such as an unknown customer ID or a bad region. A 5xx or timeout raises after the bounded retries run out. I also validate the response body against the fields I expect, and raise if they are missing, so a schema change cannot turn into an empty Data object. I never wrap the call in a broad except that returns an empty list or blank string. The pytest suite has cases for 4xx, 5xx, timeouts and schema changes that assert an exception is raised, so this behaviour cannot regress silently.

The model must never be the security boundary. Authorization belongs on the company API side, and the component should pass a caller identity the API can enforce against, not just a shared service key that can read everything. If the flow knows the authenticated user or tenant, that value should come from trusted flow inputs or server-side context, not from arguments the Agent invents. The component can also check that the requested customer ID belongs to the caller's scope before making the call. I also limit returned fields to what the use case needs. Prompt injection can make an Agent ask for anything, so least privilege has to hold at the API.

I treat it like a library. The component lives in a Git repository folder that every Langflow instance loads at startup as its custom components path, so there is exactly one source. Changes go through pull requests, pass tests and get merged. Deployments then pick them up, and rollback is just reverting the commit. I treat input and output names as a public interface. Renaming them breaks existing edges in saved flows, so I add new fields instead and deprecate the old ones. For apps calling flows over the run API, per-request settings go through tweaks rather than forked copies of the component. Traces tell me which flows actually use it before I change anything.

First, switch it to tool mode and write precise descriptions for the component and for each input. The Agent picks tools and fills arguments from that text. I'd keep the inputs minimal and validated, for example rejecting malformed IDs before calling the API. For read-only APIs that's mostly enough. For anything that writes or spends money, I'd keep it out of the Agent's tool list or require confirmation in the flow. Errors should come back as clear messages the Agent can reason about, not empty strings. Secrets never become tool inputs. Finally, I'd review Agent sessions in Langfuse or LangSmith to check that tool calls and arguments are actually correct.

Every request gets an explicit timeout, exposed as a typed input with a sensible default, so tweaks can adjust it per request. I retry only failures that are likely to be transient: connection errors, timeouts and selected 5xx or 429 responses. I use a small fixed maximum number of attempts, with exponential backoff and jitter. I never retry 4xx validation errors, because they will fail the same way again. The total time across all attempts has to stay under what the caller can wait, especially for an Agent or a synchronous API request. When retries run out, I raise an error that includes the last status and the attempt count. For write calls, retries also need idempotency keys.

I instantiate the component class, set its inputs directly, and call the output methods. The HTTP client is mocked, either by patching it or by using a transport-level mock library, so no network call happens and no real key is needed. The cases are: a success that returns correctly shaped Data; a 400 and a 404 with clear messages; a 500 that is retried and then raises; a timeout; a malformed or changed response schema that raises; and a check that the key is sent only in the auth header and never shows up in logs or error text. CI runs this suite before anything is merged into the shared components folder.

Avoid in-place breaking changes. If I need to rename an input, change an output shape or alter semantics, I add a new optional input with a default, or a new output, so existing flows keep working. If the change really cannot be backward compatible, I ship it as a new component class with a clear versioned display name and mark the old one as deprecated in its description. Teams then migrate deliberately. The change goes through code review and CI, merges into the shared folder, and reaches instances when they restart. Tracing tags let me confirm which flows still use the old version before I remove it.

Drift creeps back in a few ways. A builder edits the component code inside one flow on the canvas. Someone imports a flow exported from another instance that carries older code. Or one Langflow instance was not restarted after the folder changed. To catch it, I treat flows as artifacts too: export the flow JSON into version control, and have CI compare any embedded component code against the shared source. I make sure all instances load the same custom components path from the same commit, and I restart them during rollout. I also discourage inline edits through review. Tracing that records the component version lets me spot runs on unexpected versions in production.

I use several layers. In the Agent I keep the instructions focused and cap iterations, so it cannot loop forever. In the component, the bounded retries apply on every call, and I can add a simple per-process rate limit or short-lived cache for identical read requests. The tool description tells the model when calling is useful and when it is not, which cuts down speculative calls. Errors are returned as clear messages, so the Agent does not keep retrying a bad customer ID. On the API side, the company gateway should enforce rate limits per caller. Tracing shows tool-call counts per run, so runaway patterns are visible.

Retries are only safe when the operation is idempotent. For writes I generate an idempotency key per logical operation and send it with every attempt, assuming the company API supports one. The API then applies the change once even if a response gets lost and we retry. If the API has no idempotency support, I do not automatically retry non-idempotent calls after a timeout, because the first attempt may have succeeded. Instead I raise a clear error saying the outcome is unknown. For Agents, I would think hard about exposing writes as tools at all, and keep read and write operations as separate components so permissions can differ.

The Agent decides from text alone, so the descriptions are effectively the API contract for the model. The tool description should say what the tool does, when to use it, and what it returns, for example: looks up a customer's account status by customer ID within a region. Each input description should state the expected format, valid values and constraints, such as the allowed region options. I avoid vague names like data or query. I keep internal details out, especially anything about credentials. Then I test in the Playground with realistic questions to confirm the Agent picks the tool when it should and leaves it alone when it should not.

Tracing through Langfuse or LangSmith can capture customer IDs, personal details in responses, and anything else passed between components. I make sure the API key is never an input value that gets traced as plain text. It comes from a global variable through a secret input and is never logged. For personal data, I minimise what the component returns, mask or redact sensitive fields before they hit logs where possible, and check the tracing project's access controls and retention settings. Under Indian data protection rules and company policy, I would also check where the tracing backend stores data and whether self-hosting is needed.

Additive changes should be harmless. The component picks the fields it needs and ignores extras. A renamed or removed required field is a breaking change, and the component should raise a clear schema error naming the missing field rather than return Data with blanks. I validate the response against an explicit expected shape, for example with a small Pydantic model or explicit key checks. The pytest suite includes a changed-schema case to lock this in. Ideally a contract test against the staging API runs regularly too, so we hear about the change before production traffic fails and tracing shows the error spike.

First I filter traces for runs where this component failed or got slow, using its name and any version tag the component records. I look at when the change started and line that up with recent merges to the shared folder, instance restarts and the API team's deploys. Then I compare inputs between good and bad runs, checking whether it is one region, a certain timeout tweak, or Agent-generated arguments. Per-component latency shows whether the time is spent in our call or elsewhere in the flow. If one flow is affected and others are not, I check that flow for an outdated embedded copy. Then I reproduce it with a pytest case.

Because the secret input points at a Langflow global variable, no flow holds the key itself. Rotation happens in one place. Ideally the company API supports two valid keys at once. I issue a new key, update the global variable on each instance, confirm through tracing and a test flow that calls succeed, and then revoke the old key. If keys are environment-specific, I rotate dev, staging and production separately. Flows and exports do not change at all. If the key ever leaked, I would revoke it immediately and accept a brief error window, and the component's clear auth error makes that window obvious rather than silent.

The component should fail fast and clearly. Bounded retries with backoff, then a raised error, never empty results. During a long outage, retries from every request only add load and slow down every flow. A simple circuit breaker helps: after repeated failures it short-circuits for a cooldown period and raises an API-unavailable error immediately. In a multi-instance deployment each process has its own breaker state unless it is shared, which is acceptable for this purpose. Flows can then route on the error to tell users the service is unavailable. Tracing alerts tell the team, and the Agent gets a clear message instead of looping.

Return Data when downstream components need structured fields, such as a customer record with ID, region, status and balance. Parsers, conditional logic or other components can then read individual keys reliably. Return a Message when the result is going straight into a chat output or a prompt as text, for example a short summary for the user. A component can declare both outputs, each mapped to its own method, so builders pick the shape they need without duplicating API logic. Both methods should share one internal fetch function. That way retries, validation and error handling are identical whichever output a flow connects to.

Little's law is a good starting point: requests in flight equal arrival rate times average latency. As an illustration only, say flows call the component 20 times a second and each API call takes half a second. That is about 10 concurrent requests. Retries multiply this during incidents. With up to three attempts, a failing API can see roughly three times the load, which is why backoff and caps matter. Agents add more uncertainty, because one user question can trigger several tool calls. I would use real numbers from tracing data and the API team's rate limits, then size Langflow workers and any client-side limits from those.

Tweaks are powerful because they change component settings per request without editing the flow. So I decide deliberately what to rely on. Region and timeout are reasonable per-request overrides, and the component should validate them: region must be one of the dropdown values, and timeout must sit within a sane range. I would not design the flow to depend on callers overriding the API base URL or the credential. If base URL were a configurable input, an untrusted caller could redirect requests and leak data. Keep such values out of inputs, or restrict who can call the flow. Validation inside the component is the real safeguard, because tweaks bypass the canvas.

The audience gets wider. With an internal Agent you control the prompts. With MCP clients, any connected client and its model can discover and call the tool. So the tool and input descriptions must be accurate, and the server must require authentication so only approved clients can connect. The component's own validation and the API's authorization become even more important, because inputs come from systems you do not control. I would expose only read-safe flows at first, keep write operations separate, watch tracing for unexpected call patterns, and make sure error messages stay helpful without leaking internal URLs, stack traces or credential details.

A dropdown input constrains the choice on the canvas, but values can still arrive through tweaks, an Agent's tool call or an MCP client. So I validate again inside the output method. Region must be in the allowed list, and the customer ID must match the expected format. Timeout must be a positive number within a ceiling, so nobody sets ten minutes and ties up workers. Invalid values raise an error that names the input and lists the valid options. This is cheap, stops bad requests before they reach the API, and gives an Agent a message it can correct from instead of an opaque 400.

Unit tests prove the logic. The Playground proves the builder experience and the integration with real components. I check that the display name, description and icon make sense in the sidebar. Inputs should render with the right types: dropdown options, secret field masked, sensible defaults. I connect the outputs to downstream components to make sure Data and Message shapes work. I trigger error cases deliberately, such as a bad customer ID or a tiny timeout, and confirm the messages are clear and nothing is swallowed. I check the key does not appear anywhere visible. Finally I put the component in tool mode under an Agent and see whether it is chosen correctly.

The component code should be identical across environments. What changes is configuration. Each Langflow instance has its own global variable for the API key and a server-side setting for the base URL, ideally from environment configuration rather than an input any caller could tweak. Every instance loads the same version-controlled components folder, promoted from one commit through dev, staging and then production. Flows are exported and promoted the same way. This keeps behaviour reproducible: a bug in production can be reproduced on staging with the same code, and only the credentials and endpoint differ.

It matters because a blocking network call ties up whatever is executing the flow while it waits. If the server runs work on an event loop, a synchronous HTTP call with a long timeout can stall other runs. Langflow supports async methods on components, so for I/O-bound calls to an API I prefer an async HTTP client with an explicit timeout. That lets the server handle other requests while waiting. The trade-off is that async code is slightly harder to write and test. pytest needs async support, and mocks must be async-aware. Whichever I choose, the timeout and retry caps stay, because async does not make slow calls free.

Caching helps when the same read is repeated within a short window, for example an Agent looking up the same customer several times in one conversation. A short-lived in-memory cache keyed on customer ID and region cuts latency and API load. The risks are stale data, memory growth, and in a multi-instance deployment each instance having its own inconsistent cache. Data for one caller must never be served to another, so the key needs any identity scope as well. I would never cache errors as successes. For anything where freshness matters, such as balances or statuses, I would skip caching or keep the TTL very short, and document the behaviour in the component description.

All three need honest, specific errors, but the detail differs. Builders in the Playground benefit from the input name, the status code and a hint, such as region must be one of the listed values. An Agent needs a concise message it can act on, such as customer not found, so it can ask the user rather than retry blindly. A production API caller needs a failed run with a stable, recognisable error it can handle or alert on. In every case I exclude secrets, auth headers, full internal URLs and raw stack traces from the message. Full detail goes to tracing and server logs with proper access control.

Treat it like any shared library. Changes go through pull requests with code owners from the platform team and the API's owning team. CI runs the pytest suite, linting and a check that the component loads. Reviewers look specifically for secret handling, broad exception swallowing, missing timeouts and unreviewed new inputs that could be dangerous through tweaks. Releases are tagged, so instances load a known commit, and rollout follows dev, staging, then production with restarts. A changelog in the description or repository tells builders what changed. That discipline is what actually prevents drift, more than any single tool.

Depending on the error, the component may simply be missing from the sidebar, or flows that use it may fail to build. Either way, many teams are affected at once, which is the downside of sharing. Guards: CI imports every component module and instantiates the classes, so syntax errors and bad imports fail the build. Dependencies are pinned and installed in the Langflow image. Rollout is staged, so staging restarts first, and a smoke flow runs against it. Since instances load a tagged commit, rollback is just pointing back to the previous tag and restarting.

Mocks only prove the component matches my assumptions about the API. I would add contract tests that call the staging company API on a schedule and in CI before release. They check status codes, response fields and error shapes, so real schema changes surface early. A smoke flow on staging exercises the component end to end through POST /api/v1/run/<flow-id>, including a tweak, to catch integration and loading issues. For Agents, a small set of scripted prompts confirms tool selection still works. Production tracing then acts as the last safety net, with alerts on error rate and latency for this component.

Usually not. The component should be stateless: given its inputs, it calls the API and returns a result. Chat memory belongs to Langflow's message history, which is keyed by session ID and used by the flow or Agent to keep conversation context. Keeping state out of the component makes it safe to reuse across flows, easy to test, and correct under concurrency, since two sessions never share hidden variables. If the API genuinely needs a conversation or correlation identifier, I pass it as an explicit input. That way it is traceable and testable, rather than read from global state inside the component.

Several outputs on one component work well when they are different views of the same call, such as structured Data and a text Message from the same customer lookup. Each output maps to its own method, sharing one fetch. Separate endpoints with different purposes, especially reads versus writes, are better as separate components. That gives clearer tool descriptions for Agents, narrower inputs and different permissions. A write tool can then be withheld from an Agent while the lookup stays available. The cost is more classes to maintain, so I share the HTTP client, auth and error handling in a common helper module in the same version-controlled folder.

1. AOutputs are inferred automatically from the return type of __init__
2. BOutputs are configured only in the canvas UI, not in code
3. CAll outputs share one global run() function
4. DEach output declares the name of a method on the class that returns its valueCorrect answer

Why: A custom component declares its outputs in the class, and each output points to a method that computes and returns that output's value, such as Data or a Message.

1. AA LangSmith tracer class
2. BA pytest fixture class
3. CLangflow's Component base classCorrect answer
4. DA FastAPI router class

Why: Custom components are Python classes that subclass Langflow's Component base and declare inputs and outputs.

1. AReturn the string "OK"
2. BRaise a clear error that includes the statusCorrect answer
3. CRetry indefinitely until it succeeds
4. DReturn an empty Data object

Why: The workflow forbids hiding failures as empty successes, so a clear error is raised once the bounded retries are exhausted.

1. APut it in the component description
2. BPass it through a tweak on every request
3. CHard-code it as a class constant
4. DA secret input pointed at a Langflow global variableCorrect answer

Why: A secret input bound to a global variable keeps the key stored encrypted and out of flow JSON and exports.

1. AEdit the flow JSON and re-import it
2. BPass tweaks in the POST /api/v1/run/<flow-id> requestCorrect answer
3. CRestart Langflow with a new environment variable
4. DCreate a duplicate flow for each timeout value

Why: Tweaks in the run API request override component settings for that execution only, while the saved flow stays unchanged.

1. AIn a plain text input on the canvas
2. BIn a Langflow global variable referenced by a secret inputCorrect answer
3. CIn the component's description field
4. DAs a default value in the Python class

Why: Global variables keep credentials out of the code and out of exported flow JSON, and a secret input stops the value from being shown in the UI.

1. ARetry every error, including 400s, forever
2. BNever use a timeout so retries are not needed
3. CRetry only on successful responses
4. DBounded retries with backoff on transient failures such as timeouts and 5xxCorrect answer

Why: Only transient failures are worth retrying, and bounded attempts with backoff avoid overloading the API and blocking callers.

1. ATest only through the Playground
2. BCall the production API with the real key
3. CMock the HTTP client so no network call is madeCorrect answer
4. DSkip testing output methods

Why: The workflow uses pytest against a mocked HTTP client, covering success, 4xx, 5xx, timeouts and schema changes.

1. APaste the code into the Playground each time
2. BEach builder copies the code into their flow
3. CEmail the Python file to teams
4. DLoad a version-controlled folder through the custom components path at startupCorrect answer

Why: A version-controlled folder loaded at startup through the custom components path gives every instance the same code.

1. ARemove all its inputs
2. BConvert it into a webhook
3. CSwitch it to tool mode and give clear input descriptionsCorrect answer
4. DRename it to Agent

Why: The Agent component takes tools, including components switched to tool mode, and picks them using their descriptions.

1. ADELETE /api/v1/run/<flow-id>
2. BGET /api/v1/flows/export
3. CPOST /api/v1/run/<flow-id>Correct answer
4. DPUT /api/v1/components/<name>

Why: Flows are run through POST /api/v1/run/<flow-id>, with tweaks available to override component settings.

1. AAn idempotency key sent with every attempt, if the API supports itCorrect answer
2. BIncreasing the retry count
3. CRemoving the timeout
4. DReturning an empty success on timeout

Why: An idempotency key lets the API apply the change once even if the request is repeated after a lost response.

1. AIn the company API, based on a trusted caller identityCorrect answer
2. BIn the tool description text
3. CIn the Agent's system prompt only
4. DIn the component icon

Why: The model is not a security boundary. The API must enforce access based on identity it can trust.

1. ANone, because all flows share it automatically
2. BThat flow drifts onto a different copy of the codeCorrect answer
3. CThe API key is rotated
4. DTracing stops working everywhere

Why: Inline edits create a local copy that differs from the version-controlled component, which is the drift the workflow forbids.

1. AFill the field with an empty string and continue
2. BReturn the Data object without the field silently
3. CRaise a schema error that names the missing fieldCorrect answer
4. DCache the last good response forever

Why: Silently passing incomplete data is a hidden failure. A named schema error surfaces the change immediately.

1. AA log line
2. BDataCorrect answer
3. CA plain print statement
4. DAn exception

Why: Data carries structured fields that other components can read reliably, while a Message suits text for chat or prompts.

1. AJaeger and Zipkin only
2. BLangfuse and LangSmithCorrect answer
3. CPrometheus and Grafana only
4. DNo tracing is supported

Why: The workflow uses Langfuse or LangSmith to record each component run, its inputs and its latency.

1. AThe value is ignored and a random region is used
2. BThe component validates it and raises an error listing valid regionsCorrect answer
3. CThe flow is automatically edited
4. DThe dropdown guarantees this cannot happen

Why: Tweaks, Agents and MCP clients can bypass the canvas, so the component must validate inputs itself.

1. ACustomer ID with format validation
2. BTimeout within a capped range
3. CThe API base URLCorrect answer
4. DRegion from an allowed list

Why: An overridable base URL could redirect requests, and possibly credentials, to an attacker-controlled host.

1. AExposing flows as tools to MCP clientsCorrect answer
2. BEncrypting flow JSON exports
3. CReplacing the Playground
4. DRunning pytest automatically

Why: As an MCP server, Langflow exposes flows as tools that MCP clients can call.

1. AInside the custom component's class variables
2. BBy flow ID only
3. CThrough message history keyed by session IDCorrect answer
4. DThrough tweaks

Why: Message history gives chat memory per session ID, so the component itself can remain stateless.

1. AIt makes the icon disappear
2. BLangflow forbids any Python variables
3. CIt prevents tool mode
4. DConcurrent sessions could share or overwrite each other's stateCorrect answer

Why: Hidden shared state breaks correctness under concurrency and makes the component hard to test and reuse.

1. AAbout 0.025
2. BAbout 10Correct answer
3. CAbout 40
4. DAbout 2

Why: By Little's law, in-flight requests equal arrival rate times latency: 20 × 0.5 = 10.

1. AThey reduce latency
2. BThey hide the key
3. CThey multiply load on a failing API and tie up flow executionCorrect answer
4. DThey improve the success rate

Why: Each request retrying keeps hitting the broken API, adding load and slowing every flow that uses the component.

1. AThe list of valid region values
2. BThe API key or auth headerCorrect answer
3. CThe HTTP status code
4. DThe name of an invalid input

Why: Error text can reach users, Agents, logs and traces, so secrets must never be included.

1. AGenerating the flow ID
2. BChecking real rendering, connections, outputs and error messages on the canvasCorrect answer
3. CStoring the API key
4. DReplacing version control

Why: The Playground validates the builder experience and integration, which mocked unit tests cannot show.

1. ABy changing only the icon
2. BEdit it in place and restart all instances
3. CAs a new versioned component, with the old one marked deprecatedCorrect answer
4. DBy telling builders to edit their flows inline

Why: A separate versioned component lets teams migrate deliberately and avoids breaking existing flows.

1. AIncreasing the timeout
2. BA contract test against the staging APICorrect answer
3. CMore mocked tests with the old schema
4. DA Playground screenshot

Why: Contract tests exercise the real API's responses, so they catch schema changes that mocks cannot reveal.

1. ADeletes the component from the sidebar
2. BFails fast for a cooldown period instead of calling the APICorrect answer
3. CReturns cached empty results
4. DSwitches the flow to a different model

Why: A breaker short-circuits calls for a while and raises an immediate clear error, which protects the API and the callers.

1. ABy the tracing integration
2. BBy a tweak at run time
3. CBy the component icon
4. DBy mapping the output to a method on the classCorrect answer

Why: Each declared output names a method on the class that produces its value.

1. AIt avoids blocking execution while waiting on the networkCorrect answer
2. BIt removes the need for timeouts
3. CIt encrypts the request
4. DIt disables retries

Why: Async I/O lets the server do other work during the wait, though timeouts and retry caps are still needed.

1. AIn one component with a hidden write flag
2. BIn the Agent's prompt
3. CIn separate components, giving the Agent only the read toolCorrect answer
4. DIn tweaks sent by the Agent

Why: Separate components let you give the Agent only safe tools, rather than relying on the model to avoid a write path.

1. AShare the cache key across all regions
2. BCache errors as empty successes
3. CNever serve one caller's cached data to another unauthorised callerCorrect answer
4. DUse an unlimited TTL for balances

Why: The cache key must include identity scope, or the cache becomes a data leak between callers.